Chapter 3 Using Ant with GlassFish^TM Server

The Oracle GlassFish Server provides server-specific Ant tasks, which are described in the following sections:

• Setting Up Your Ant Environment

• GlassFish Server Ant Tasks

• Reusable Subelements

GlassFish Server is compatible with Apache Ant versions 1.6.5 or greater. If you don't have Ant installed, you can download it from the Update Tool. The Apache Ant Build Tool add-on component supplies Ant version 1.7.1. For more information about the Update Tool, see Update Tool in Oracle GlassFish Server 3.0.1 Administration Guide.

For more information about Ant, see the Apache Software Foundation web site at http://ant.apache.org/.

For information about standard Ant tasks, see the Ant documentation at http://ant.apache.org/manual/.

Variables in the examples in this chapter, such as ${asinstalldir}, reference values defined in build.xml or properties files.

Setting Up Your Ant Environment

To set up your Ant environment for using GlassFish Server Ant tasks, you can either define the ANT_OPTS environment variable or define a target. In both these cases, you must also set the classpath to point to the sun-appserv-ant.jar file.

Defining the ANT_OPTS Variable

To define the ANT_OPTS environment variable on UNIX systems, use the following commands, where ${ASINSTALLDIR} is an environment variable defined to point to the GlassFish Server installation directory.

export ANT_OPTS="-Djava.library.path${ASINSTALLDIR}/modules"
export CLASSPATH=${CLASSPATH};${ASINSTALLDIR}/modules/sun-appserv-ant.jar

To define the ANT_OPTS environment variable on Windows systems, use the following commands, where %ASINSTALLDIR% is an environment variable defined to point to the GlassFish Server installation directory.

set ANT_OPTS="-Djava.library.path=%ASINSTALLDIR%\modules"
set CLASSPATH=%CLASSPATH%;%ASINSTALLDIR%\modules\sun-appserv-ant.jar

Defining a Target

The following target element defines the GlassFish Server Ant tasks and references the sun-appserv-ant.jar file. You can include this target in your build.xml file. The ${asinstalldir} in the classpath element refers to the GlassFish Server installation directory.

<target name="as-ant-init">
   <taskdef name="sun-appserv-deploy"
      classname="org.apache.tools.ant.taskdefs.optional.sun.appserv.DeployTask" />
   <taskdef name="sun-appserv-undeploy"
      classname="org.apache.tools.ant.taskdefs.optional.sun.appserv.UndeployTask" />
   <taskdef name="sun-appserv-component"
      classname="org.apache.tools.ant.taskdefs.optional.sun.appserv.ComponentTask" />
   <taskdef name="sun-appserv-admin"
      classname="org.apache.tools.ant.taskdefs.optional.sun.appserv.AdminTask" />
   <taskdef name="sun-appserv-jspc"
      classname="org.apache.tools.ant.taskdefs.optional.sun.appserv.SunJspc" />
   <taskdef name="sun-appserv-update"
      classname="org.apache.tools.ant.taskdefs.optional.sun.appserv.UpdateTask" />
   <taskdef name="sun-appserv-instance"
      classname="org.apache.tools.ant.taskdefs.optional.sun.appserv.InstanceTask" />
    <taskdef name="wsgen" classname="com.sun.tools.ws.ant.WsGen" />
    <taskdef name="wsimport" classname="com.sun.tools.ws.ant.WsImport" />
   <classpath path="${asinstalldir}/lib/sun-appserv-ant.jar" />
</target>

Targets that use the GlassFish Server Ant tasks then can use the as-ant-init target as a dependency. For example:

<target name="create-some-jdbc-resource" depends="as-ant-init">
   ...
</target>

Ant resolves properties from top to bottom in Ant build files. If you define the GlassFish Server Ant tasks at the project level, make sure that any properties used within the task definitions have been resolved before the task definitions. For example, the following snippet defines the sun-appserv-admin task at the project level:

<?xml version="1.0" encoding="UTF-8"?>
<project name="glassfish-admin-ant-tasks" default="default">
    <property name="asinstalldir" value="c:/glassfishv3/glassfish" />
    <taskdef name="sun-appserv-admin"
        classname="org.apache.tools.ant.taskdefs.optional.sun.appserv.AdminTask"
        classpath="${asintalldir}/modules/sun-appserv-ant.jar" />
    ...
</project>

GlassFish Server Ant Tasks

