Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Application Server Enterprise Edition 8.1 2005Q1 Developer's Guide 

Chapter 3
Assembling and Deploying Applications

This 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 Deployment

Application 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:

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

Figure shows EJB or Web 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

Figure shows J2EE 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:

http://java.sun.com/products/

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.

Table 3-1  J2EE Standard Descriptors 

Deployment Descriptor

Where to Find More Information

application.xml

Java 2 Platform Enterprise Edition Specification, v1.4, Chapter 8, “Application Assembly and Deployment - J2EE:application XML DTD”

web.xml

Java Servlet Specification, v2.4 Chapter 13, “Deployment Descriptor,” and JavaServer Pages Specification, v2.0, Chapter 7, “JSP Pages as XML Documents,” and Chapter 5, “Tag Extensions”

ejb-jar.xml

Enterprise JavaBeans Specification, v2.1, Chapter 16, “Deployment Descriptor”

application-client.xml

Java 2 Platform Enterprise Edition Specification, v1.4, Chapter 9, “Application Clients - J2EE:application-client XML DTD”

ra.xml

Java 2 Enterprise Edition, J2EE Connector Architecture Specification, v1.0, Chapter 10, “Packaging and Deployment.”

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.”

Table 3-2  Sun Java System Application Server Descriptors 

Deployment Descriptor

DTD File

Description

sun-application.xml

sun-application_1_4-0.dtd

Configures an entire J2EE application (EAR file).

sun-web.xml

sun-web-app_2_4-1.dtd

Configures a web application (WAR file).

sun-ejb-jar.xml

sun-ejb-jar_2_1-1.dtd

Configures an enterprise bean (EJB JAR file).

sun-cmp-mappings.xml

sun-cmp-mapping_1_2.dtd

Configures container-managed persistence for an enterprise bean.

sun-application-client.xml

sun-application-client_1_4-1.dtd

Configures an Application Client Container (ACC) client (JAR file).

sun-acc.xml

sun-application-client-container_1_0.dtd

Configures the Application Client Container.

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.

+ converter_1/

|--- converterClient.jar

|--+ META-INF/

|  |--- MANIFEST.MF

|  |--- application.xml

|  '--- sun-application.xml

|--+ war-ic_war/

|  |--- index.jsp

|  |--+ META-INF/

|  |  |--- MANIFEST.MF

|  '--+ WEB-INF/

|     |--- web.xml

|     '--- sun-web.xml

|--+ ejb-jar-ic_jar/

|  |--- Converter.class

|  |--- ConverterBean.class

|  |--- ConverterHome.class

|  '--+ META-INF/

|     |--- MANIFEST.MF

|     |--- ejb-jar.xml

|     '--- sun-ejb-jar.xml

'--+ app-client-ic_jar/

   |--- ConverterClient.class

   '--+ META-INF/

      |--- MANIFEST.MF

      |--- application-client.xml

      '--- sun-application-client.xml

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

Figure shows the 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_name

The 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

Figure shows the 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_name

The 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

Figure shows the 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.

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:

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:

  1. Deploy the dependent application.
  2. 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.
  3. 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.
  4. Deploy the calling application.

  5. Note

    The calling EJB or web component must specify in its sun-ejb-jar.xml or sun-web.xml file the JNDI name of the EJB component in the dependent application. Using an ejb-link mapping does not work when the EJB component being called resides in another application.



Assembling Modules and Applications

Assembling (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


Tip

Using the verifier tool can help you avoid runtime errors that are difficult to debug.


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:

  • a or all - Reports all results. This is the default in both verbose and non verbose modes.
  • w or warnings - Reports only warning and failure results.
  • f or failures - Reports only failure results.

-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 Applications

This 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:

  1. Open the Applications component.
  2. Go to the page for the type of application or module. For example, for a web application, go to the Web Applications page.
  3. Click on the name of the application or module you wish to disable.
  4. Uncheck the Status Enabled box.

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:

  1. Select the Application Settings component under the relevant configuration.
  2. Check the Reload Enabled box to enable dynamic reloading.
  3. 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:

  1. Create an empty file named .reload at the root of the deployed application:
  2. domain_dir/applications/j2ee-apps/app_name/.reload

  1. Explicitly update the .reload file’s timestamp (touch .reload in UNIX) each time you make the above changes.

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:

  1. Select the Application Settings component under the relevant configuration.
  2. Check the Auto Deploy Enabled box to enable autodeployment, or uncheck this box to disable autodeployment.
  3. 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.
  4. 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.
  5. 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.
  6. 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:

  1. Open the Applications component.
  2. Go to the page for the type of application or module. For example, for a web application, go to the Web Applications page.
  3. Click on the Deploy button. (You can also undeploy, enable, or disable an application or module from this page.)

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:

Deploying an Application Client

Deployment is only necessary for application clients that communicate with EJB components. To deploy an application client:

  1. Assemble the necessary client files (as described in Chapter 8, "Developing Java Clients").
  2. Assemble the EJB components to be accessed by the client.
  3. Package the client and EJB components together in an application.
  4. Deploy the application as described in Tools for Deployment. You can use the --retrieve option to get the client JAR file.
  5. 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.

  6. 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:

  1. 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.
  2. Copy the ACC package JAR file to the client machine and unjar it.
  3. Configure the sun-acc.xml file, located in the appclient/appserv/lib/appclient directory by default if you used the package-appclient script.
  4. Configure the asenv.conf (asenv.bat on Windows) file, located in appclient/appserv/bin by default if you used the package-appclient script.
  5. 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 Tool

Apache 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:

This section covers the following asant-related topics:

For more information about Ant, see the Apache Software Foundation website:

http://ant.apache.org/

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

server

A Sun Java System Application Server instance.

component

A component to be deployed.

fileset

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

server

A Sun Java System Application Server instance.

component

A component to be deployed.

fileset

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

server

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

server

A Sun Java System Application Server instance.

component

A component to be deployed.

fileset

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

server

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



Previous      Contents      Index      Next     


Part No: 819-0217.   Copyright 2004 - 2005 Sun Microsystems, Inc. All rights reserved.