Use the asant tasks provided by the Application Server for assembling, deploying, and undeploying modules and applications, and for configuring the server. The tasks are as follows:
Deploys any of the following.
Enterprise application (EAR file)
Web application (WAR file)
Enterprise Java Bean (EJB-JAR file)
Enterprise connector (RAR file)
Application client
The following table describes subelements for the sun-appserv-deploy task. These are objects upon which this task acts.
Table 3–1 The sun-appserv-deploy Subelements
Element |
Description |
---|---|
A component to be deployed |
|
A set of component files that match specified parameters |
The following table describes attributes for the sun-appserv-deploy task.
Table 3–2 The sun-appserv-deploy Attributes
Attribute |
Default |
Description |
---|---|---|
none |
(optional if a component or fileset subelement is present, otherwise required) The component to deploy. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. If upload is set to false, this must be an absolute path on the server machine. |
|
name |
file name without extension |
(optional) The display name for the component being deployed. |
true |
(optional) If true, the component is overwritten if it already exists on the server. If false, sun-appserv-deploy fails if the component exists. |
|
client stubs not saved |
(optional) The directory where client stubs are saved. This attribute is inherited by nested component elements. |
|
false |
(optional) If true, all JSP files found in an enterprise application (.ear) or web application (.war) are precompiled. This attribute is ignored for other component types. This attribute is inherited by nested component elements. |
|
false |
(optional) If true, syntax and semantics for all deployment descriptors are automatically verified for correctness. This attribute is inherited by nested component elements. |
|
file name without extension |
(optional) The context root for a web module (WAR file). This attribute is ignored if the component is not a WAR file. |
|
sun-ejb-jar.xml entry |
(optional) The name of the database vendor for which tables can be created. Allowed values are javadb, db2, mssql, oracle, postgresql, pointbase, derby (also for CloudScape), and sybase, case-insensitive. If not specified, the value of the database-vendor-name attribute in sun-ejb-jar.xml is used. If no value is specified, a connection is made to the resource specified by the jndi-name subelement of the cmp-resource element in the sun-ejb-jar.xml file, and the database vendor name is read. If the connection cannot be established, or if the value is not recognized, SQL-92 compliance is presumed. For details, see Generation Options for CMP. |
|
sun-ejb-jar.xml entry |
(optional) If true, causes database tables to be created for beans that need them. If false, does not create tables. If not specified, the value of the create-tables-at-deploy attribute in sun-ejb-jar.xml is used. For details, see Generation Options and Generation Options for CMP. |
|
sun-ejb-jar.xml entry |
(optional) If true, and if tables were automatically created when this application was last deployed, tables from the earlier deployment are dropped and fresh ones are created. If true, and if tables were not automatically created when this application was last deployed, no attempt is made to drop any tables. If tables with the same names as those that would have been automatically created are found, the deployment proceeds, but a warning indicates that tables could not be created. If false, settings of create-tables-at-deploy or drop-tables-at-undeploy in the sun-ejb-jar.xml file are overridden. For details, see Generation Options and Generation Options for CMP. |
|
sun-ejb-jar.xml entry |
(optional) If true, specifies that table names are unique within each application server domain. If not specified, the value of the use-unique-table-names property in sun-ejb-jar.xml is used. For details, see Generation Options for CMP. |
|
true |
(optional) If true, enables the component. |
|
none |
(optional) A deployment plan is a JAR file containing Sun-specific descriptors. Use this attribute when deploying an EAR file that lacks Sun-specific descriptors. |
|
true |
(optional) If true, the component is transferred to the server for deployment. If the component is being deployed on the local machine, set upload to false to reduce deployment time. If a directory is specified for deployment, upload must be false. |
|
default virtual server only |
(optional) A comma-separated list of virtual servers to be deployment targets. This attribute applies only to application (.ear) or web (.war) components and is ignored for other component types. |
|
admin |
(optional) The user name used when logging into the application server. |
|
passwordfile |
none |
(optional) File containing passwords. The password from this file is retrieved for communication with the application server. |
localhost |
(optional) Target server. When deploying to a remote server, use the fully qualified host name. |
|
4848 |
(optional) The administration port on the target server. |
|
see description |
(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath. |
Here is a simple application deployment script with many implied attributes:
<sun-appserv-deploy file="${assemble}/simpleapp.ear" passwordfile="${passwordfile}" />
Here is an equivalent script showing all the implied attributes:
<sun-appserv-deploy file="${assemble}/simpleapp.ear" name="simpleapp" force="true" precompilejsp="false" verify="false" upload="true" user="admin" passwordfile="${passwordfile}" host="localhost" port="4848" asinstalldir="${asinstalldir}" />
This example deploys multiple components to the same Application Server 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 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>
Undeploys any of the following.
Enterprise application (EAR file)
Web application (WAR file)
Enterprise Java Bean (EJB-JAR file)
Enterprise connector (RAR file)
Application client
The following table describes subelements for the sun-appserv-undeploy task. These are objects upon which this task acts.
Table 3–3 The sun-appserv-undeploy Subelements
Element |
Description |
---|---|
A component to be deployed |
|
A set of component files that match specified parameters |
The following table describes attributes for the sun-appserv-undeploy task.
Table 3–4 The sun-appserv-undeploy Attributes
Attribute |
Default |
Description |
---|---|---|
name |
file name without extension |
(optional if a component or fileset subelement is present or the file attribute is specified, otherwise required) The display name for the component being undeployed. |
none |
(optional) The component to undeploy. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. |
|
sun-ejb-jar.xml entry |
(optional) If true, causes database tables that were automatically created when the bean(s) were last deployed to be dropped when the bean(s) are undeployed. If false, does not drop tables. If not specified, the value of the drop-tables-at-undeploy attribute in sun-ejb-jar.xml is used. For details, see Generation Options and Generation Options for CMP. |
|
false |
(optional) If true, deletes all connection pools and connector resources associated with the resource adapter being undeployed. If false, undeployment fails if any pools or resources are still associated with the resource adapter. This attribute is applicable to connectors (resource adapters) and applications with connector modules. |
|
admin |
(optional) The user name used when logging into the application server. |
|
passwordfile |
none |
(optional) File containing passwords. The password from this file is retrieved for communication with the application server. |
localhost |
(optional) Target server. When deploying to a remote server, use the fully qualified host name. |
|
4848 |
(optional) The administration port on the target server. |
|
see description |
(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath. |
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" 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>
Enables or disables the following Java EE component types that have been deployed to the Application 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.
The following table describes subelements for the sun-appserv-component task. These are objects upon which this task acts.
Table 3–5 The sun-appserv-component Subelements
Element |
Description |
---|---|
A component to be deployed |
|
A set of component files that match specified parameters |
The following table describes attributes for the sun-appserv-component task.
Table 3–6 The sun-appserv-component Attributes
Attribute |
Default |
Description |
---|---|---|
none |
The control command for the target application server. Valid values are enable and disable. |
|
name |
file name without extension |
(optional if a component or fileset subelement is present or the file attribute is specified, otherwise required) The display name for the component being enabled or disabled. |
none |
(optional) The component to enable or disable. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. |
|
admin |
(optional) The user name used when logging into the application server. |
|
passwordfile |
none |
(optional) File containing passwords. The password from this file is retrieved for communication with the application server. |
localhost |
(optional) Target server. When enabling or disabling a remote server, use the fully qualified host name. |
|
4848 |
(optional) The administration port on the target server. |
|
see description |
(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath. |
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" 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>
Enables arbitrary administrative commands and scripts to be executed on the Application 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.
The following table describes attributes for the sun-appserv-admin task.
Table 3–7 The sun-appserv-admin Attributes
Attribute |
Default |
Description |
---|---|---|
none |
(exactly one of these is required: command or explicitcommand) The command to execute. If the user, passwordfile, host, or port attributes are also specified, they are automatically inserted into the command before execution. If any of these options are specified in the command string, the corresponding attribute values are ignored. |
|
none |
(exactly one of these is required: command or explicitcommand) The exact command to execute. No command processing is done, and all other attributes are ignored. |
|
user |
admin |
(optional) The user name used when logging into the application server. |
passwordfile |
none |
(optional) File containing passwords. The password from this file is retrieved for communication with the application server. |
host |
localhost |
(optional) Target server. If it is a remote server, use the fully qualified host name. |
port |
4848 |
(optional) The administration port on the target server. |
see description |
(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath. |
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 command="create-jms-dest --user adminuser --host localhost --port 4848 --desttype topic --target server1 simpleJmsDest">
Precompiles JSP source code into Application Server compatible Java code for initial invocation by Application 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.
The following table describes attributes for the sun-appserv-jspc task.
Table 3–8 The sun-appserv-jspc Attributes
Attribute |
Default |
Description |
---|---|---|
|
The destination directory for the generated Java source files. |
|
|
(exactly one of these is required: srcdir or webapp) The source directory where the JSP files are located. |
|
|
(exactly one of these is required: srcdir or webapp) The directory containing the web application. All JSP files within the directory are recursively parsed. The base directory must have a WEB-INF subdirectory beneath it. When webapp is used, sun-appserv-jspc hands off all dependency checking to the compiler. |
|
2 |
(optional) The verbosity integer to be passed to the compiler. |
|
|
(optional) The classpath for running the JSP compiler. |
|
|
(optional) A reference to the JSP compiler classpath. |
|
/ |
(optional) The URI context of relative URI references in the JSP files. If this context does not exist, it is derived from the location of the JSP file relative to the declared or derived value of uriroot. Only pages translated from an explicitly declared JSP file are affected. |
|
see description |
(optional) The root directory of the web application, against which URI files are resolved. If this directory is not specified, the first JSP file is used to derive it: each parent directory of the first JSP file is searched for a WEB-INF directory, and the directory closest to the JSP file that has one is used. If no WEB-INF directory is found, the directory from which sun-appserv-jspc was called is used. Only pages translated from an explicitly declared JSP file (including tag libraries) are affected. |
|
(optional) The destination package for the generated Java classes. |
||
see description |
(optional) The installation directory for the local Application Server installation, which is used to find the administrative classes. If not specified, the command checks if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath. |
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>
Enables deployed 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 Application Server.
For more information about dynamic reloading, see the Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
The following table describes attributes for the sun-appserv-update task.
Table 3–9 The sun-appserv-update Attributes
Attribute |
Default |
Description |
---|---|---|
none |
The component to update, which must be a valid archive. |
|
domain1 |
(optional) The domain in which the application has been previously deployed. |
The following example updates the Java EE application foo.ear, which is deployed to the default domain, domain1.
<sun-appserv-update file="foo.ear"/>