Mailing-List: contact tomcat-user-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Tomcat Users List" <tomcat-user@jakarta.apache.org>
Message-ID: <3FDE1EBB.5010002@yahoo.com>
Date: Mon, 15 Dec 2003 13:51:07 -0700
From: Patrick Taylor <patdtaylor2000@yahoo.com>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US;
 rv:1.5) Gecko/20031007
MIME-Version: 1.0
To: tomcat-user@jakarta.apache.org
CC: fjh@wir-age.de,  remm@jboss.org
Subject: tips on using the catalina "deploy" ant task (war vs localWar
 attribute)
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

I have been trying to use the catalina "deploy" ant task to deploy my 
web app to Tomcat 5.0 from a local directory structure (not a war 
file).  Unfortunately, this proved rather difficult, as this task is not 
documented very well at present.  After reading various bits of 
documentation and the source code of the ant task, I have finally 
figured out how to do it, and in the process learned several other 
undocumented facts.  I thought it would be a good idea to share my 
findings with the Tomcat community.

In short, the key to deploying a web app from a local directory *or* a 
local war file is to use the "localWar" attribute of the deploy task, 
not the "war" attribute.  The attribute value should be the path to the 
directory or the war file, prefixed with "file://", for example:

    localWar="file://${build.home}"

The "war" attribute of the deploy task can only be used with a war file, 
not a directory.  If you use this attribute, the deploy task uploads the 
contents of the war file to the server.  In other words, the war file 
will be *copied* to the server.  (If you just want your server to 
directly use the war file at the given path, you should use the 
"localWar" attribute, not the "war" attribute.)  Also, note the 
following facts about the value of the "war" attribute:

    - It can start with "file://", but (at least) on Windows, appears to 
require a third slash in the prefix, for example: "file:///c:/blah/foo.war".

    - It can be a simple path, for example, "c:/blah/foo.war".

    - In either case (using the "file:" syntax or not), on Windows, the 
path can use backslashes instead of forward slashes, or a mix, for 
example, "file:///c:\blah/foo.war".


Here are some more details, particularly regarding the documentation.

The javadoc for the org.apache.catalina.ant package contains some 
documentation about the ant tasks it defines:

    
http://jakarta.apache.org/tomcat/tomcat-5.0-doc/catalina/docs/api/org/apache/catalina/ant/package-summary.html

Unfortunately, this summary does not mention the "localWar" attribute, 
and incorrectly states that the "war" attribute can be used with a 
directory.

The javadoc for the deploy task is here:

    
http://jakarta.apache.org/tomcat/tomcat-5.0-doc/catalina/docs/api/org/apache/catalina/ant/DeployTask.html

It does mention both the "localWar" and "war" attributes, but suggests 
that these can only be used to deploy a war file -- it doesn't mention 
deploying from a directory.

Some key documentation about the Tomcat manager protocol is here:

    http://jakarta.apache.org/tomcat/tomcat-5.0-doc/manager-howto.html

The section "Deploy A New Application Remotely" describes the war upload 
protocol.  This protocol is used by the "deploy" task when the "war" 
attribute is specified.  In this case, the war file is uploaded using 
HTTP PUT.

The sub-section "Deploy A New Application from a Local Path", "Install a 
Directory or WAR by URL" describes the protocol used by the "deploy" 
task when the "localWar" attribute is specified.  In this case, the path 
to the local directory or war file is given by the "war" parameter in 
the URL using HTTP GET.   Yes, it is confusing that the "war" URL 
parameter is used when the deploy task specifies the "localWar" 
attribute, but not when it specifies the "war" attribute.

Unfortunately, the section "Executing Manager Commands With Ant" doesn't 
really help understand the deploy task.  In fact, the example deploy 
task in that section appears to be incorrect, as it specifies a 
directory using the "war" attribute, which doesn't work -- the 
"localWar" attribute must be used for a directory.

I hope some of you will find this information helpful.

- Patrick


---------------------------------------------------------------------
To unsubscribe, e-mail: tomcat-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tomcat-user-help@jakarta.apache.org