Chapter 5 Deploying Applications

This chapter explains how to deploy (install) J2EE applications on the Application Server. This chapter contains following sections:

About Deployment

The Deployment Life Cycle

Types of J2EE Archive Files

Naming Conventions

The Deployment Life Cycle

After installing the Application Server and started a domain, you can deploy (install) J2EE applications and modules. During deployment, an application or module can go through the following stages:

Initial Deployment

Deploy (install) an application or module into a specific domain, standalone server instance, or cluster. If you deploy the application only to the domain, it exists in the domain's central repository, but no server instances or clusters reference it. Before deploying an application or module, start the domain. Because applications and modules are packaged in archive files, specify the archive file name during deployment.

If you deploy using the asadmin tool, the default is to deploy to the default server instance. If you deploy using the Admin Console, the default is to deploy to the domain.

Deployment is dynamic: you don't need to restart the server instance after you deploy an application. If you do restart, all deployed applications and modules are still deployed.

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.

Adding or Deleting Targets for a Deployed Application

Once deployed, the application or module exists in the central repository and can be referenced by a number of server instances and/or clusters. To change which server instances and clusters reference an application after the application is deployed, change an applications's targets. Because the application itself is stored in the central repository, the same version of the application is deployed to different server instances or clusters. However, an application deployed to more than one target can be enabled on one and disabled on another.

Redeployment

To replace a deployed application or module, redeploy it. You don't have to undeploy and then deploy it again.

You can add additional target server instances or clusters when you redeploy.

For more information about redeploying applications to multiple targets, see "Redeploying to Multiple Targets".

Undeployment

To uninstall an application or module, undeploy it.

Types of J2EE Archive Files

A software provider packages an application or module into a archive file. To deploy the application or module, specify the archive file name. The content and structure of the archive file is defined by the specifications of the J2EE platform. Types of J2EE archive files are as follows:

Web Application Archive (WAR): A WAR file consists of Web components such as servlets and JSPs, as well as static HTML pages, JAR files, tag libraries and utility classes. A WAR file name has the .war extension.

EJB JAR: The EJB JAR file contains one or more enterprise beans, the components used for EJB technology. The EJB JAR file also includes any utility classes needed by the enterprise beans. The name of an EJB JAR file has the .jar extension.

J2EE Application Client JAR: This JAR file contains the code for a J2EE application client, which accesses server-side components such as enterprise beans via RMI/IIOP. In the Admin Console, a J2EE application client is referred to as an "application client." The name of the J2EE application client JAR file has the .jar extension.

Resource Adapter Archive (RAR): A RAR file holds a resource adapter. Defined by the J2EE Connector Architecture specifications, a resource adapter is a portable component that enables enterprise beans, Web components, and application clients to access resources and foreign enterprise systems. A resource adapter is often referred to as a connector. A RAR file name has the .rar extension.

Enterprise Application Archive (EAR): An EAR file holds one or more WAR, EJB JAR, RAR or J2EE Application Client JAR files. An EAR file name has the .ear extension.

The software provider might assemble an application into a single EAR file or into separate WAR, EJB JAR, and application client JAR files. In the administration tools, the deployment pages and commands are similar for all types of files.

Naming Conventions

In a given domain, the names of deployed applications and modules must be unique.

If you deploy using the Admin Console, you specify the name in the Application Name field.

If you deploy using the asadmin deploy command, the default name of the application or module is the prefix of the JAR file that you deploy. For example, if you deploy the hello.war file, the Web application name is hello. To override the default name, specify the --name option.

Modules of different types can have the same name within an application. When the application is deployed, the directories holding the individual modules are named with _jar, _war and _rar suffixes. Modules of the same type within an application must have unique names. In addition, database schema file names must be unique within an application.

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 Sun Java System Application Server, but to other J2EE application servers as well.

JNDI lookup names for EJBs 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.

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

Admin Console Tasks for Deploying Applications

Deploying an Enterprise Application

Deploying a Web Application

Deploying an EJB Module

Deploying an Application Client Module

Deploying a Connector Module

Creating a Lifecycle Module

Deploying an Application Client Module

Deploying an Enterprise Application

An enterprise application is packaged in an EAR file, a type of archive file that contains any type of J2EE standalone modules, such as WAR and EJB JAR files.

