test

Sun Java System Application Server 9.1 Application Deployment Guide

Chapter 1 Assembling and Deploying Applications

This chapter describes Sun JavaTM System Application Server modules and how these modules are assembled separately or together in an application. This chapter also describes tools for assembly and deployment.

The Application Server modules and applications include Java Platform, Enterprise Edition (Java EE platform) standard features and Application Server specific features. Only Application Server specific features are described in detail in this chapter.

The following topics are presented in this chapter:

Note –

Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile or the enterprise profile. For information about profiles, see Usage Profiles in Sun Java System Application Server 9.1 Administration Guide.

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 Java-EE-compliant application server. A package can be classified either as a module or as a full-fledged application. This section covers the following topics:

About Modules

A Java EE module is a collection of one or more Java EE components that execute in the same container type (for example, web or EJB) with annotations or deployment descriptors of that type. One descriptor is Java EE standard, the other is optional and Application Server specific. Annotations can be used instead of Java EE standard descriptors.

Types of Java EE modules are as follows:

Package definitions must be used in the source code of all modules so the class loader 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 Java EE server reads this information and acts accordingly.

The Application Server also supports lifecycle modules. See Chapter 13, Developing Lifecycle Listeners, in Sun Java System Application Server 9.1 Developer’s Guide for more information.

EJB JAR, Web, and application client modules can also be deployed separately, outside of any application, as in the following figure. EJB components are assembled in a JAR file with annotations or ejb-jar.xml and sun-ejb-jar.xml deployment descriptors. Web components are assembled in a WAR file with annotations or web.xml and sun-web.xml deployment descriptors. Application client components are assembled in a JAR file with application-client.xml and sun-application-client.xml deployment descriptors. These module types are deployed to the Application Server.

Figure 1–1 Module Assembly and Deployment

Figure shows EJB or Web module assembly and deployment.

About Applications

A Java EE application is a logical collection of one or more Java EE modules tied together by application annotations or 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 an Application Server application and deployed. EJB components are assembled in a JAR file with annotations or ejb-jar.xml and sun-ejb-jar.xml deployment descriptors. Web components are assembled in a WAR file with annotations or web.xml and sun-web.xml deployment descriptors. An application client is assembled in a JAR file with application-client.xml and sun-application-client.xml deployment descriptors. A resource adapter is assembled in a RAR file with a ra.xml deployment descriptor. All modules are assembled in an EAR file and deployed to the Application Server.

Figure 1–2 Application Assembly and Deployment

Figure shows Java EE application assembly and deployment.

Each module has an optional Application Server deployment descriptor and annotations or a Java EE deployment descriptor. The Application Server uses the annotations or deployment descriptors to deploy the application components and to register the resources with the Application Server.

An application consists of one or more modules, an optional Application Server deployment descriptor, and annotations or a Java EE application deployment descriptor. All items are assembled, using the Java ARchive (.jar) file format, into one file with an extension of .ear.

Java EE Standard Annotation

The Application Server supports applications and modules annotated according to the following specifications:

The following annotation and deployment descriptor combinations are supported:

To check the correctness of annotations or deployment descriptors prior to deployment, see The verifier Utility.

Java EE Standard Descriptors

Java EE standard deployment descriptors are described in the Java EE specification, v5. You can find the specification at http://java.sun.com/products/. Information about the XML schemas that define Java EE standard deployment descriptors is available at http://java.sun.com/xml/ns/javaee/.

Application Server Descriptors

The Application Server uses additional, optional deployment descriptors for configuring features specific to the Application Server.

To check the correctness of these deployment descriptors prior to deployment, see The verifier Utility.

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 an 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 Admin Console or the asadmin command. See Tools for Deployment.

You can specify a name in one of these ways:

Make sure your package and file names do not contain spaces or characters that are illegal for your operating system.

