Enterprise Server Ant Tasks

Use the Ant tasks provided by the Enterprise Server for assembling, deploying, and undeploying modules and applications, and for configuring the server. The tasks are as follows:

• The sun-appserv-deploy Task

• The sun-appserv-undeploy Task

• The sun-appserv-instance Task

• The sun-appserv-component Task

• The sun-appserv-admin Task

• The sun-appserv-jspc Task

• The sun-appserv-update Task

• The wsgen Task

• The wsimport Task

The sun-appserv-deploy Task

Deploys any of the following to a local or remote Enterprise Server instance.

• Enterprise application (EAR file)

• Web application (WAR file)

• Enterprise Java Bean (EJB-JAR file)

• Enterprise connector (RAR file)

• Application client

Subelements of sun-appserv-deploy

The following table describes subelements for the sun-appserv-deploy task. These are objects upon which this task acts.

The sun-appserv-deploy Subelements

Element Description The server Subelement An Enterprise Server instance The component Subelement A component to be deployed The fileset Subelement A set of component files that match specified parameters

Attributes of sun-appserv-deploy

The following table describes attributes for the sun-appserv-deploy task.

The sun-appserv-deploy Attributes

Examples of sun-appserv-deploy

Here is a simple web application deployment script with many implied attributes:

<sun-appserv-deploy
file="${assemble}/simpleapp.war"
passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-deploy
 file="${assemble}/simpleapp.war"
 name="simpleapp"
 force="true"
 precompilejsp="false"
 verify="false"
 upload="true"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 target="${default-instance-name}"
 asinstalldir="${asinstalldir}" />

This example deploys multiple components to the same Enterprise Server instance running on a remote server:

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
         asinstalldir="/opt/sun" >
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"
     contextroot="test"/>
 <component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

This example deploys multiple components to two Enterprise Server instances running on remote servers. In this example, both servers are using the same admin password. If this were not the case, each password could be specified in the server element.

<sun-appserv-deploy passwordfile="${passwordfile}" asinstalldir="/opt/sun" >
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"
     contextroot="test"/>
 <component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

This example deploys the same components as the previous example because the three components match the fileset criteria, but note that it is not possible to set some component-specific attributes. All component-specific attributes (name and contextroot) use their default values.

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
         asinstalldir="/opt/sun" >
 <fileset dir="${assemble}" includes="**/*.?ar" />
</sun-appserv-deploy>

The sun-appserv-undeploy Task

Undeploys any of the following from a local or remote Enterprise Server instance.

• Enterprise application (EAR file)

• Web application (WAR file)

• Enterprise Java Bean (EJB-JAR file)

• Enterprise connector (RAR file)

• Application client

Subelements of sun-appserv-undeploy

The following table describes subelements for the sun-appserv-undeploy task. These are objects upon which this task acts.

The sun-appserv-undeploy Subelements

Element Description The server Subelement An Enterprise Server instance The component Subelement A component to be deployed The fileset Subelement A set of component files that match specified parameters

Attributes of sun-appserv-undeploy

The following table describes attributes for the sun-appserv-undeploy task.

The sun-appserv-undeploy Attributes

Examples of sun-appserv-undeploy

Here is a simple application undeployment script with many implied attributes:

<sun-appserv-undeploy name="simpleapp" passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-undeploy
 name="simpleapp"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 target="${default-instance-name}"
 asinstalldir="${asinstalldir}" />

This example demonstrates using the archive files (EAR and WAR, in this case) for the undeployment, using the component name (for undeploying the EJB component in this example), and undeploying multiple components.

<sun-appserv-undeploy passwordfile="${passwordfile}">
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-undeploy>

As with the deployment process, components can be undeployed from multiple servers in a single command. This example shows the same three components being removed from two different instances of the Enterprise Server. In this example, the passwords for both instances are the same.

<sun-appserv-undeploy passwordfile="${passwordfile}">
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-undeploy>

The sun-appserv-instance Task

Starts, stops, restarts, creates, or removes application server instances.

Subelements of sun-appserv-instance

The following table describes subelements for the sun-appserv-instance task. These are objects upon which this task acts.