In the tree component, expand the Applications node.

Select the Enterprise Applications node.

On the Enterprise Applications page, click Deploy.

On the Deployment page, specify the EAR file to deploy.

The server machine is the host that is running the application server domain administration server. The client machine is the host on which you are viewing the Admin Console through a browser. If a file or directory is said to reside on a server or client machine, it might really live on another host, but the file or directory must be accessible from the file system of the server or client machine.

For the Upload File button, if the file resides on the client machine, select Yes. If the file resides on the server machine, then select No.

To deploy an unpackaged application from an exploded directory, select No. The exploded directory must reside on the server machine. Deploying from an exploded directory is for advanced developers and is not recommended for production environments.

In the File Or Directory field, to deploy a file click Browse and locate the file (or type the full path name of the file). To deploy from an exploded directory, type the full path name of the directory.

Click Next to display the Deploy Enterprise Application page.

On the Deploy Enterprise Application page, specify the settings for the application.

In the Application Name field, either retain the default name, which is the prefix of the file name, or type another name. The application name must be unique.

By default, an application is available as soon as it is deployed. To disable the application so that is unavailable after deployment, deselect the Enabled checkbox.

If the application has already been deployed, it is replaced with the new application unless you deselect the Redeploy checkbox.

If you deployed an application or module to multiple clusters or server instances, you must redeploy it to all clusters or instances that share it. Otherwise, you see an error.

To verify the structure and contents of the file before deployment, select the Verifier checkbox. Verification of large applications can be time-consuming. Verify the file if you suspect it is corrupt or non-portable.

To precompile JSP pages, select the JSPs checkbox. If you do not select this checkbox, the JSP pages are compiled at runtime when they are first accessed. Because compilation is often time-consuming, in a production environment select this checkbox.

Choose a high availability setting.

To enable high availability for the application, select the Availability checkbox. If availability is enabled for an application, it must also be enabled at all higher levels (named configuration and web container or EJB container) as well.

Choose the targets to which to deploy the application.

From the list of available targets, choose the target or targets and click Add. Targets can be clusters or standalone server instances. If you do not select an item from the drop-down list, the application is deployed to the domain, and is not associated with any target instance or cluster.

Note that this behavior is different than the behavior when you use the asadmin tool. In that case, an unspecified target deploys the application to the default server instance server.

Choose whether to generate RMI stubs.

If you choose to generate RMI stubs, static RMI-IIOP stubs are generated and put into the client.jar.

Click OK to deploy the application.

Deploying a Web Application

A Web application is packaged in a WAR file, a type of archive file that contains components such as servlets and JSP pages.

In the tree component, expand the Applications node.

Select the Web Applications node.

On the Web Applications page, click Deploy.

On the Deployment page, specify the WAR file to deploy.

For the Upload File button, if the file resides on the client machine, select Yes. If the file resides on the server machine, select No.

Click Next to display the Deploy Web Application page.

On the Deploy Web Application page, specify the settings for the application.

In the Application Name field, either retain the default name, which is the prefix of the file name, or type another name. (The default name appears if you select Yes for the Upload File button.) The application name must be unique.