Using a Java package-like naming scheme is recommended for module filenames, EAR filenames, module names as found in the <module-name> portion of the ejb-jar.xml files, and EJB names as found in the <ejb-name> portion of the ejb-jar.xml files. The use of this package-like naming scheme ensures that name collisions do not occur. The benefits of this naming practice apply not only to the Application Server, but to other Java EE application servers as well.

JNDI lookup names for EJB components must also be unique. Establishing a consistent naming convention might help. For example, appending the application name and the module name to the EJB name is one way to guarantee unique names. In this case, mycompany.pkging.pkgingEJB.MyEJB would be the JNDI name for an EJB in the module pkgingEJB.jar, which is packaged in the application pkging.ear.

If you are writing your own JSR 88 client to deploy applications to the Application Server using the following API, the name of the application is taken from the display-name entry in the Java EE 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 Admin Console nor the asadmin command uses this API.

Note –

Use of the following JSR 88 API is preferred. In this case, the name is derived from the file name as previously described.

javax.enterprise.deploy.spi.DeploymentManager.distribute(Target[], File, File)

For more information about JSR 88, see the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.

Directory Structure

When you deploy an application, the application is expanded from the EAR file to an open directory structure. 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 Java EE specification.

Assembling Modules and Applications

Assembling (or packaging) modules and applications in Application Server conforms to all of the customary Java-EE-defined specifications. The only difference is that when you assemble in Application Server, you can include optional Application Server specific deployment descriptors that enhance the functionality of the Application Server. You can also package the Application Server specific deployment descriptors separately in a deployment plan; see Using a Deployment Plan.

For example, when you assemble an EJB JAR module, you annotate or create two deployment descriptor files with these names: ejb-jar.xml and sun-ejb-jar.xml. 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. For more information about sun-ejb-jar.xml and sun-cmp-mapping.xml, see Appendix A, Deployment Descriptor Files.

Note –

According to the Java EE 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 Chapter 2, Class Loaders, in Sun Java System Application Server 9.1 Developer’s Guide.

The Application Server provides these tools for assembling and verifying a module or an application:

The asant Utility

The asant utility can help you assemble and deploy modules and applications. For details, see Chapter 3, The asant Utility, in Sun Java System Application Server 9.1 Developer’s Guide.

The NetBeans IDE

You can use the NetBeansTM Integrated Development Environment (IDE) to assemble Java EE applications and modules. The GlassFish edition of the Application Server is bundled with the NetBeans 5.5 IDE. For more information about using the NetBeans IDE, see http://www.netbeans.org.

The verifier Utility

The verifier utility validates Java EE annotations and deployment descriptors and Application Server specific deployment descriptors against their corresponding DTD or schema files. It gives errors and warnings if a module or application is not Java EE and 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 Application Server deployment and the asant task The sun-appserv-deploy Task in Sun Java System Application Server 9.1 Developer’s Guide. You can also run it as a stand-alone utility from the command line. The verifier utility is located in the as-install/bin directory.

You can run the verifier during Application Server deployment using the Admin Console or the asadmin deploy command with the --verify="true" option (see The asadmin Deployment Commands and The Admin Console Deployment Pages). In these cases, 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 1–1 Verifier Options

Short Form 

Long Form 

Description 

-v

--verbose

Turns on verbose mode. In verbose mode, the status of each run of each test is displayed on the verifier console. 

-d output-dir

--destdir output-dir

Writes test results to the output-dir, which must already exist. By default, the results files are created in the current directory.

-D domain-dir

--domain domain-dir

Specifies the absolute path to the domain directory. This option is ignored if the -p option is used. The default domain directory isas-install/domains/domain1.

-rlevel

--reportlevel level

Sets the output report level to one of the following values:

  • a or all - Reports all results.

  • w or warnings - Reports only warning and failure results. This is the default.

  • f or failures - Reports only failure results.

-t

--timestamp

Appends a timestamp to the output file name. The format of the timestamp is yyyyMMddhhmmss. 

-?

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

-p

--portability

Verifies portable features only. By default, the verifier also checks correct usage of Application Server features in the sun-*.xml deployment descriptor files.