The sun-appserv-instance Subelements

Element Description The server Subelement An Enterprise Server instance

Attributes of sun-appserv-instance

The following table describes attributes for the sun-appserv-instance task.

The sun-appserv-instance Attributes

Examples of sun-appserv-instance

This example starts the local Enterprise Server instance:

<sun-appserv-instance action="start" passwordfile="${passwordfile}"
 instance="${default-instance-name}"/>

Here is an equivalent script showing all the implied attributes:

<sun-appserv-instance
 action="start"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 instance="${default-instance-name}"
 asinstalldir="${asinstalldir}" />

Multiple servers can be controlled using a single command. In this example, two servers are restarted, and in this case each server uses a different password:

<sun-appserv-instance action="restart"
     instance="${default-instance-name}"/>
<server host="greg.sun.com" passwordfile="${password.greg}"/>
 <server host="joe.sun.com" passwordfile="${password.joe}"/>
</sun-appserv-instance>

This example creates a new Enterprise Server instance:

<sun-appserv-instance
 action="create" instanceport="8080"
 passwordfile="${passwordfile}"
 instance="development" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-instance
 action="create"
 instanceport="8080"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 instance="development"
 asinstalldir="${asinstalldir}" />

Instances can be created on multiple servers using a single command. This example creates a new instance named qa on two different servers. In this case, both servers use the same password.

<sun-appserv-instance
     action="create"
     instanceport="8080"
     instance="qa"
     passwordfile="${passwordfile}>
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
</sun-appserv-instance>

These instances can also be removed from their respective servers:

<sun-appserv-instance
     action="delete"
     instance="qa"
     passwordfile="${passwordfile}>
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
</sun-appserv-instance>

Different instance names and instance ports can also be specified using attributes of the server subelement:

<sun-appserv-instance action="create" passwordfile="${passwordfile}>
 <server host="greg.sun.com" instanceport="8080" instance="qa"/>
 <server host="joe.sun.com" instanceport="9090"
     instance="integration-test"/>
</sun-appserv-instance>

The sun-appserv-component Task

Enables or disables the following Java EE component types that have been deployed to the Enterprise Server.

• Enterprise application (EAR file)

• Web application (WAR file)

• Enterprise Java Bean (EJB-JAR file)

• Enterprise connector (RAR file)

• Application client

You do not need to specify the archive to enable or disable a component: only the component name is required. You can use the component archive, however, because it implies the component name.

Subelements of sun-appserv-component

The following table describes subelements for the sun-appserv-component task. These are objects upon which this task acts.

The sun-appserv-component Subelements

Element Description The server Subelement An Enterprise Server instance The component Subelement A component to be deployed The fileset Subelement A set of component files that match specified parameters

Attributes of sun-appserv-component

The following table describes attributes for the sun-appserv-component task.

The sun-appserv-component Attributes

Examples of sun-appserv-component

Here is a simple example of disabling a component:

<sun-appserv-component
 action="disable"
 name="simpleapp"
 passwordfile="${passwordfile}" />

Here is a simple example of enabling a component:

<sun-appserv-component
 action="enable"
 name="simpleapp"
 passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-component
 action="enable"
 name="simpleapp"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 target="${default-instance-name}"
 asinstalldir="${asinstalldir}" />

This example demonstrates disabling multiple components using the archive files (EAR and WAR, in this case) and using the component name (for an EJB component in this example).

<sun-appserv-component action="disable" passwordfile="${passwordfile}">
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-component>

Components can be enabled or disabled on multiple servers in a single task. This example shows the same three components being enabled on two different instances of the Enterprise Server. In this example, the passwords for both instances are the same.

<sun-appserv-component action="enable" passwordfile="${passwordfile}">
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-component>

The sun-appserv-admin Task

Enables arbitrary administrative commands and scripts to be executed on the Enterprise Server. This is useful for cases where a specific Ant task has not been developed or a set of related commands are in a single script.

Subelements of sun-appserv-admin

The following table describes subelements for the sun-appserv-admin task. These are objects upon which this task acts.

The sun-appserv-admin Subelements

