Sun Java System Application Server Enterprise Edition 8.1 2005Q1 Developer's Guide |
Chapter 3
Assembling and Deploying ApplicationsThis chapter describes Sun Java System Application Server modules and how these modules are assembled separately or together in an application. This chapter also describes classloaders and tools for assembly and deployment.
Sun Java System Application Server modules and applications include J2EE standard features and Sun Java System Application Server specific features. Only Sun Java System Application Server specific features are described in detail in this chapter.
The following topics are presented in this chapter:
Overview of Assembly and DeploymentApplication assembly (also known as packaging) is the process of combining discrete components of an application into a single unit that can be deployed to a J2EE-compliant application server. A package can be classified either as a module or as a full-fledged application. This section covers the following topics:
Modules
A J2EE module is a collection of one or more J2EE components of the same container type (for example, web or EJB) with deployment descriptors of that type. One descriptor is J2EE standard, the other is Sun Java System Application Server specific. Types of J2EE modules are as follows:
- Web Application Archive (WAR): A web application is a collection of servlets, HTML pages, classes, and other resources that can be bundled and deployed to several J2EE application servers. A WAR file can consist of the following items: servlets, JSP files, JSP tag libraries, utility classes, static pages, client-side applets, beans, bean classes, and deployment descriptors (web.xml and optionally sun-web.xml).
- EJB JAR File: The EJB JAR file is the standard format for assembling enterprise beans. This file contains the bean classes (home, remote, local, and implementation), all of the utility classes, and the deployment descriptors (ejb-jar.xml and sun-ejb-jar.xml). If the EJB component is an entity bean with container managed persistence, a .dbschema file and a CMP mapping descriptor, sun-cmp-mapping.xml, must be included as well.
- Application Client Container JAR File: An ACC client is a Sun Java System Application Server specific type of J2EE client. An ACC client supports the standard J2EE Application Client specifications, and in addition, supports direct access to the Sun Java System Application Server. Its deployment descriptors are application-client.xml and sun-application-client.xml.
- Resource RAR File: RAR files apply to J2EE CA connectors. A connector module is like a device driver. It is a portable way of allowing EJB components to access a foreign enterprise system. Each Sun Java System Application Server connector has a J2EE XML file, ra.xml.
Package definitions must be used in the source code of all modules so the classloader can properly locate the classes after the modules have been deployed.
Because the information in a deployment descriptor is declarative, it can be changed without requiring modifications to source code. At run time, the J2EE server reads this information and acts accordingly.
Sun Java System Application Server also supports lifecycle modules. See Chapter 10, "Developing Lifecycle Listeners," for more information.
EJB JAR and Web modules can also be assembled as separate JAR or WAR files and deployed separately, outside of any application, as in the following figure.
Figure 3-1 Module Assembly and Deployment
Applications
A J2EE application is a logical collection of one or more J2EE modules tied together by application deployment descriptors. Components can be assembled at either the module or the application level. Components can also be deployed at either the module or the application level.
The following diagram illustrates how components are assembled into modules and then assembled into a Sun Java System Application Server application EAR file ready for deployment.
Figure 3-2 Application Assembly and Deployment
Each module has a Sun Java System Application Server deployment descriptor and a J2EE deployment descriptor. The Sun Java System Application Server uses the deployment descriptors to deploy the application components and to register the resources with the Sun Java System Application Server.
An application consists of one or more modules, an optional Sun Java System Application Server deployment descriptor, and a required J2EE application deployment descriptor. All items are assembled, using the Java ARchive (.jar) file format, into one file with an extension of .ear.
J2EE Standard Descriptors
The J2EE platform provides assembly and deployment facilities. These facilities use WAR, JAR, and EAR files as standard packages for components and applications, and XML-based deployment descriptors for customizing parameters.
J2EE standard deployment descriptors are described in the J2EE specification, v1.4. You can find the specification here:
To check the correctness of these deployment descriptors prior to deployment, see The Deployment Descriptor Verifier.
The following table shows where to find more information about J2EE standard deployment descriptors.
Sun Java System Application Server Descriptors
Sun Java System Application Server uses additional deployment descriptors for configuring features specific to the Sun Java System Application Server. The sun-application.xml, sun-web.xml, and sun-cmp-mappings.xml files are optional; all the others are required.
To check the correctness of these deployment descriptors prior to deployment, see The Deployment Descriptor Verifier.
The following table lists the Sun Java System Application Server deployment descriptors and their DTD files. For complete descriptions of these files, see Appendix A, “Deployment Descriptor Files.”
Naming Standards
Names of applications and individually deployed EJB JAR, WAR, and connector RAR modules must be unique within a Sun Java System Application Server domain. Modules of the same type within an application must have unique names. In addition, for entity beans that use CMP,.dbschema file names must be unique within an application.
If you do not explicitly specify a name, the default name is the first portion of the file name (without the .war or .jar extension). Modules of different types can have the same name within an application, because the directories holding the individual modules are named with _jar, _war and _rar suffixes. This is the case when you use the Administration Console, the asadmin command, or the deploytool to deploy an application or module. See Tools for Deployment.
Make sure your package and file names do not contain spaces or characters that are illegal for your operating system.
If you are writing your own JSR 88 client to deploy applications to the Sun Java System Application Server using the following API, the name of the application is taken from the display-name entry in the J2EE standard deployment descriptor, because there is no file name in this case. If the display-name entry is not present, the Application Server creates a temporary file name and uses that name to deploy the application.
javax.enterprise.deploy.spi.DeploymentManager.distribute(Target[], InputStream, InputStream)
Neither the Administration Console, the asadmin command, nor the deploytool uses this API.
For more information about JSR 88, see the JSR 88 page:
http://jcp.org/en/jsr/detail?id=88
Directory Structure
When you deploy an application, the application is expanded to an open directory structure, and the directories holding the individual modules are named with _jar, _war and _rar suffixes. If you use the asadmin deploydir command to deploy a directory instead of an EAR file, your directory structure must follow this same convention.
Module and application directory structures follow the structure outlined in the J2EE specification. Here is an example directory structure of a simple application containing a web module, an EJB module, and a client module.
Here is an example directory structure of an individually deployed connector module.
+ MyConnector/
|--- readme.html
|--- ra.jar
|--- client.jar
|--- win.dll
|--- solaris.so
'--+ META-INF/
|--- MANIFEST.MF
'--- ra.xml
Runtime Environments
Whether you deploy an individual module or an application, deployment affects both the file system and the server configuration. See the following Module runtime environment and Application runtime environment figures.
Module Runtime Environment
The following figure illustrates the environment for individually deployed module-based deployment.
Figure 3-3 Module runtime environment
For file system entries, modules are extracted as follows:
domain_dir/applications/j2ee-modules/module_name
domain_dir/generated/ejb/j2ee-modules/module_name
domain_dir/generated/jsp/j2ee-modules/module_nameThe applications directory contains the directory structures described in Directory Structure. The generated/ejb directory contains the stubs and ties that an ACC client needs to access the module; the generated/jsp directory contains compiled JSP files.
Lifecycle modules (see Chapter 10, "Developing Lifecycle Listeners") are extracted as follows:
domain_dir/applications/lifecycle-modules/module_name
Configuration entries are added in the domain.xml file as follows:
<server>
<applications>
<type-module>
...module configuration...
</type-module>
</applications>
</server>The type of the module in domain.xml can be lifecycle, ejb, web, or connector. For details about domain.xml, see the Sun Java System Application Server Administration Reference.
Application Runtime Environment
The following figure illustrates the environment for application-based deployment.
Figure 3-4 Application runtime environment
For file system entries, applications are extracted as follows:
domain_dir/applications/j2ee-apps/app_name
domain_dir/generated/ejb/j2ee-apps/app_name
domain_dir/generated/jsp/j2ee-apps/app_nameThe applications directory contains the directory structures described in Directory Structure. The generated/ejb directory contains the stubs and ties that an ACC client needs to access the module; the generated/jsp directory contains compiled JSP files.
Configuration entries are added in the domain.xml file as follows:
<server>
<applications>
<j2ee-application>
...application configuration...
</j2ee-application>
</applications>
</server>For details about domain.xml, see the Sun Java System Application Server Administration Reference.
Classloaders
Understanding Sun Java System Application Server classloaders can help you determine where and how you can position supporting JAR and resource files for your modules and applications.
In a Java Virtual Machine (JVM), the classloaders dynamically load a specific java class file needed for resolving a dependency. For example, when an instance of java.util.Enumeration needs to be created, one of the classloaders loads the relevant class into the environment. This section includes the following topics:
The Classloader Hierarchy
Classloaders in the Sun Java System Application Server runtime follow a hierarchy that is illustrated in the following figure.
Figure 3-5 Classloader runtime hierarchy
Note that this is not a Java inheritance hierarchy, but a delegation hierarchy. In the delegation design, a classloader delegates classloading to its parent before attempting to load a class itself. A classloader parent can be either the System Classloader or another custom classloader. If the parent classloader can’t load a class, the findClass() method is called on the classloader subclass. In effect, a classloader is responsible for loading only the classes not available to the parent.
The Servlet specification recommends that the Web Classloader look in the local classloader before delegating to its parent. You can make the Web Classloader follow the delegation model in the Servlet specification by setting delegate="false" in the class-loader element of the sun-web.xml file. It’s safe to do this only for a web module that does not interact with any other modules.
The default value is delegate="true", which causes the Web Classloader to delegate in the same manner as the other classloaders. You must use delegate="true" for a web application that accesses EJB components or that acts as a web service client or endpoint. For details about sun-web.xml, see “The sun-web.xml File” on page 321.
The following table describes Sun Java System Application Server classloaders.
Table 3-3 Sun Java System Application Server Classloaders
Classloader
Description
Bootstrap
The Bootstrap Classloader loads all the JDK classes.
System
The System Classloader loads most of the core Sun Java System Application Server classes. It is created based on the classpath-prefix, server-classpath, and classpath-suffix attributes of the java-config element in the domain.xml file. The environment classpath is included if env-classpath-ignored="false" is set in the java-config element.
Common
The Common Classloader loads classes in the domain_dir/lib/classes directory, followed by JAR and ZIP files in the domain_dir/lib directory. No special classpath settings are required. The existence of these directories is optional; if they don’t exist, the Common Classloader is not created.
Connector
The Connector Classloader is a single classloader instance that loads individually deployed connector modules, which are shared across all applications.
LifeCycleModule
The LifeCycleModule Classloader is the parent classloader for lifecycle modules. Each lifecycle module’s classpath is used to construct its own classloader.
EJB
The EJB Classloader loads the enabled EJB classes in a specific enabled EJB module or J2EE application. One instance of this classloader is present in each classloader universe. The EJB Classloader is created with a list of URLs that point to the locations of the classes it needs to load.
Web
The Web Classloader loads the servlets and other classes in a specific enabled web module or J2EE application. One instance of this classloader is present in each classloader universe. The Web Classloader is created with a list of URLs that point to the locations of the classes it needs to load.
JSP Engine
The JSP Engine Classloader loads compiled JSP classes of enabled JSP files. One instance of this classloader is present in each classloader universe. The JSP Engine Classloader is created with a list of URLs that point to the locations of the classes it needs to load.
Classloader Universes
Access to components within applications and modules installed on the server occurs within the context of isolated classloader universes, each of which has its own EJB, Web, and JSP Engine classloaders.
- Application Universe: Each J2EE application has its own classloader universe, which loads the classes in all the modules in the application.
- Individually Deployed Module Universe: Each individually deployed EJB JAR, web WAR, or lifecycle module has its own classloader universe, which loads the classes in the module.
Note
A resource such as a file that is accessed by a servlet, JSP, or EJB component must be in a directory pointed to by the classloader’s classpath. For example, the web classloader’s classpath includes these directories:
module_name/WEB-INF/classes
module_name/WEB-INF/libIf a servlet accesses a resource, it must be in one of these directories or it is not loaded.
Circumventing Classloader Isolation
Since each application or individually deployed module classloader universe is isolated, an application or module cannot load classes from another application or module. This prevents two similarly named classes in different applications from interfering with each other.
To circumvent this limitation for libraries, utility classes, or individually deployed modules accessed by more than one application, you can include the relevant path to the required classes in one of these ways:
Using the System Classloader
To use the System Classloader, do one of the following, then restart the server:
- Use the Administration Console. Select the JVM Settings component under the relevant configuration, select the Path Settings tab, and edit the Classpath Suffix field. For details, see the Sun Java System Application Server Administration Guide.
- Edit the classpath-suffix attribute of the java-config element in the domain.xml file. For details about domain.xml, see the Sun Java System Application Server Administration Reference.
Using the System Classloader makes an application or module accessible to any other application or module across the domain.
Using the Common Classloader
To use the Common Classloader, copy the JAR and ZIP files into the domain_dir/lib directory or copy the .class files into the domain_dir/lib/classes directory, then restart the server.
Using the Common Classloader makes an application or module accessible to any other application or module across the domain.
Using the Java Optional Package Mechanism
To use the Java optional package mechanism, copy the JAR and ZIP files into the domain_dir/lib/ext directory, then restart the server.
Using the Java optional package mechanism makes an application or module accessible to any other application or module across the domain. For example, this is the recommended way of adding JDBC drivers to the Sun Java System Application Server.
Packaging the Client JAR for One Application in Another Application
By packaging the client JAR for one application in a second application, you allow an EJB or web component in the second application to call an EJB component in the first (dependent) application, without making either of them accessible to any other application or module.
As an alternative for a production environment, you can have the Common Classloader load client JAR of the dependent application as described in Using the Common Classloader. Server performance is better, but you must restart the server to make the dependent application accessible, and it is accessible across the domain.
To package the client JAR for one application in another application:
- Deploy the dependent application.
- Add the dependent application’s client JAR file to the calling application.
- For a calling EJB component, add the client JAR file at the same level as the EJB component. Then add a Class-Path entry to the MANIFEST.MF file of the calling EJB component. The Class-Path entry has this syntax:
Class-Path: filepath1.jar filepath2.jar ...
Each filepath is relative to the directory or JAR file containing the MANIFEST.MF file. For details, see the J2EE specification, section 8.1.1.2, “Dependencies.”
- For a calling web component, add the client JAR file under the WEB-INF/lib directory.
- For most applications, packaging the client JAR file with the calling EJB component is sufficient. You do not need to package the client JAR file with both the EJB and web components unless the web component is directly calling the EJB component in the dependent application. If you need to package the client JAR with both the EJB and web components, set delegate="true" in the class-loader element of the sun-web.xml file. This changes the Web Classloader so it follows the standard classloader delegation model and delegates to its parent before attempting to load a class itself.
- Deploy the calling application.
Assembling Modules and ApplicationsAssembling (or packaging) modules and applications in Sun Java System Application Server conforms to all of the customary J2EE-defined specifications. The only difference is that when you assemble in Sun Java System Application Server, you include Sun Java System Application Server specific deployment descriptors that enhance the functionality of the Application Server.
For example, when you assemble an EJB JAR module, you must create two deployment descriptor files with these names: ejb-jar.xml and sun-ejb-jar.xml (both required). If the EJB component is an entity bean with container-managed persistence, you can also create a .dbschema file and a sun-cmp-mapping.xml file, but these are not required. For more information about sun-ejb-jar.xml and sun-cmp-mapping.xml, see Appendix A, “Deployment Descriptor Files.”
Note
According to the J2EE specification, section 8.1.1.2, “Dependencies,” you cannot package utility classes within an individually deployed EJB module. Instead, package the EJB module and utility JAR within an application using the JAR Extension Mechanism Architecture. For other alternatives, see Circumventing Classloader Isolation.
The Sun Java System Application Server provides these tools for assembling and verifying a module or an application:
deploytool
You can use the deploytool, provided with Sun Java System Application Server, to assemble J2EE applications and modules, configure deployment parameters, perform simple static checks, and deploy the final result. For more information about using the deploytool, see the J2EE 1.4 Tutorial:
http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html
Apache Ant
Ant can help you assemble and deploy modules and applications. For details, see asant Assembly and Deployment Tool.
The Deployment Descriptor Verifier
The verifier tool validates both J2EE and Sun Java System Application Server specific deployment descriptors against their corresponding DTD files and gives errors and warnings if a module or application is not J2EE and Sun Java System Application Server compliant. You can verify deployment descriptors in EAR, WAR, RAR, and JAR files.
The verifier tool is not simply an XML syntax verifier. Rules and interdependencies between various elements in the deployment descriptors are verified. Where needed, user application classes are introspected to apply validation rules.
The verifier is integrated into Sun Java System Application Server deployment, the deploytool, and the sun-appserv-deploy Ant task. You can also run it as a stand-alone utility from the command line. The verifier is located in the install_dir/bin directory.
When you run the verifier during Sun Java System Application Server deployment, the output of the verifier is written to the tempdir/verifier-results/ directory, where tempdir is the temporary directory defined in the operating system. Deployment fails if any failures are reported during the verification process. The verifier also logs information about verification progress to the standard output.
For details on all the assertions tested by the verifier, see the assertions documentation provided at:
http://java.sun.com/j2ee/avk/index.html
This section covers the following topics:
Command Line Syntax
The verifier tool’s syntax is as follows:
verifier [options] file
The file can be an EAR, WAR, RAR, or JAR file.
The following table shows the options for the verifier tool.
Table 3-4 Verifier Options
Short Form
Long Form
Description
-v
--verbose
Turns on verbose mode.
-d output_dir
--destdir
Writes test results to the output_dir, which must already exist. By default, the results files are created in the current directory.
-r level
--reportlevel level
Sets the output report level to one of the following values:
-n
--notimestamp
Does not append the timestamp to the output file name.
-h or -?
--help
Displays help for the verifier command. If you use this option, you do not need to specify an EAR, WAR, RAR, or JAR file.
-V
--version
Displays the verifier tool version. If you use this option, you do not need to specify an EAR, WAR, RAR, or JAR file.
-u
--gui
Opens a graphical interface for performing verification. If you use this option, you do not need to specify an EAR, WAR, RAR, or JAR file. For more information, see the verifier online help.
For example, the following command runs the verifier in verbose mode and writes all the results of static verification of the ejb.jar file to the output directory ResultsDir:
verifier -v -r a -d ResultsDir ejb.jar
The results files are ejb.jar_verifier.timestamp.txt and ejb.jar_verifier.timestamp.xml. The format of the timestamp is yyyyMMddhhmmss.
If the verifier runs successfully, a result code of 0 is returned. This does not mean that no verification errors occurred. A non-zero error code is returned if the verifier fails to run.
Ant Integration
You can integrate the verifier into an Ant build file as a target and use the Ant call feature to call the target each time an application or module is assembled. This is because the main method in com.sun.enterprise.tools.verifier.Verifier is callable from user Ant scripts. The main method accepts the arguments described in the Verifier Options table.
Example code for an Ant verify target is as follows:
<target name="verify">
<echo message="Verification Process for ${testfile}"/>
<java classname="com.sun.enterprise.tools.verifier.Verifier"
fork="yes">
<sysproperty key="com.sun.enterprise.home"
value="${appserv.home}"/>
<sysproperty key="verifier.xsl"
value="${appserv.home}/verifier/config" />
<!-- uncomment the following for verbose output -->
<!--<arg value="-v"/>-->
<arg value="${assemble}/${ejbjar}" />
<classpath path="${appserv.cpath}:${java.class.path}"/>
</java>
</target>Sample Results Files
Here is a sample results XML file:
<static-verification>
<ejb>
<failed>
<test>
<test-name>
tests.ejb.session.TransactionTypeNullForContainerTX
</test-name>
<test-assertion>
Session bean with bean managed transaction demarcation test
</test-assertion>
<test-description>
For [ TheGreeter ] Error: Session Beans [ TheGreeter ] with [ Bean ] managed transaction demarcation should not have container transactions defined.
</test-description>
</test>
</failed>
</ejb>
...
</static-verification>Here is a sample results TXT file:
---------------------------
STATIC VERIFICATION RESULTS
---------------------------
----------------------------------
NUMBER OF FAILURES/WARNINGS/ERRORS
----------------------------------
# of Failures : 3
# of Warnings : 6
# of Errors : 0-----------------------------
RESULTS FOR EJB-RELATED TESTS
-----------------------------
--------------
FAILED TESTS :
--------------
Test Name : tests.ejb.session.TransactionTypeNullForContainerTX
Test Assertion : Session bean with bean managed transaction demarcation test
Test Description : For [ TheGreeter ]
Error: Session Beans [ TheGreeter ] with [ Bean ] managed transaction demarcation should not have container transactions defined.
...---------------
PASSED TESTS :
---------------
Test Name : tests.ejb.session.ejbcreatemethod.EjbCreateMethodStatic
Test Assertion : Each session Bean must have at least one non-static ejbCreate method test
Test Description : For [ TheGreeter ] For EJB Class [ samples.helloworld.ejb.GreeterEJB ] method [ ejbCreate ] [ samples.helloworld.ejb.GreeterEJB ] properly declares non-static ejbCreate(...) method.
...-----------
WARNINGS :
-----------
Test Name : tests.ejb.businessmethod.BusinessMethodException
Test Assertion : Enterprise bean business method throws RemoteException test
Test Description :
Test Name : tests.ejb.ias.beanpool.IASEjbBeanPool
Test Assertion :
Test Description : WARNING [IAS-EJB ejb] : bean-pool should be defined for Stateless Session and Message Driven Beans
...---------------------
NOTAPPLICABLE TESTS :
---------------------
Test Name : tests.ejb.entity.pkmultiplefield.PrimaryKeyClassFieldsCmp
Test Assertion : Ejb primary key class properly declares all class fields within subset of the names of the container-managed fields test.
Test Description : For [ TheGreeter ] class com.sun.enterprise.tools.verifier.tests.ejb.entity.pkmultiplefield.Primary KeyClassFieldsCmp expected Entity bean, but called with Session.
Test Name : tests.ejb.entity.ejbcreatemethod.EjbCreateMethodReturn
Test Assertion : Each entity Bean can have zero or more ejbCreate methods which return primary key type test
Test Description : For [ TheGreeter ] class com.sun.enterprise.tools.verifier.tests.ejb.entity.ejbcreatemethod.EjbCrea teMethodReturn expected Entity bean, but called with Session bean.
...-----------------------------------
RESULTS FOR OTHER XML-RELATED TESTS
-----------------------------------
---------------
PASSED TESTS :
---------------
Test Name : tests.dd.ParseDD
Test Assertion : Test parses the deployment descriptor using a SAX parser to avoid the dependency on the DOL
Test Description : PASSED [EJB] : [ remote ] and [ home ] tags present.
PASSED [EJB]: session-type is Stateless.
PASSED [EJB]: trans-attribute is NotSupported.
PASSED [EJB]: transaction-type is Bean.
...
Deploying Modules and ApplicationsThis section describes the different ways to deploy J2EE applications and modules to the Sun Java System Application Server. It covers the following topics:
Deployment Errors
If an error occurs during deployment, the application or module is not deployed. If a module within an application contains an error, the entire application is not deployed. This prevents a partial deployment that could leave the server in an inconsistent state.
The Deployment Life Cycle
After an application is initially deployed, it can be modified and reloaded, redeployed, disabled, re-enabled, and finally undeployed (removed from the server). This section covers the following topics related to the deployment life cycle:
Dynamic Deployment
You can deploy, redeploy, and undeploy an application or module without restarting the server. This is called dynamic deployment. This feature is available only on the default server instance.
Although primarily for developers, dynamic deployment can be used in operational environments to bring new applications and modules online without requiring a server restart. Whenever a redeployment is done, the sessions at that transit time become invalid. The client must restart the session.
Disabling a Deployed Application or Module
You can disable a deployed application or module without removing it from the server. Disabling an application makes it inaccessible to clients.
To disable an application or module using the Administration Console:
For details, see the Sun Java System Application Server Administration Guide.
To disable an application or module using the asadmin disable command, see the Sun Java System Application Server Reference Manual.
Dynamic Reloading
If dynamic reloading is enabled (it is by default), you do not have to redeploy an application or module when you change its code or deployment descriptors. All you have to do is copy the changed JSP or class files into the deployment directory for the application or module. The server checks for changes periodically and redeploys the application, automatically and dynamically, with the changes. This feature is available only on the default server instance.
This is useful in a development environment, because it allows code changes to be tested quickly. In a production environment, however, dynamic reloading might degrade performance. In addition, whenever a reload is done, the sessions at that transit time become invalid. The client must restart the session.
To enable dynamic reloading, use the Administration Console:
- Select the Application Settings component under the relevant configuration.
- Check the Reload Enabled box to enable dynamic reloading.
- Enter a number of seconds in the Reload Poll Interval field to set the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.
For details, see the Sun Java System Application Server Administration Guide.
In addition, to load new servlet files, reload EJB related changes, or reload deployment descriptor changes, you must do the following:
Automatic Deployment
Automatic deployment, also called autodeployment, involves copying an application or module file (JAR, WAR, RAR, or EAR) into a special directory, where it is automatically deployed by the Sun Java System Application Server. To undeploy an automatically deployed application or module, simply remove its file from the special autodeployment directory. This is useful in a development environment, because it allows new code to be tested quickly. This feature is available only on the default server instance.
Autodeployment is enabled by default. To enable and configure or to disable autodeployment, use the Administration Console:
- Select the Application Settings component under the relevant configuration.
- Check the Auto Deploy Enabled box to enable autodeployment, or uncheck this box to disable autodeployment.
- Enter a number of seconds in the Auto Deploy Poll Interval field to set the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.
- You can change the Auto Deploy Directory if you like. The default is domain_dir/autodeploy. You can enter an absolute or relative path. A relative path is relative to domain_dir.
- You can check the Verifier Enabled box to verify your deployment descriptor files. This is optional. For details about the verifier, see The Deployment Descriptor Verifier.
- Check the Precompile Enabled box to precompile any JSP files.
For details, see the Sun Java System Application Server Administration Guide.
Tools for Deployment
This section discusses the various tools that can be used to deploy modules and applications. The deployment tools include:
Apache Ant
Ant can help you assemble and deploy modules and applications. For details, see asant Assembly and Deployment Tool.
The deploytool
You can use the deploytool, provided with Sun Java System Application Server, to assemble J2EE applications and modules, configure deployment parameters, perform simple static checks, and deploy the final result. For more information about using the deploytool, see the J2EE 1.4 Tutorial:
http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html
JSR 88
You can write your own JSR 88 client to deploy applications to the Sun Java System Application Server. For more information, see the JSR 88 page:
http://jcp.org/en/jsr/detail?id=88
See Naming Standards for application and module naming considerations.
The asadmin Command
You can use the asadmin deploy or asadmin deploydir command to deploy or undeploy applications and individually deployed modules on local servers. For details, see the Sun Java System Application Server Reference Manual. The asadmin deploydir command is available only on the default server instance.
To deploy a lifecycle module, see Deploying a Lifecycle Module.
Note
On Windows, if you are deploying a directory on a mapped drive, you must be running Sun Java System Application Server as the same user to which the mapped drive is assigned, or Sun Java System Application Server won’t see the directory.
The Administration Console
You can use the Administration Console to deploy modules and applications to both local and remote Sun Java System Application Server sites. To use this tool, follow these steps:
For details, see the Sun Java System Application Server Administration Guide.
To deploy a lifecycle module, see Deploying a Lifecycle Module.
Deployment by Module or Application
You can deploy applications or individual modules that are independent of applications. The runtime and file system implications of application-based or individual module-based deployment are described in Runtime Environments.
Individual module-based deployment is preferable when components need to be accessed by:
Modules can be combined into an EAR file and then deployed as a single module. This is similar to deploying the modules of the EAR independently.
Deploying a WAR Module
You deploy a WAR module as described in Tools for Deployment.
You can precompile JSP files during deployment by checking the appropriate box in the Administration Console or by using the --precompilejsp option of the asadmin deploy or asadmin deploydir command. The sun-appserv-deploy and sun-appserv-jspc Ant tasks also allow you to precompile JSP files.
You can keep the generated source for JSP files by adding the -keepgenerated flag to the jsp-config element in sun-web.xml. If you include this property when you deploy the WAR module, the generated source is kept in domain_dir/generated/jsp/j2ee-apps/app_name/module_name if it is in an application or domain_dir/generated/jsp/j2ee-modules/module_name if it is in an individually deployed web module.
For more information about JSP precompilation, see “Options for Compiling JSP Files” on page 148. For more information about the -keepgenerated property, see “jsp-config” on page 378.
HTTP sessions in WAR modules can be saved in a persistent store in case a server instance fails. For more information, see “Distributed Sessions and Persistence” on page 284 and the Sun Java System Application Server Administration Guide.
Note
After a web application is undeployed, its HttpSession information is not immediately removed if sessions are persistent. HttpSession information is removed in the subsequent cycle, when timed out sessions are removed. Therefore, you should disable a web application before undeploying it if sessions are persistent.
If you are setting up load balancing, web module context roots must be unique within a cluster. See the Sun Java System Application Server Administration Guide for more information about load balancing.
Deploying an EJB JAR Module
You deploy an EJB JAR module as described in Tools for Deployment.
You can keep the generated source for stubs and ties by adding the -keepgenerated flag to the rmic-options attribute of the java-config element in domain.xml. If you include this flag when you deploy the EJB JAR module, the generated source is kept in domain_dir/generated/ejb/j2ee-apps/app_name/module_name if it is in an application or domain_dir/generated/ejb/j2ee-modules/module_name if it is in an individually deployed EJB JAR module. For more information about the -keepgenerated flag, see the Sun Java System Application Server Administration Reference.
Generation of stubs and ties is performed asynchronously, so unless you request their generation during deployment (for example, using the --retrieve option of the asadmin deploy command), stubs and ties are not guaranteed to be available immediately after deployment. You can use the asadmin get-client-stubs command to retrieve the stubs and ties whether or not you requested their generation during deployment. For details, see the Sun Java System Application Server Reference Manual.
Deploying a Lifecycle Module
For general information about lifecycle modules, see Chapter 10, "Developing Lifecycle Listeners."
You can deploy a lifecycle module using the following tools:
- In the Administration Console, open the Applications component and go to the Lifecycle Modules page. For details, see the Sun Java System Application Server Administration Guide.
- Use the asadmin create-lifecycle-module command. For details, see the Sun Java System Application Server Reference Manual.
Deploying an Application Client
Deployment is only necessary for application clients that communicate with EJB components. To deploy an application client:
- Assemble the necessary client files (as described in Chapter 8, "Developing Java Clients").
- Assemble the EJB components to be accessed by the client.
- Package the client and EJB components together in an application.
- Deploy the application as described in Tools for Deployment. You can use the --retrieve option to get the client JAR file.
You can also use the asadmin get-client-stubs command to retrieve the stubs and ties whether or not you requested their generation during deployment. For details, see the Sun Java System Application Server Reference Manual.
- The client JAR contains the ties and necessary classes for the ACC client. Copy this file to the client machine, and set the APPCPATH environment variable on the client to point to this JAR.
To execute the client on the Sun Java System Application Server machine to test it, use the appclient script in the install_dir/bin directory. If you are using the default server instance, the only required option is -client. For example:
appclient -client converterClient.jar
The -xml parameter, which specifies the location of the sun-acc.xml file, is also required if you are not using the default instance.
Before you can execute an ACC client on a different machine, you must prepare the client machine:
- You can use the package-appclient script in the install_dir/bin directory to create the ACC package JAR file. This is optional. This JAR file is created in the install_dir/lib/appclient directory.
- Copy the ACC package JAR file to the client machine and unjar it.
- Configure the sun-acc.xml file, located in the appclient/appserv/lib/appclient directory by default if you used the package-appclient script.
- Configure the asenv.conf (asenv.bat on Windows) file, located in appclient/appserv/bin by default if you used the package-appclient script.
- Copy the client JAR file to the client machine. You are now ready to execute the client.
For more detailed information about the appclient and package-appclient scripts, see Chapter 8, "Developing Java Clients."
Deploying a J2EE CA Resource Adapter
You deploy a connector module as described in Tools for Deployment. After deploying the module, you must configure it as described in Chapter 9, "Developing Connectors."
Access to Shared Frameworks
When J2EE applications and modules use shared framework classes (such as utility classes and libraries) the classes can be put in the path for the System Classloader or the Common Classloader rather than in an application or module. If you assemble a large, shared library into every module that uses it, the result is a huge file that takes too long to register with the server. In addition, several versions of the same class could exist in different classloaders, which is a waste of resources. For more information, see Circumventing Classloader Isolation.
asant Assembly and Deployment ToolApache Ant 1.5.4 is provided with Sun Java System Application Server and can be launched from the bin directory using the command asant. Sun Java System Application Server also provides server-specific tasks for deployment, which are described in this section.
Make sure you have done these things before using asant:
- Include install_dir/bin in the PATH environment variable (/usr/sfw/bin for Sun Java Enterprise System on Solaris). The Ant script provided with Sun Java System Application Server, asant, is located in this directory. For details on how to use asant, see the Sun Java System Application Server Reference Manual and the sample applications documentation in the install_dir/samples/docs/ant.html file.
- If you are executing platform-specific applications, such as the exec or cvs task, the ANT_HOME environment variable must be set to the Ant installation directory.
- Set up your password file. The argument for the passworfile option of each Ant task is a file. This file contains the password attribute name and its value, in the following format:
AS_ADMIN_PASSWORD=password
This section covers the following asant-related topics:
For more information about Ant, see the Apache Software Foundation website:
For information about standard Ant tasks, see the Ant documentation:
http://computing.ee.ethz.ch/sepp/ant-1.5.4-ke/manual/index.html
asant Tasks for Sun Java System Application Server
Use the asant tasks provided by Sun Java System Application Server for assembling, deploying, and undeploying modules and applications, and for configuring the server. The tasks are as follows:
sun-appserv-deploy
Deploys any of the following to a local or remote Sun Java System Application Server instance.
Subelements
The following table describes subelements for the sun-appserv-deploy task. These are objects upon which this task acts.
Table 3-5 sun-appserv-deploy Subelements
Element
Description
A Sun Java System Application Server instance.
A component to be deployed.
A set of component files that match specified parameters.
Attributes
The following table describes attributes for the sun-appserv-deploy task.
Table 3-6 sun-appserv-deploy Attributes
Attribute
Default
Description
file
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.
type
determined by extension
(optional) Deprecated.
force
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.
retrievestubs
client stubs not saved
(optional) The directory where client stubs are saved. This attribute is inherited by nested component elements.
precompilejsp
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.
verify
false
(optional) If true, syntax and semantics for all deployment descriptors are automatically verified for correctness. This attribute is inherited by nested component elements.
contextroot
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.
dbvendorname
sun-ejb-jar.xml entry
(optional) The name of the database vendor for which tables can be created. Allowed values are db2, mssql, oracle, pointbase, 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.
createtables
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.
dropandcreatetables
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.
uniquetablenames
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.
enabled
true
(optional) If true, enables the component.
deploymentplan
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.
availabilityenabled
false
(optional) If true, enables high availability features, including persistence of HTTP sessions and checkpointing of the stateful session bean state.
generatermistubs
false
(optional) If true, generates the static RMI-IIOP stubs and puts them in the client JAR file.
upload
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.
virtualservers
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. This attribute is inherited by nested server elements.
user
admin
(optional) The user name used when logging into the application server administration instance. This attribute is inherited by nested server elements.
password
none
(optional) Deprecated, use passwordfile instead. The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
passwordfile
none
(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements. If both password and passwordfile are specified, passwordfile takes precedence.
host
localhost
(optional) Target server. When deploying to a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.
port
4849
(optional) The administration port on the target server. This attribute is inherited by nested server elements.
target
name of default instance
(optional) Target application server instance. This attribute is inherited by nested server elements.
asinstalldir
see description
(optional) The installation directory for the local Sun Java System 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.
sunonehome
see description
(optional) Deprecated. Use asinstalldir instead.
Examples
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="4849"
target="${default-instance-name}"
asinstalldir="${asinstalldir}" />This example deploys multiple components to the same Sun Java System Application 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 Sun Java System Application 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’s 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>sun-appserv-undeploy
Undeploys any of the following from a local or remote Sun Java System Application Server instance.
Subelements
The following table describes subelements for the sun-appserv-undeploy task. These are objects upon which this task acts.
Table 3-7 sun-appserv-undeploy Subelements
Element
Description
A Sun Java System Application Server instance.
A component to be deployed.
A set of component files that match specified parameters.
Attributes
The following table describes attributes for the sun-appserv-undeploy task.
Table 3-8 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.
file
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.
type
determined by extension
(optional) Deprecated.
droptables
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.
cascade
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.
user
admin
(optional) The user name used when logging into the application server administration instance. This attribute is inherited by nested server elements.
password
none
(optional) Deprecated, use passwordfile instead. The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
passwordfile
none
(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements. If both password and passwordfile are specified, passwordfile takes precedence.
host
localhost
(optional) Target server. When deploying to a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.
port
4849
(optional) The administration port on the target server. This attribute is inherited by nested server elements.
target
name of default instance
(optional) Target application server instance. This attribute is inherited by nested server elements.
asinstalldir
see description
(optional) The installation directory for the local Sun Java System 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.
sunonehome
see description
(optional) Deprecated. Use asinstalldir instead.
Examples
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="4849"
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 Sun Java System Application 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>sun-appserv-instance
Starts, stops, restarts, creates, or removes one or more application server instances.
Subelements
The following table describes subelements for the sun-appserv-instance task. These are objects upon which this task acts.
Table 3-9 sun-appserv-instance Subelements
Element
Description
A Sun Java System Application Server instance.
Attributes
The following table describes attributes for the sun-appserv-instance task.
Table 3-10 sun-appserv-instance Attributes
Attribute
Default
Description
action
none
The control command for the target application server. Valid values are start, stop, restart, create, and delete. A restart sends the stop command followed by the start command. The restart command is not supported on Windows.
debug
false
(optional) Deprecated. If action is set to start or restart, specifies whether the server starts in debug mode. This attribute is ignored for other values of action. If true, the instance generates additional debugging output throughout its lifetime. This attribute is inherited by nested server elements.
instanceport
none
(optional) Deprecated.
nodeagent
none
(required if action is create, otherwise ignored) The name of the node agent on which the instance is being created.
cluster
none
(optional, applicable only if action is create) The clustered instance to be created. The server’s configuration is inherited from the named cluster.
The config and cluster attributes are mutually exclusive. If both are omitted, a stand-alone server instance is created.
config
none
(optional, applicable only if action is create) The configuration for the new stand-alone instance.
The configuration must exist and must not be default-config (the cluster configuration template) or an already referenced stand-alone configuration (including the administration server configuration server-config).
The config and cluster attributes are mutually exclusive. If both are omitted, a stand-alone server instance is created.
property
none
(optional, applicable only if action is create) Defines system properties for the server instance. These properties override port settings in the server instance’s configuration. The following properties are defined: http-listener-1-port, http-listener-2-port, orb-listener-1-port, SSL-port, SSL_MUTUALAUTH-port, JMX_SYSTEM_CONNECTOR_port.
System properties can be changed after instance creation using the system property commands. For details, see the Reference Manual.
user
admin
(optional) The username used when logging into the application server administration instance. This attribute is inherited by nested server elements.
password
none
(optional) Deprecated, use passwordfile instead. The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
passwordfile
none
(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements. If both password and passwordfile are specified, passwordfile takes precedence.
host
localhost
(optional) Target server. If it is a remote server, use the fully qualified hostname. This attribute is inherited by nested server elements.
port
4849
(optional) The administration port on the target server. This attribute is inherited by nested server elements.
instance
name of default instance
(optional) Target application server instance. This attribute is inherited by nested server elements.
asinstalldir
see description
(optional) The installation directory for the local Sun Java System 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.
sunonehome
see description
(optional) Deprecated. Use asinstalldir instead.
Examples
This example starts the local Sun Java System Application 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="4849"
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 Sun Java System Application 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="4849"
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>sun-appserv-component
Enables or disables the following J2EE component types that have been deployed to the Sun Java System Application Server.
You don’t 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
The following table describes subelements for the sun-appserv-component task. These are objects upon which this task acts.
Table 3-11 sun-appserv-component Subelements
Element
Description
A Sun Java System Application Server instance.
A component to be deployed.
A set of component files that match specified parameters.
Attributes
The following table describes attributes for the sun-appserv-component task.
Table 3-12 sun-appserv-component Attributes
Attribute
Default
Description
action
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.
file
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.
type
determined by extension
(optional) Deprecated.
user
admin
(optional) The user name used when logging into the application server administration instance. This attribute is inherited by nested server elements.
password
none
(optional) Deprecated, use passwordfile instead. The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
passwordfile
none
(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements. If both password and passwordfile are specified, passwordfile takes precedence.
host
localhost
(optional) Target server. When enabling or disabling a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.
port
4849
(optional) The administration port on the target server. This attribute is inherited by nested server elements.
target
name of default instance
(optional) Target application server instance. This attribute is inherited by nested server elements.
asinstalldir
see description
(optional) The installation directory for the local Sun Java System 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.
sunonehome
see description
(optional) Deprecated. Use asinstalldir instead.
Examples
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="4849"
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 Sun Java System Application 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>sun-appserv-admin
Enables arbitrary administrative commands and scripts to be executed on the Sun Java System Application Server. This is useful for cases where a specific Ant task hasn’t been developed or a set of related commands are in a single script.
Subelements
The following table describes subelements for the sun-appserv-admin task. These are objects upon which this task acts.
Table 3-13 sun-appserv-admin Subelements
Element
Description
A Sun Java System Application Server instance.
Attributes
The following table describes attributes for the sun-appserv-admin task.
Table 3-14 sun-appserv-admin Attributes
Attribute
Default
Description
command
none
(exactly one of these is required: command, commandfile, or explicitcommand) The command to execute. If the user, passwordfile, host, or port, or target 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.
commandfile
none
(exactly one of these is required: command, commandfile, or explicitcommand) Deprecated. The command script to execute. If commandfile is used, the values of all other attributes are ignored. Be sure to end the script referenced by commandfile with the exit command; if you omit exit, the Ant task might appear to hang after the command script is called.
explicitcommand
none
(exactly one of these is required: command, commandfile, 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 administration instance. This attribute is inherited by nested server elements.
password
none
(optional) Deprecated, use passwordfile instead. The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
passwordfile
none
(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements. If both password and passwordfile are specified, passwordfile takes precedence.
host
localhost
(optional) Target server. If it is a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.
port
4849
(optional) The administration port on the target server. This attribute is inherited by nested server elements.
asinstalldir
see description
(optional) The installation directory for the local Sun Java System 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.
sunonehome
see description
(optional) Deprecated. Use asinstalldir instead.
Examples
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 commandfile to execute the create-jms-dest command:
<sun-appserv-admin commandfile="create_jms_dest.txt" instance="development">
The create_jms_dest.txt file contains the following:
create-jms-dest --user admin --passwordfile "${passwordfile}" --host localhost --port 4849 --desttype topic --target server1 simpleJmsDest
Here is an example of using explicitcommand to execute the create-jms-dest command:
<sun-appserv-admin command="create-jms-dest --user admin --passwordfile "${passwordfile}" --host localhost --port 4849 --desttype topic --target server1 simpleJmsDest">
sun-appserv-jspc
Precompiles JSP source code into Sun Java System Application Server compatible Java code for initial invocation by Sun Java System 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.
Subelements
none
Attributes
The following table describes attributes for the sun-appserv-jspc task.
Table 3-15 sun-appserv-jspc Attributes
Attribute
Default
Description
destdir
The destination directory for the generated Java source files.
srcdir
(exactly one of these is required: srcdir or webapp) The source directory where the JSP files are located.
webapp
(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.
verbose
2
(optional) The verbosity integer to be passed to the compiler.
classpath
(optional) The classpath for running the JSP compiler.
classpathref
(optional) A reference to the JSP compiler classpath.
uribase
/
(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.
uriroot
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 sun-appserv-jspc was called from is used. Only pages translated from an explicitly declared JSP file (including tag libraries) are affected.
package
(optional) The destination package for the generated Java classes.
asinstalldir
see description
(optional) The installation directory for the local Sun Java System 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.
sunonehome
see description
(optional) Deprecated. Use asinstalldir instead.
Example
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>sun-appserv-update
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.
Subelements
none
Attributes
The following table describes attributes for the sun-appserv-update task.
Table 3-16 sun-appserv-update Attributes
Attribute
Default
Description
file
none
The component to update, which must be a valid archive.
domain
domain1
(optional) The domain in which the application has been previously deployed.
Example
The following example updates the J2EE application foo.ear, which is deployed to the default domain, domain1.
<sun-appserv-update file="foo.ear"/>
Reusable Subelements
Reusable subelements of the Ant tasks for the Sun Java System Application Server are as follows. These are objects upon which the Ant tasks act.
server
Specifies a Sun Java System Application 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.
Subelements
none
Attributes
The following table describes attributes for the server element.
Table 3-17 server Attributes
Attribute
Default
Description
user
admin
(optional) The username used when logging into the application server administration instance.
password
none
(optional) Deprecated, use passwordfile instead. The password used when logging into the application server administration instance.
passwordfile
none
(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. If both password and passwordfile are specified, passwordfile takes precedence.
host
localhost
(optional) Target server. When targeting a remote server, use the fully qualified hostname.
port
4849
(optional) The administration port on the target server.
instance
name of default instance
(optional) Target application server instance.
domain
(applies to sun-appserv-update only) The domain in which the application has been previously deployed.
instanceport
none
(applies to sun-appserv-instance only) Deprecated.
nodeagent
none
(applies to sun-appserv-instance only, required if action is create, otherwise ignored) The name of the node agent on which the instance is being created.
debug
false
(applies to sun-appserv-instance only, optional) Deprecated. If action is set to start, specifies whether the server starts in debug mode. This attribute is ignored for other values of action. If true, the instance generates additional debugging output throughout its lifetime.
upload
true
(applies to sun-appserv-deploy only, 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.
virtualservers
default virtual server only
(applies to sun-appserv-deploy 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.
Examples
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.sun.com" passwordfile="${password.greg}"/>
<server host="joe.sun.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.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>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.sun.com" instanceport="8080" instance="qa"/>
<server host="joe.sun.com" instanceport="9090"
instance="integration-test"/>
</sun-appserv-instance>You can deploy multiple components to multiple servers (see the component nested element. This example deploys each component to two Sun Java System Application Server instances running on remote servers. Both servers use the same password.
<sun-appserv-deploy passwordfile="${passwordfile}" asinstalldir="/opt/s1as8" >
<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>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.sun.com"/>
<server host="joe.sun.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.sun.com"/>
<server host="joe.sun.com"/>
<component file="${assemble}/simpleapp.ear"/>
<component file="${assemble}/simpleservlet.war"/>
<component name="simplebean" />
</sun-appserv-component>component
Specifies a J2EE 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.
Subelements
none
Attributes
The following table describes attributes for the component element.
Table 3-18 component Attributes
Attribute
Default
Description
file
none
(optional if the parent task is sun-appserv-undeploy or sun-appserv-component) The target component. 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.
type
determined by extension
(optional) Deprecated.
force
true
(applies to sun-appserv-deploy only, optional) If true, the component is overwritten if it already exists on the server. If false, the containing element’s operation fails if the component exists.
precompilejsp
false
(applies to sun-appserv-deploy only, 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.
retrievestubs
client stubs not saved
(applies to sun-appserv-deploy only, optional) The directory where client stubs are saved.
contextroot
file name without extension
(applies to sun-appserv-deploy only, optional) The context root for a web module (WAR file). This attribute is ignored if the component is not a WAR file.
verify
false
(applies to sun-appserv-deploy only, optional) If true, syntax and semantics for all deployment descriptors is automatically verified for correctness.
Examples
You can deploy multiple components using a single task. This example deploys each component to the same Sun Java System Application Server instance running on a remote server.
<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.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.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>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.sun.com"/>
<server host="joe.sun.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.sun.com"/>
<server host="joe.sun.com"/>
<component file="${assemble}/simpleapp.ear"/>
<component file="${assemble}/simpleservlet.war"/>
<component name="simplebean" />
</sun-appserv-component>fileset
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://computing.ee.ethz.ch/sepp/ant-1.5.4-ke/manual/CoreTypes/fileset.html