-a

--app

Runs only the application tests. 

-A

--appclient

Runs only the application client tests. 

-c

--connector

Runs only the connector tests. 

-e

--ejb

Runs only the EJB tests. 

-w

--web

Runs only the web module tests. 

-s

--webservices

Runs only the web service tests. 

-l

--webservicesclient

Runs only the web service client tests. 

For example, the following command runs the verifier on the ejb.jar file with default settings:

verifier ejb.jar

The results files are ejb.jar.txt and ejb.jar.xml.

For a more complex example, the following command runs the verifier on the ejb.jar file in portability mode displaying only failures and with a timestamp:

verifier -p -rf -t ejb.jar

The results files are ejb.jartimestamp.txt and ejb.jartimestamp.xml. The format of the timestamp is yyyyMMddhhmmss.

If the verifier runs successfully and no verification errors occurred, a result code of 0 is returned. A nonzero error code is returned if errors occurred or 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. You can use any of the arguments described in Table 1–1. Example code for an Ant verify target is as follows:

<?xml version="1.0" encoding="iso-8859-1"?>
<project name="Verifier Launcher" default="verify">
    <target name="verify" description="verify using verifier script">
        <exec executable="as-install/bin/verifier" 
                failonerror="true" vmlauncher="false">
            <arg line="-d /tmp path-to-app"/>
        </exec>
    </target>
</project>

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 : 1
# of Warnings : 0
# of Errors : 0

-----------------------------
RESULTS FOR EJB-RELATED TESTS
-----------------------------

--------------
FAILED TESTS : 
--------------