Element Description The server Subelement An Enterprise Server instance

Attributes of sun-appserv-admin

The following table describes attributes for the sun-appserv-admin task.

The sun-appserv-admin Attributes

Examples of sun-appserv-admin

Here is an example of executing the create-jms-dest command:

<sun-appserv-admin command="create-jms-dest --desttype topic">

Here is an example of using explicitcommand to execute the create-jms-dest command:

<sun-appserv-admin explicitcommand="create-jms-dest --desttype topic --target server1 simpleJmsDest">

The sun-appserv-jspc Task

Precompiles JSP source code into Enterprise Server compatible Java code for initial invocation by Enterprise Server. Use this task to speed up access to JSP files or to check the syntax of JSP source code. You can feed the resulting Java code to the javac task to generate class files for the JSP files.

Attributes of sun-appserv-jspc

The following table describes attributes for the sun-appserv-jspc task.

The sun-appserv-jspc Attributes

Example of sun-appserv-jspc

The following example uses the webapp attribute to generate Java source files from JSP files. The sun-appserv-jspc task is immediately followed by a javac task, which compiles the generated Java files into class files. The classpath value in the javac task must be all on one line with no spaces.

<sun-appserv-jspc
 destdir="${assemble.war}/generated"
 webapp="${assemble.war}"
 classpath="${assemble.war}/WEB-INF/classes"
 asinstalldir="${asinstalldir}" />
<javac
 srcdir="${assemble.war}/WEB-INF/generated"
 destdir="${assemble.war}/WEB-INF/generated"
 debug="on"
 classpath="${assemble.war}/WEB-INF/classes:${asinstalldir}/lib/
   appserv-rt.jar:${asinstalldir}/lib/appserv-ext.jar">
 <include name="**/*.java"/>
</javac>

The sun-appserv-update Task

Enables deployed web applications (EAR files) and modules (EJB JAR, RAR, and WAR files) to be updated and reloaded for fast iterative development. This task copies modified class files, XML files, and other contents of the archive files to the appropriate subdirectory of the domain-dir/applications directory, then touches the .reload file to cause dynamic reloading to occur.

This is a local task and must be executed on the same machine as the Enterprise Server.

For more information about dynamic reloading, see the Sun GlassFish Enterprise Server v3 Application Deployment Guide.

Attributes of sun-appserv-update

The following table describes attributes for the sun-appserv-update task.

The sun-appserv-update Attributes

Example of sun-appserv-update

The following example updates the Java EE application foo.ear, which is deployed to the default domain, domain1.

<sun-appserv-update file="foo.ear"/>

The wsgen Task

Generates JAX-WS portable artifacts used in JAX-WS web services. Reads a web service endpoint class and generates all the required artifacts for web service deployment and invocation.

Attributes of wsgen

The following table describes attributes for the wsgen task.

The wsgen Attributes

servicename="{http://mynamespace/}MyService"

portname="{http://mynamespace/}MyPort"

Example of wsgen

The following example generates portable artifacts for fromjava.server.AddNumbersImpl, uses compile.classpath as the classpath, and writes the WSDL file to ${wsdl.dir}.

<wsgen
   resourcedestdir="${wsdl.dir}"
   sei="fromjava.server.AddNumbersImpl">
   <classpath refid="compile.classpath"/>
</wsgen>

The wsimport Task

Generates JAX-WS portable artifacts for a given WSDL file. Portable artifacts include service endpoint interfaces (SEIs), services, exception classes mapped from the wsdl:fault and soap:headerfault tags, asynchronous response beans derived from the wsdl:message tag, and JAXB generated value types. After generation, these artifacts can be packaged in a WAR file with the WSDL and schema documents along with the endpoint implementation and then deployed.

Attributes of wsimport

The following table describes attributes for the wsimport task.

The wsimport Attributes

Example of wsimport

The following example generates client-side artifacts for AddNumbers.wsdl and stores .class files in the ${build.classes.home} directory using the custom.xml customization file.

<wsimport
   destdir="${build.classes.home}"
   wsdl="AddNumbers.wsdl"
   binding="custom.xml">
</wsimport>