Use the Ant tasks provided by the GlassFish 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 GlassFish 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.

Attributes of sun-appserv-deploy

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

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 GlassFish Server instance running on a remote server:

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.oracle.com"
		 asinstalldir="/opt/glassfish" >
 <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 GlassFish 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/glassfish" >
 <server host="greg.oracle.com"/>
 <server host="joe.oracle.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.oracle.com"
		 asinstalldir="/opt/glassfish" >
 <fileset dir="${assemble}" includes="**/*.?ar" />
</sun-appserv-deploy>

The sun-appserv-undeploy Task

Undeploys any of the following from a local or remote GlassFish 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.

Attributes of sun-appserv-undeploy

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

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 GlassFish Server. In this example, the passwords for both instances are the same.

<sun-appserv-undeploy passwordfile="${passwordfile}">
 <server host="greg.oracle.com"/>
 <server host="joe.oracle.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 GlassFish 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.

Attributes of sun-appserv-instance

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

Examples of sun-appserv-instance

This example starts the local GlassFish 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.oracle.com" passwordfile="${password.greg}"/>
 <server host="joe.oracle.com" passwordfile="${password.joe}"/>
</sun-appserv-instance>

This example creates a new GlassFish 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.oracle.com"/>
 <server host="joe.oracle.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.oracle.com"/>
 <server host="joe.oracle.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.oracle.com" instanceport="8080" instance="qa"/>
 <server host="joe.oracle.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 GlassFish 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.

Attributes of sun-appserv-component

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

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 GlassFish Server. In this example, the passwords for both instances are the same.

<sun-appserv-component action="enable" passwordfile="${passwordfile}">
 <server host="greg.oracle.com"/>
 <server host="joe.oracle.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 GlassFish 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.

Attributes of sun-appserv-admin

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

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 GlassFish Server compatible Java code for initial invocation by GlassFish 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.

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 GlassFish Server.

For more information about dynamic reloading, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.

Attributes of sun-appserv-update

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

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.

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.

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>

Reusable Subelements

Reusable subelements of the Ant tasks for the GlassFish Server are as follows. These are objects upon which the Ant tasks act.

• The server Subelement

• The component Subelement

• The fileset Subelement

The server Subelement

Specifies a GlassFish Server instance. Allows a single task to act on multiple server instances. The server attributes override corresponding attributes in the parent task; therefore, the parent task attributes function as default values.

Attributes of server

The following table describes attributes for the server element.

Examples of server

You can control multiple servers using a single task. In this example, two servers are started, each using a different password. Only the second server is started in debug mode.

<sun-appserv-instance action="start">
<server host="greg.oracle.com" passwordfile="${password.greg}"/>
<server host="joe.oracle.com" passwordfile="${password.joe}"
	 debug="true"/>
</sun-appserv-instance>

You can create instances on multiple servers using a single task. This example creates a new instance named qa on two different servers. Both servers use the same password.

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

You can specify different instance names and instance ports using attributes of the nested server element:

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

You can deploy multiple components to multiple servers (see the The component Subelement) . This example deploys each component to two GlassFish Server instances running on remote servers. Both servers use the same password.

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

You can also undeploy multiple components from multiple servers. This example shows the same three components being removed from two different instances. Both servers use the same password.

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

You can enable or disable components on multiple servers. This example shows the same three components being enabled on two different instances. Both servers use the same password.

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

The component Subelement

Specifies a Java EE component. Allows a single task to act on multiple components. The component attributes override corresponding attributes in the parent task; therefore, the parent task attributes function as default values.

Attributes of component

The following table describes attributes for the component element.

Examples of component

You can deploy multiple components using a single task. This example deploys each component to the same GlassFish Server instance running on a remote server.

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

You can also undeploy multiple components using a single task. This example demonstrates using the archive files (EAR and WAR, in this case) and the component name (for the EJB component).

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

You can deploy multiple components to multiple servers. This example deploys each component to two instances running on remote servers. Both servers use the same password.

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

You can also undeploy multiple components to multiple servers. This example shows the same three components being removed from two different instances. Both servers use the same password.

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

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

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

You can enable or disable multiple components on multiple servers. This example shows the same three components being enabled on two different instances. Both servers use the same password.

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

The fileset Subelement

Selects component files that match specified parameters. When fileset is included as a subelement, the name and contextroot attributes of the containing element must use their default values for each file in the fileset. For more information, see http://ant.apache.org/manual/Types/fileset.html.