Test Name : tests.ejb.ejb30.BusinessIntfInheritance
Test Assertion : A business interface must not extend javax.ejb.EJBObject 
or javax.ejb.EJBLocalObject. Please refer to EJB 3.0 Simplified API Section 
#3.2 for further information.
Test Description : For [ sessionApp#session-ejb.jar#HelloEJB ]
[ com.sun.sample.session.Hello ] extends either javax.ejb.EJBObject or 
javax.ejb.EJBLocalObject.


----------------------------------
END OF STATIC VERIFICATION RESULTS
----------------------------------

Deploying Modules and Applications

This section describes the different ways to deploy Java EE applications and modules to the 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.

In addition, certain warning conditions allow an application to be deployed but return a warning message to the deployment client.

The Deployment Life Cycle

After installing the Application Server and starting a domain, you can deploy (install) Java EE applications and modules. During deployment and as the application is changed, an application or module can go through the following stages:

  1. Initial Deployment

    Before deploying an application or module, start the domain.

    Deploy (install) an application or module to a specific stand-alone server instance or cluster. Because applications and modules are packaged in archive files, specify the archive file name during deployment. The default is to deploy to the default server instance server.

    If you deploy to server instances or clusters, the application or module exists in the domain’s central repository and is referenced by any clusters or server instances you deployed to as targets.

    You can also deploy to the domain using the asadmin deploy or asadmin deploydir command or the Admin Console. In the cluster profile, the preselected deployment target is server. To deploy only to the domain, specify no target. If you deploy the application or module only to the domain, it exists in the domain’s central repository, but no server instances or clusters reference it until you add references.

    Deployment is dynamic: you don’t need to restart the server instance after deploying application or module for applications to be available. If you do restart, all deployed applications and modules are still deployed and available.

  2. Enabling or Disabling

    By default, a deployed application or module is enabled, which means that it is runnable and can be accessed by clients if it has been deployed to an accessible server instance or cluster. To prevent access, disable the application or module. A disabled application or module is not uninstalled from the domain and can be easily enabled after deployment. For more information, see Disabling a Deployed Application or Module.

  3. Adding or Deleting Targets for a Deployed Application or Module

    Once deployed, the application or module exists in the central repository and can be referenced by a number of server instances and/or clusters. Initially, the server instances or clusters you deployed to as targets reference the application or module.

    To change which server instances and clusters reference an application or module after it is deployed, change an application or module’s targets using the Admin Console, or change the application references using the asadmin tool. Because the application itself is stored in the central repository, adding or deleting targets adds or deletes the same version of an application on different targets. However, an application deployed to more than one target can be enabled on one and disabled on another, so even if an application is referenced by a target, it is not available to users unless it is enabled on that target.

  4. Redeployment

    To replace a deployed application or module, redeploy it. Redeploying automatically undeploys the previously deployed application or module and replaces it with the new one.

    When redeploying through the Admin Console, the redeployed application or module is deployed to the domain, and all stand-alone or clustered server instances that reference it automatically receive the new version if dynamic reconfiguration is enabled. If using the asadmin deploy command to redeploy, specify domain as the target.

    If an application is deployed on one target only and you are redeploying using asadmin, specify the same target during redeployment.

    For production environments, perform a rolling upgrade, which upgrades the application or module without interruption in service. For more information, see To Upgrade Components Without Loss of Service in Sun Java System Application Server 9.1 High Availability Administration Guide.

  5. Undeployment

    To uninstall an application or module, undeploy it.

Deployment for Development

This section covers the following topics related to deployment for development:

Note –

You can overwrite a previously deployed application by using the --force option of asadmin deploy or asadmin deploydir or by selecting the Redeploy button in the Admin Console. However, you must remove a preconfigured resource before you can update it.

Dynamic Deployment

You can deploy, redeploy, and undeploy an application or module without restarting the server instances. This is called dynamic deployment. 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 asadmin disable command, see the Sun Java System Application Server 9.1 Reference Manual.

ProcedureTo Disable an Application or Module in the Admin 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 box to the left of the name of each application or module you wish to disable.

  4. Click on the Disable button.

See Also

For details, click the Help button in the Admin Console.

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. Simply 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. Deployment directories are as follows:

For an application:

domain-dir/applications/j2ee-apps/app-name

For an individually deployed module:

domain-dir/applications/j2ee-modules/module-name

Dynamic reloading 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.

You can also use the sun-appserv-update task with the asant utility to update an application or module. See Chapter 3, The asant Utility, in Sun Java System Application Server 9.1 Developer’s Guide.

ProcedureTo Enable Dynamic Reloading in the Admin Console

  1. To access reloading features:

    • In the developer profile:

      1. Select the Application Server component.

      2. Select the Advanced tab.

      3. Select the Applications Configuration tab.

    • In the cluster profile:

      1. Select the Stand-Alone Instances component.

      2. Select the instance named server in the table.

        This is the Admin Server.

      3. Select the Advanced tab.

  2. Check the Reload Enabled box to enable dynamic reloading.

  3. Enter a number of seconds in the Reload Poll Interval field.

    This sets the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.

See Also

For details, click the Help button in the Admin Console.

ProcedureTo Reload Code or Deployment Descriptor Changes

  1. Create an empty file named .reload at the root of the deployed application or module.

    For an application:

    domain-dir/applications/j2ee-apps/app-name/.reload

    For an individually deployed module:

    domain-dir/applications/j2ee-modules/module-name/.reload

  2. Explicitly update the .reload file’s timestamp (touch .reload in UNIX) each time you make 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 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 of a web services JSR 181 annotated file is supported. For more information, see JSR 181 and Chapter 6, Developing Web Services, in Sun Java System Application Server 9.1 Developer’s Guide.

Autodeployment is enabled by default.

ProcedureTo Enable and Configure or to Disable Autodeployment

  1. To access autodeployment features:

    • In the developer profile:

      1. Select the Application Server component.

      2. Select the Advanced tab.

      3. Select the Applications Configuration tab.

    • In the cluster profile:

      1. Select the Stand-Alone Instances component.

      2. Select the instance named server in the table.

        This is the Admin Server.

      3. Select the Advanced tab.

  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.

    This sets 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.

    You can enter an absolute or relative path. A relative path is relative to domain-dir. The default is domain-dir/autodeploy.

  5. You can check the Verifier Enabled box to verify your deployment descriptor files. This is optional.

    For details about the verifier, see The verifier Utility.

  6. Check the Precompile Enabled box to precompile any JSP files.

See Also

For details, click the Help button in the Admin Console.

Directory Deployment

A directory containing an unpackaged application or module is sometimes called an exploded directory. To deploy a directory instead of an EAR, WAR, JAR, or RAR file, you can do one of the following:

The contents of the directory must match the contents of a corresponding Java EE archive file. For example, if you deploy a Web application from a directory, the contents of the directory must be the same as a corresponding WAR file. In addition, the directories holding the individual modules must be named with _jar, _war and _rar suffixes. For information about the required directory contents, see the appropriate specifications.

You can change the deployment descriptor files directly in the exploded directory. If your environment is configured to use dynamic reloading, you can also dynamically reload applications deployed from the directory. For more information, see Dynamic Reloading.

Note –

On Windows, if you are deploying a directory on a mapped drive, you must be running the Application Server as the same user to which the mapped drive is assigned, or the Application Server won’t see the directory.

Using a Deployment Plan

This feature is for advanced developers.

A deployment plan is an JAR file that contains only the deployment descriptors that are specific to the Application Server. The deployment plan is part of the implementation of JSR 88. Use a deployment plan to deploy an application or module that does not contain the deployment descriptors that are specific to the Application Server. For more information about JSR 88, see the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.

To deploy using a deployment plan, specify the --deploymentplan option of the asadmin deploy command. The following command, for example, deploys the enterprise application in the myrostapp.ear file according to the plan specified by the mydeployplan.jar file.


$ asadmin deploy --user admin --deploymentplan mydeployplan.jar myrostapp.ear

In the deployment plan file for an enterprise application (EAR), the sun-application.xml file is located at the root. The deployment descriptor for each module is stored according to this syntax: module-name.sun-dd-name, where the sun-dd-name depends on the module type. If a module contains a CMP mappings file, the file is named module-name.sun-cmp-mappings.xml. A .dbschema file is stored at the root level with each forward slash character (/) replaced by a pound sign (#). The following listing shows the structure of the deployment plan file for an enterprise application (EAR).

$ jar -tvf mydeployplan.jar
420 Thu Mar 13 15:37:48 PST 2003 sun-application.xml
370 Thu Mar 13 15:37:48 PST 2003 RosterClient.war.sun-web.xml
418 Thu Mar 13 15:37:48 PST 2003 roster-ac.jar.sun-application-client.xml
1281 Thu Mar 13 15:37:48 PST 2003 roster-ejb.jar.sun-ejb-jar.xml
2317 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.sun-ejb-jar.xml
3432 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.sun-cmp-mappings.xml
84805 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.RosterSchema.dbschema

In the deployment plan for a web application or a module file, the deployment descriptor that is specific to the Application Server is at the root level. If a stand-alone EJB module contains a CMP bean, the deployment plan includes the sun-cmp-mappings.xml and .dbschema files at the root level. In the following listing, the deployment plan describes a CMP bean.

$ jar r -tvf myotherplan.jar
3603 Thu Mar 13 15:24:20 PST 2003 sun-ejb-jar.xml
3432 Thu Mar 13 15:24:20 PST 2003 sun-cmp-mappings.xml
84805 Thu Mar 13 15:24:20 PST 2003 RosterSchema.dbschema

Tools for Deployment

This section discusses the various tools that can be used to deploy modules and applications. The deployment tools include:

The asant Utility

The asant utility can help you assemble and deploy modules and applications. For details, see Chapter 3, The asant Utility, in Sun Java System Application Server 9.1 Developer’s Guide.

JSR 88

You can write your own JSR 88 client to deploy applications to the Application Server. For more information, see the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.

The syntax of the URI entry for the getDeploymentManager method is as follows:

deployer:Sun:AppServer::admin-host:admin-port[:https]

The :https is not needed by default in the developer profile and needed by default in the cluster profile. For example:

deployer:Sun:AppServer::localhost:4848:https

See Naming Standards for application and module naming considerations.

The asadmin Deployment Commands

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 Directory Deployment and the Sun Java System Application Server 9.1 Reference Manual. The asadmin deploydir command is available only on the default server instance.

To deploy a lifecycle module, see Deploying a Lifecycle Module.

The Admin Console Deployment Pages

You can use the Admin Console to deploy modules and applications to both local and remote Application Server sites.

ProcedureTo Use the Admin Console for Deployment

  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. In the developer profile, you can undeploy, enable, or disable an application or module from the table on this page. In the cluster profile, click on the link in the Status column to undeploy, enable, or disable an application or module on specific targets.

  3. Click on the Deploy button.

    On this page, you type the path to the WAR, JAR, EAR, or RAR file or the exploded directory structure. You can also specify deployment settings that vary according to the type of application or module.

See Also

For details, click the Help button in the Admin Console.

To deploy a lifecycle module, see Deploying a Lifecycle Module.

For more information on deploying from an exploded directory structure, see Directory Deployment.

Deployment by Module or Application

You can deploy applications or individual modules that are independent of applications; see About Modules and About Applications. 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 Web Service

You deploy a web service endpoint to the Application Server just as you would any servlet or stateless session bean (SLSB).

Web service management is fully supported in the Admin Console. If the deployed application or module has a web service endpoint, it is detected automatically during deployment. Once the application or module is deployed, click on the Web Service component. The table in the right frame lists deployed web service endpoints.

You can use the --registryjndiname option of the asadmin deploy or asadmin deploydir command to publish the web service as part of deployment, but this is optional. See Tools for Deployment.

To deploy a JSR 181 annotated file, use the autodeployment feature. You can compile and deploy in one step, as in the following example:


javac -cp javaee.jar -d domain-dir/autodeploy MyWS.java

For more information about JSR 181, see http://jcp.org/en/jsr/detail?id=181. For more information about autodeployment, see Automatic Deployment.

The Sun-specific deployment descriptor files sun-web.xml and sun-ejb-jar.xml provide optional web service enhancements in their webservice-endpoint and webservice-description elements.

For more information about web services, see JSR 181 and Chapter 6, Developing Web Services, in Sun Java System Application Server 9.1 Developer’s Guide.

Deploying a WAR Module

You deploy a WAR module as described in Tools for Deployment. If you do not specify a context root, the default is the name of the WAR file without the extension.

If a web application accesses a DataSource that is not specified in a resource-ref in sun-web.xml, or there is no sun-web.xml file, the resource-ref-name defined in web.xml is used. A warning message is logged recording the JNDI name used to look up the resource.

You can precompile JSP files during deployment by checking the appropriate box in the Admin Console, or by using the --precompilejsp option of the asadmin deploy or asadmin deploydir command. The asant tasks sun-appserv-deploy and sun-appserv-jspc also allow you to precompile JSP files. For more information, see Chapter 3, The asant Utility, in Sun Java System Application Server 9.1 Developer’s Guide.

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 jsp-config and Options for Compiling JSP Files in Sun Java System Application Server 9.1 Developer’s Guide.

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 in Sun Java System Application Server 9.1 Developer’s Guide and the Sun Java System Application Server 9.1 High Availability 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.

Web module context roots must be unique within a server instance.

See the Sun Java System Application Server 9.1 High Availability Administration Guide for information about load balancing.

Deploying an EJB JAR Module

You deploy an EJB JAR module as described in Tools for Deployment.

If no JNDI name for the EJB JAR module is specified in the jndi-name element immediately under the ejb element in sun-ejb-jar.xml, or there is no sun-ejb-jar.xml file, a default, non-clashing JNDI name is derived. A warning message is logged recording the JNDI name used to look up the EJB JAR module.

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 9.1 Administration Reference.

Generation of stubs and ties is performed asynchronously, so unless you request their generation during deployment, stubs and ties are not guaranteed to be available immediately after deployment. To generate stubs and ties during deployment, use the --retrieve option of the asadmin deploy or asadmin deploydir command, or check the Generate RMIStubs Enabled box in the Admin Console.

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 9.1 Reference Manual.

Deploying a Lifecycle Module

For general information about lifecycle modules, see Chapter 13, Developing Lifecycle Listeners, in Sun Java System Application Server 9.1 Developer’s Guide.

You can deploy a lifecycle module using the following tools:

Note –

If the is-failure-fatal setting is set to true (the default is false), lifecycle module failure prevents server initialization or startup, but not shutdown or termination.

Deploying an Application Client

Deployment is necessary for application clients that communicate with EJB components or that use Java Web Start launch support.

Java Web Start is supported for application clients and for applications that contain application clients. It is enabled by default both in application clients and in the Application Server.

This section contains the following topics:

ProcedureTo Deploy an Application Client

  1. Assemble the necessary client files.

  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.

  5. If you are using the appclient script to run the application client, retrieve the client JAR file.

    The client JAR file contains the ties and necessary classes for the application client.

    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 9.1 Reference Manual.

  6. If you are using the appclient script to run the application client, copy the client JAR file to the client machine.

Next Steps

You can execute the client on the Application Server machine to test it in one of the following ways:

See Also

For more detailed information about Java Web Start, see Chapter 11, Developing Java Clients, in Sun Java System Application Server 9.1 Developer’s Guide.

For more detailed information about the appclient script, see the Sun Java System Application Server 9.1 Reference Manual.

ProcedureTo Prepare Another Machine for Executing an Application Client

If Java Web Start is enabled, the default URL for an application is as follows:


http://host:port/context-root

The default URL for a stand-alone application client module is as follows:


http://host:port/module-id

If the context-root or module-id is not specified during deployment, the name of the EAR or JAR file without the extension is used. For an application, the relative path to the application client JAR file is also included. If the application or module is not in EAR or JAR file format, a context-root or module-id is generated.

Regardless of how the context-root or module-id is determined, it is written to the server log. For details about naming, see Naming Standards.

To set a different URL for an application client, use the context-root subelement of the java-web-start-access element in the sun-application-client.xml file.

If Java Web Start is not enabled for the application client, follow these steps.

  1. You can use the package-appclient script in the as-install/bin directory to create the ACC package JAR file. This is optional.

    This JAR file is created in the as-install/lib/appclient directory.

  2. Copy the ACC package JAR file to the client machine and unjar it.

  3. Configure the sun-acc.xml file.

    This file is 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.

    This file is 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.

See Also

For more detailed information about Java Web Start and the package-appclient script, see Chapter 11, Developing Java Clients, in Sun Java System Application Server 9.1 Developer’s Guide.

Undeployment of Application Clients

Once application clients are downloaded, they remain on the client until removed manually. The Java Web Start control panel provides a simple interface you can use to discard downloaded application clients that used Java Web Start. When you undeploy an application client, you can no longer use Java Web Start, or any other mechanism, to download the application client. If you try to launch an application client that was previously downloaded even though the server side of the application client is no longer present, the results depend on whether the application client has been written to tolerate such situations.

You can write your application client to detect failures in contacting server-side components and to continue running anyway. In this case, Java Web Start can run an undeployed application client as it is cached locally. For example, your application client can be written to catch and recover from a javax.naming.NamingException in locating a resource or a java.rmi.RemoteException in referring to a previously-located resource that becomes inaccessible.

Deploying a J2EE CA Connector Module

You deploy a J2EE Connector Architecture (CA) connector module as described in Tools for Deployment. After deploying the module, you must configure it as described in Chapter 12, Developing Connectors, in Sun Java System Application Server 9.1 Developer’s Guide.

Access to Shared Frameworks

When Java EE 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, the Common Classloader, or an application-specific class loader 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 Chapter 2, Class Loaders, in Sun Java System Application Server 9.1 Developer’s Guide.