In the Context Root field, enter a string that identifies the Web application. In the URL of the Web application, the context root immediately follows the port number (http://host:port/context-root/...). Make sure that the context root starts with a forward slash, for example: /hello

By default, an application is available as soon as it is deployed. To disable the application so that is unavailable after deployment, deselect the Enabled checkbox.

If the application has already been deployed, it will be replaced with the new application unless you deselect the Redeploy checkbox.

If you deployed an application or module to multiple clusters or server instances, you must redeploy it to all clusters or instances that share it. Otherwise, you see an error.

To verify the structure and contents of the file before deployment, select the Verifier checkbox. Verification of large applications is often time-consuming. Verify the file if you suspect it is corrupt or non-portable.

Choose a high availability setting.

Choose the targets to which to deploy the application.

Note that this behavior is different than the behavior when you use the asadmin tool. In that case, an unspecified target deploys the application to the default server instance server.

Choose whether to generate RMI stubs.

If you choose to generate RMI stubs, static RMI-IIOP stubs are generated and put into the client.jar.

Click OK to deploy the application.

Deploying an EJB Module

In the tree component, expand the Applications node.

Select the EJB Modules node.

On the EJB Module page, click Deploy.

On the Deployment page, specify the JAR file to deploy.

For the Upload File button, if the file resides on the client machine, select Yes. If the file resides on the server machine, select No.

Click Next to display the Deploy EJB Module page.

On the Deploy EJB Module page, specify the settings for the application.

In the Application Name field, either retain the default name, which is the prefix of the file name, or type another name. The application name must be unique.

By default, an application is available as soon as it is deployed. To disable the application so that is unavailable after deployment, deselect the Enabled checkbox.

If the application has already been deployed, it will be replaced with the new application unless you deselect the Redeploy checkbox.

If you deployed an application or module to multiple clusters or server instances, you must redeploy it to all clusters or instances that share it. Otherwise, you see an error.

Choose a high availability setting.

Choose the targets to which to deploy the application.

Note that this behavior is different than the behavior when you use the asadmin tool. In that case, an unspecified target deploys the application to the default server instance server.

Choose whether to generate RMI stubs.

If you choose to generate RMI stubs, static RMI-IIOP stubs are generated and put into the client.jar.

Click OK to deploy the module.

Deploying a Connector Module

A connector, also known as a resource adapter, is packaged in a type of archive file called a RAR file.

In the tree component, expand the Applications node.

Select the Connector Modules node.

On the Connector Modules page, click Deploy.

On the Deployment page, specify the RAR file to deploy.

For the Upload File button, if the file resides on the client machine, then select Yes. If the file resides on the server machine, then select No.

Click Next to display the Deploy Connector Module page.

On the Deploy Connector Module page, specify the settings for the application.

In the Application Name field, either retain the default name, which is the prefix of the file name, or type another name. The application name must be unique.

By default, an application is available as soon as it is deployed. If you want to disable the application so that it is unavailable after deployment, deselect the Enabled checkbox.

When you enable or disable a connector module, you also enable or disable the connector resources and connection pools that point to the module.

If the application has already been deployed, it will be replaced with the new application unless you deselect the Redeploy checkbox.

If you deployed an application or module to multiple clusters or server instances, you must redeploy it to all clusters or instances that share it. Otherwise, you see an error.

If the resource adapter has additional properties specified, they are displayed.

Use the table to modify the default values of these properties.

Choose the targets to which to deploy the module.

From the list of available targets, choose a target or targets and click Add. Targets can be clusters or standalone server instances. If you do not select an item from the drop-down list, the application is deployed to the domain, and is not associated with any target instance or cluster.

Note that this behavior is different than the behavior when you use the asadmin tool. In that case, an unspecified target deploys the application to the default server instance server.

Click OK to deploy the module.

Creating a Lifecycle Module

A lifecycle module performs tasks when it is triggered by one or more events in the server lifecycle. These server events are:

initialization

start up

ready to service requests

shut down

Lifecycle modules are not part of the J2EE specification, but are an enhancement to the Sun Java System Application Server.

In the tree component, expand the Applications node.

Select the Lifecycle Modules node.

On the Lifecycle Modules page, click New.

On the Create Lifecycle Module page, specify the settings:

In the Name field, type a name that denotes the function of the module.

In the Class Name field, type the fully qualified name of the lifecycle module's class file.

If the JAR file containing the lifecycle is in the server's classpath, then leave the Classpath field blank. Otherwise, type the fully qualified path.

If you don't specify the classpath, you must unpack the classes in application_server_home/domains/domain/applications/lifecycle-module/module_name. If you specify a classpath, nothing else is required.

In the Load Order field, type an integer greater than 100 and less than the operating system's MAXINT value.

The integer determines the order in which lifecycle modules are loaded when the server starts up. Modules with smaller integers are loaded sooner.

When you start the server, it loads lifecycle modules that are already deployed. By default, if a load fails, the server continues the start-up operation. To prevent the server from starting up when a load fails, select the On Load Failure checkbox.

By default, a module is available as soon as it is deployed. To disable the module so that is unavailable after deployment, deselect the Enabled checkbox.

Click OK.

Deploying an Application Client Module

An application client module, also called a J2EE application client JAR file, contains the server-side routines for the client.

In the tree component, expand the Applications node.

Select the App Client Modules node.

On the Application Client Modules page, click Deploy.

On the Deployment page, specify the JAR file to deploy.

For the Upload File button, if the file resides on the client machine, select Yes. If the file resides on the server machine, select No.

Click Next to display the Deploy Application Client Module page.

On the Deploy Application Client Module page, specify the settings for the application.

In the Application Name field, either retain the default name, which is the prefix of the file name, or type another name. The application name must be unique.

If the application has already been deployed, it will be replaced with the new application unless you deselect the Redeploy checkbox.

If you deployed an application or module to multiple clusters or server instances, you must redeploy it to all clusters or instances that share it. Otherwise, you see an error.

To verify the structure and contents of the file before deployment, select the Verifier checkbox. Verification of large applications can be time-consuming.Verify the file if you suspect it is corrupt or non-portable.

Choose the targets to which to deploy the module.

Note that this behavior is different than the behavior when you use the asadmin tool. In that case, an unspecified target deploys the application to the default server instance server.

Choose whether to generate RMI stubs.

If you choose to generate RMI stubs, static RMI-IIOP stubs are generated and put into the client.jar.

Click OK to deploy the module.

Typically, the application provider ships a JAR file containing the client-side routines.

The application provider gets the client-side stubs by specifying the --retrieve option of the asadmin deploy command.

Admin Console Tasks for Listing, Undeploying, and Enabling Applications

Listing Deployed Applications

Listing Subcomponents

Viewing Module Descriptors of Deployed Applications or Modules

Undeploying an Application

Enabling and Disabling an Application

Enabling and Disabling Dynamic Reloading

Listing Deployed Applications

In the tree component, expand the Applications node.

Expand the node for the application or module type.

In the tree component, select the node of the application or module.

On the page, select an entry in the Application Name column.

Listing Subcomponents

Enterprise and Web applications and Connector Modules contain subcomponents. For example, a Web application might contain one or more servlets. Use the same method for listing the subcomponents of Enterprise and Web applications and Connector Modules.

In the tree component, expand the Applications node.

Expand the Web Applications node.

Select the node for a particular Web application.

On the Web Application page, note the contents of the Sub Components table.

Viewing Module Descriptors of Deployed Applications or Modules

For Enterprise Applications, Web Applications, EBJ Modules, Connector Modules, and App Client Modules, you can view the module deployment descriptors.

In the tree component, expand the Applications node.

Select the node for the type of application or module for which you want to view descriptors.

Select the node for the deployed application.

Select the Descriptor tab.

To see the text of the descriptor file, click the file name.

The page displays the file contents. This information is read-only.

Undeploying an Application

In the tree component, expand the Applications node.

Select the node for the type of application or module want to undeploy.

In the table listing the deployed applications, select the checkbox for the application you want to undeploy.

Click Undeploy.

Enabling and Disabling an Application

If a deployed application or module is enabled, it is accessible by clients. If it is disabled, it is still deployed but is not accessible by clients. By default, when you deploy an application or module, it is enabled because the Status checkbox on the Deploy page is selected.

In the tree component, expand the Applications node.

Expand the node for the application type.

Select the node for the deployed application or module.

Select the Status checkbox.

Managing Application Targets

After deploying an application or module, manage the server instances and clusters that reference it by managing targets.

In the tree component, expand the Applications node.

Expand the node for the application type.

Select the node for the deployed application.

Select the Targets tab.

To enable or disable an application on a specific target instance or cluster, click the checkbox next to the target and choose enable or disable from the drop-down menu.

To add or delete targets for the application, chose Manage Targets.

Add or remove targets and click OK.

The application is now available on the revised list of targets.

Equivalent asadmin commands: create-application-ref, delete-application-ref.

Deploying on Additional Virtual Servers

After deploying an application or module to a target server instance or cluster of instances, you can associate it with additional virtual servers.

From the deployed application or module's Target page, click the Manage Virtual Servers link next to the target.

Add or remove virtual server targets from the list of available virtual servers.

Click OK.

Redeploying to Multiple Targets

If an application is deployed to multiple targets (standalone server instances or clusters), you cannot redeploy to multiple targets. Use the following method to make sure all server instances that reference an application receive the most recent version.

Delete the application references for all but one target.

Redeploy the application to the target that still references it.

Create application references for the additional targets until all servers that originally referenced the application do so again.

Users experience no loss of service because the servers are never shut down and restarted.

Enabling and Disabling Dynamic Reloading

If dynamic reloading is enabled, the server periodically checks for changes in the files of the deployed application and automatically reloads the application with the changes. Dynamic reloading is useful in a development environment because it allows code changes to be tested quickly. In a production environment, however, dynamic reloading may degrade performance.

Dynamic reloading is intended for development environments. It is incompatible with session persistence, a production environment feature. Do not enable session persistence if dynamic deployment is enabled.


Note	Dynamic reloading is only available for the default server instance.

In the tree component, expand the relevant configuration node.

Select Deployment Settings.

On the Applications Configuration page, configure the following:

Reload: Enable or disable dynamic reloading with the Enabled checkbox.

Reload Poll Interval: Specify how often the server checks for changes in the deployed applications.

Admin Session Timeout: Specify the amount of time before the Admin Session times out and you have to log in again.

XML Validation:

full: If XML validation fails, deployment fails.

parsing: XML validation errors are reported but deployment occurs.

none: No XML validation is performed.

Deployment Methods for Developers

Using Auto Deploy

Deploying an Unpackaged Application From a Directory

Using the deploytool Utility

Using a Deployment Plan

Using Auto Deploy

The auto deploy feature enables you to deploy a pre-packaged application or module by copying it to the install_dir/domains/domain_dir/autodeploy directory.

For example, copy a file named hello.war to the install_dir/domains/domain1/autodeploy directory. To undeploy the application, remove the hello.war file from the autodeploy directory.

The auto deploy feature is intended for development environments. It is incompatible with session persistence, a production environment feature. Do not enable session persistence if dynamic deployment is enabled


Note	Auto deploy is only available for the default server instance.

In the tree component, expand the configuration node for which to change the auto deploy settings.

Select Deployment Settings.

On the Applications Configuration page, configure the following:

Enable or disable auto deploy by selecting or deselecting the Enabled checkbox.

In the Auto Deploy Poll Interval field, specify how often the server checks the auto deploy directory for application or module files. Changing the poll interval will not affect the amount of time it takes to deploy an application or module.

In the Auto Deploy Directory, if you specify the directory where you build your application, then you won't have to copy the file to the default auto deploy directory.

The default is a directory called autodeploy in the server instance's root directory. By default a variable is used to eliminate the need to manually change the directory for multiple server instances.

To run the verifier before deployment, select the Verifier Enabled checkbox. The verifier examines the structure and content of the file. Verification of large applications is often time-consuming.

Deploying an Unpackaged Application From a Directory

Use directory deployment only to deploy to the default server instance (server). You cannot use it to deploy to clusters or standalone server instances.

A directory containing an unpackaged application or module is sometimes called an exploded directory. The contents of the directory must match the contents of a corresponding J2EE 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. For information about the required directory contents, see the appropriate specifications.

You can change the deployment descriptor files directly in the exploded directory. If dynamic reloading is enabled, the server automatically detects the changes and reloads the application. See "Enabling and Disabling Dynamic Reloading".

In the Admin Console, begin the deployment process. See "Deploying a Web Application".

On the Deployment page, specify the following:

Under Upload File, select No.

Using the deploytool Utility

Designed for software developers, the deploytool utility packages and deploys J2EE applications and modules. For instructions on how to use deploytool, see The J2EE 1.4 Tutorial.

Using a Deployment Plan

A deployment plan is an JAR file that contains only the deployment descriptors that are specific to the Application Server. These deployment descriptors, for example sun-application.xml, are described in the Application Server Developer's Guide. The deployment plan is part of the implementation of JSR 88: J2EE Application Deployment. Use a deployment plan to deploy an application or module that does not contain the deployment descriptors that are specific to the Application Server.

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 myrosterapp.ear file according to the plan specified by the mydeployplan.jar file.

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

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.

Previous Contents Index Next
Sun Java System Application Server Enterprise Edition 8 2004Q4 Beta Administration Guide