|
| Sun ONE Application Server 7, Update 1 Administrator's Guide |
Deploying ApplicationsThis module describes how to deploy various Sun ONE Application Server modules and applications.
Sun ONE Application Server modules and applications include J2EE standard elements and Sun ONE Application Server specific elements. Only Sun ONE Application Server specific elements are described in detail in this module.
To know about packaging and assembling modules and applications for deployment, see the Sun ONE Application Server Developer's Guide.
This module includes the following topics:
- About J2EE Modules
- About J2EE Applications
- J2EE Standard Descriptors
- Sun ONE Application Server Descriptors
- Naming Standards
- Deployment Directory Structure
- Runtime Environments
- About Classloaders
- Deploying Modules and Applications
- The Application Deployment Descriptor Files
About J2EE Modules
A J2EE module is a collection of one or more J2EE components of the same container type with deployment descriptors of that type. One descriptor is J2EE standard, the other is Sun ONE Application Server specific. Types of J2EE modules are as follows:
- Web Application Archive (WAR): A web application is a collection of servlets, HTML pages, classes, and other resources that can be bundled and deployed to several J2EE application servers. A WAR file can consist of the following items: servlets, JSPs, JSP tag libraries, utility classes, static pages, client-side applets, beans, bean classes, and deployment descriptors (web.xml and optionally sun-web.xml).
- EJB JAR File: The EJB JAR file is the standard format for assembling enterprise beans. This file contains the bean classes (home, remote, local, and implementation), all of the utility classes, and the deployment descriptors (ejb-jar.xml and optionally sun-ejb-jar.xml). If the EJB is an entity bean with container managed persistence, a CMP deployment descriptor, sun-cmp-mapping.xml, may be included as well.
- Application (RMI/IIOP) Client JAR File: An RMI/IIOP Client is a Sun ONE Application Server specific type of J2EE client. An RMI/IIOP Client supports the standard J2EE Application Client specifications, and in addition, supports direct access to the Sun ONE Application Server. Its deployment descriptors are application-client.xml and optionally sun-application-client.xml.
- Resource RAR File: RAR files apply to J2EE CA connectors. A connector module is like a device driver. It is a portable way of allowing EJBs to access a foreign enterprise system. Each Sun ONE Application Server connector has a J2EE XML file, ra.xml. A connector must also have a Sun ONE Application Server deployment descriptor, sun-ra.xml.
Package definitions must be used in the source code of all modules so the classloader can properly locate the classes after the modules have been deployed.
Because the information in a deployment descriptor is declarative, it can be changed without requiring modifications to source code. At run time, the J2EE server reads this information and acts accordingly.
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.
About J2EE 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.
Components are assembled into modules and then assembled into a Sun ONE Application Server application .ear file ready for deployment.
Each module has a Sun ONE Application Server deployment descriptor and a J2EE deployment descriptor. The Sun ONE Application Server Administration interface uses the deployment descriptors to deploy the application components and to register the resources with the Sun ONE Application Server.
An application consists of one or more modules, an optional Sun ONE 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 JAR files as the standard package for components and applications, and XML-based deployment descriptors for customizing parameters. For more information on the J2EE assembly and deployment process, see Developing Enterprise Applications with the J2EE, v 1.0, Chapter 7.
The J2EE standard deployment descriptors are described in the J2EE specification, v1.3.
To check the correctness of these deployment descriptors prior to deployment, see the information on the deployment descriptor verifier in the Sun ONE Application Server Developer's Guide.
The following table, "J2EE Standard Descriptors," shows where to find more information about J2EE standard deployment descriptors. The left column lists the deployment descriptors, and the right column lists where to find more information about those descriptors.
You can find specifications here:
Sun ONE Application Server Descriptors
Sun ONE Application Server uses additional deployment descriptors for configuring features specific to the Sun ONE Application Server. These are optional except for the sun-ra.xml file, which is required for a connector module.
To check the correctness of these deployment descriptors prior to deployment, see the information on the deployment descriptor verifier in the Sun ONE Application Server Developer's Guide.
The following table, "Sun ONE Application Server Descriptors," shows where to find more information about Sun ONE Application Server deployment descriptors. The left column lists the deployment descriptors, and the right column lists where to find more information about those descriptors.
Note The Sun ONE Application Server deployment descriptors must have 600 level access privileges on UNIX systems.
The DTD schema files for all the Sun ONE Application Server deployment descriptors are located in the install_dir/appserv/lib/dtds directory.
Naming Standards
Names of applications and individually deployed EJB JAR, WAR, and connector RAR modules (as specified by the name attributes in the server.xml file) must be unique in the Sun ONE Application Server. 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). For details about server.xml, see the Sun ONE Application Server Administrator's Configuration File Reference.
Modules of different types can have the same name within an application, because 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 ONE Application Server, but to other J2EE application servers as well.
JNDI lookup names for EJBs must also be unique. Here too, establishing a consistent naming convention may help. For example, appending the application name and the module name to the EJB name would be 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 your package and file names do not contain spaces or characters that are illegal for your operating system.
Deployment Directory Structure
When you deploy an application, 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 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
'--- sun-ra.xml
Runtime Environments
Whether you deploy a component as an individually deployed module or as an application, deployment affects both the file system and the server configuration. See the "Module Runtime Environment" and "Application Runtime Environment" figures.
Module Runtime Environment
The following figure,"Module Runtime Environment," illustrates the environment for individually deployed module-based deployment.
Module Runtime Environment
For file system entries, modules are extracted as follows:
instance_dir/applications/j2ee-modules/module_name
instance_dir/generated/ejb/j2ee-modules/module_name
instance_dir/generated/jsp/j2ee-modules/module_nameThe generated/ejb directory contains stubs and ties; the generated/jsp directory contains compiled JSPs.
Lifecycle modules are extracted as follows:
instance_dir/applications/lifecycle-modules/module_name
Configuration entries are added in server.xml as follows:
<server>
<applications>
<type-module>
...module configuration...
</type-module>
</applications>
</server>The type of the module in server.xml can be lifecycle, ejb, web, or connector. For details about server.xml, see the Sun ONE Application Server Administrator's Configuration File Reference.
Application Runtime Environment
The following figure, "Application Runtime Environment," illustrates the environment for application-based deployment.
Application Runtime Environment
For file system entries, applications are extracted as follows:
instance_dir/applications/j2ee-apps/app_name
instance_dir/generated/ejb/j2ee-apps/app_name
instance_dir/generated/jsp/j2ee-apps/app_nameThe generated/ejb directory contains stubs and ties; the generated/jsp directory contains compiled JSPs.
Configuration entries are added in server.xml as follows:
<server>
<applications>
<j2ee-application>
...application configuration...
</j2ee-application>
</applications>
</server>For details about server.xml, see the Sun ONE Application Server Administrator's Configuration File Reference.
Configuring server.xml To Use FastJavac Compiler
By default, Sun ONE Application Server uses the in built JDK compiler to compile applications during deployment. You can also use Sun One Studio's FastJavac compiler, which has a faster compilation rate, during deployment.
In the bundled Solaris install, the location of the FastJavac compiler is not transparent. In order to use the FastJavac compiler, you need to configure the administrative server's server.xml with the path for the compiler, as follows:
Add the following jvm-option in the java-config element, in server.xml:
<java-config java-home="/<install-dir>/jdk" server-classpath="....." >
jvm-options>-Dcom.sun.aas.deployment.java.compiler=/<install-dir>/studio4/bin/fastjavac/fastjavac.sun</jvm-options>
<property name="com.sun.aas.deployment.java.compiler.options"
value="-jdk /<install-dir>/jdk" />
</java-config>
About Classloaders
Understanding Sun ONE 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. For a more detailed discussion on Classloaders, see the Sun ONE Application Server Developer's Guide.
Deploying Modules and Applications
This section describes the different ways to deploy J2EE applications and modules to the Sun ONE Application Server. It covers the following topics:
- Deployment Names and Errors
- The Deployment Life Cycle
- Deployment of Module or Application
- Deploying a WAR Module
- Deploying an EJB JAR Module
- Deploying a Lifecycle Module
- Deploying an RMI/IIOP Client
- Deploying a J2EE CA Resource Adapter
- Deploying Static Content
- Access to Shared Frameworks
Deployment Names and Errors
A unique name is generated in the server.xml file when you deploy an application or module. Do not change this name. During deployment, the server detects any name collisions and does not load an application or module having a non-unique name. Messages are sent to the server log when this happens. For more about naming, see "Naming Standards".
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.
For details about server.xml, see the Sun ONE Application Server Administrator's Configuration File Reference.
The Deployment Life Cycle
After an application is initially deployed, it may be modified and reloaded, redeployed, disabled, reenabled, 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.
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. Each application and module has an enabled attribute in the server.xml file and a corresponding option in the Administration interface, which you can change. For details about server.xml, see the Sun ONE Application Server Administrator's Configuration File Reference.
Dynamic Reloading
If dynamic reloading is enabled, you do not have to redeploy an application or module when you change its code. All you have to do is copy the changed 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 is useful in a development environment, because it allows code changes to be tested quickly. Dynamic reloading is not recommended for a production environment, however, because it may 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, you can do one of the following:
- Use the Administration interface:
Open the Applications component under your server instance.
Check the Reload Enabled box to enable dynamic reloading.
Enter a number of seconds in the Reload Poll Interval field to set the interval at which applications and modules are checked for code changes and dynamically reloaded.
Go to the server instance page and select the Apply Changes button.
- Edit the following attributes of the server.xml file's applications element:
dynamic-reload-enabled="true" enables dynamic reloading.
dynamic-reload-poll-interval-in-seconds sets the interval at which applications and modules are checked for code changes and dynamically reloaded.
For details about server.xml, see the Sun ONE Application Server Administrator's Configuration File Reference.
In addition, to load new servlet files, reload EJB related changes, or reload deployment descriptor changes, you must do the following:
- Create an empty file named .reload at the root of the deployed application:
instance_dir/applications/j2ee-apps/app_name/.reload
or individually deployed module:
instance_dir/applications/j2ee-modules/module_name/.reload
- Explicitly update the .reload file's timestamp (touch .reload in UNIX) each time you make the above changes.
For JSPs, changes are reloaded automatically at a frequency set in the reload-interval property of the jsp-config element in the sun-web.xml file. To disable dynamic reloading of JSPs, set reload-interval="-1".
Tools for Deployment
This section discusses the various tools that can be used to deploy modules and applications. The deployment tools include:
The asadmin Utility
You can use the asadmin utility to deploy or undeploy applications and individually deployed modules on local servers. Concurrent deployment on multiple machines is not supported. This section describes the asadmin utility only briefly.
To deploy a lifecycle module, see "Deploying a Lifecycle Module".
asadmin deploy
The asadmin deploy command deploys a WAR, JAR, RAR, or EAR file. To deploy an application, specify --type application in the command. To deploy an individual module, specify --type ejb, web, connector. The syntax is as follows, with defaults shown for optional parameters that have them:
asadmin deploy --user admin_user [--password admin_password] [--host localhost] [-port 4848] [--secure | -s] [--virtualservers virtual_servers] [--type application|ejb|web|connector] [--contextroot contextroot] [--force=true] [--precompilejsp=false] [--name component_name] [--upload=true] [--retrieve local_dirpath] [--instance instance_name] filepath
For example, the following command deploys an individual EJB module:
asadmin deploy --user jadams --password secret --host localhost --port 4848 --type ejb --instance server1 packagingEJB.jar
asadmin deploydir
The asadmin deploydir command deploys an application or module in an open directory structure. The structure must be as specified in "Deployment Directory Structure". The location of the dirpath under instance_dir/applications/j2ee-apps or instance_dir/applications/j2ee-modules determines whether it is an application or individually deployed module. The syntax is as follows, with defaults shown for optional parameters that have them:
asadmin deploydir --user admin_user [--password admin_password] [--host localhost] [-port 4848] [--secure | -s] [--virtualservers virtual_servers] [--type application|ejb|web|connector] [--contextroot contextroot] [--force=true] [--precompilejsp=false] [--name component_name] [--instance instance_name] dirpath
For example, the following command deploys an individual EJB module:
asadmin deploydir --user jadams --password secret --host localhost --port 4848 --type ejb --instance server1 packagingEJB
asadmin undeploy
The asadmin undeploy command undeploys an application or module. To undeploy an application, specify --type app in the command. To undeploy a module, specify --type ejb, web, or connector. The syntax is as follows, with defaults shown for optional parameters that have them:
asadmin undeploy --user admin_user [--password admin_password] [--host localhost] [-port 4848] [--secure | -s] [--type application|ejb|web|connector] [--instance instance_name] component_name
For example, the following command undeploys an individual EJB module:
asadmin undeploy --user jadams --password secret --host localhost --port 4848 --type ejb --instance server1 packagingEJB
The Administration Interface
You can use the Administration interface to deploy modules and applications to both local and remote Sun ONE Application Server sites. To use this tool, follow these steps:
- Open the Applications component under your server instance.
- Go to the Enterprise Applications, Web Applications, Connector Modules, or EJB Modules page.
- Click on the Deploy button.
- Enter the full path to the module or application (or click on Browse to find it), then click on the OK button.
- Enter the module or application name.
You can also redeploy the module or application if it already exists by checking the appropriate box. This is optional.
- Assign the application or module to one or more virtual servers by checking the boxes next to the virtual server names.
- Click on the OK button.
To deploy a lifecycle module, see "Deploying a Lifecycle Module".
Sun ONE Studio
You can use Sun ONE Studio 4 to deploy J2EE applications and modules. For more information about using Sun ONE Studio, see the Sun ONE Studio 4, Enterprise Edition Tutorial.
Deployment of 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:
- Other modules
- J2EE Applications
- RMI/IIOP clients (Module-based deployment allows shared access to a bean from an RMI/IIOP client, a servlet, or an EJB.)
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 in one of the ways described in "Tools for Deployment".
You can keep the generated source for JSPs by adding the -keepgenerated property 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 instance_dir/generated/jsp/j2ee-apps/app_name/module_name if it is in an application or instance_dir/generated/jsp/j2ee-modules/module_name if it is in an individually deployed web module. For more information about the -keepgenerated property, see the Sun ONE Application Server Developer's Guide to Web Applications.
Deploying an EJB JAR Module
You deploy an EJB JAR module in one of the ways 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 server.xml. If you include this flag when you deploy the EJB JAR module, the generated source is kept in instance_dir/generated/ejb/j2ee-apps/app_name/module_name if it is in an application or instance_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 ONE Application Server Administrator's Configuration File Reference.
Deploying a Lifecycle Module
For general information about lifecycle modules, see the Sun ONE Application Server Developer's Guide.
You can deploy a lifecycle module using the following tools:
The asadmin Utility
To deploy a lifecycle module, use the asadmin create-lifecycle-module command. The syntax is as follows, with defaults shown for optional parameters that have them:
asadmin create-lifecycle-module --user admin_user [--password admin_password] [--host localhost] [-port 4848] [--secure | -s] [--instance instance_name] --classname classname [--classpath classpath] [--loadorder load_order_number] [--failurefatal=false] [--enabled=true] [--description text_description] [--property (name=value)[:name=value]*] modulename
For example:
asadmin create-lifecycle-module --user jadams --password secret --host localhost --port 4848 --instance server1 --classname RMIServer MyRMIServer
To undeploy a lifecycle module, use the asadmin delete-lifecycle-module command. The syntax is as follows, with defaults shown for optional parameters that have them:
asadmin delete-lifecycle-module --user admin_user [--password admin_password] [--host localhost] [-port 4848] [--secure | -s] [--instance instance_name] module_name
For example:
asadmin delete-lifecycle-module --user jadams --password secret --host localhost --port 4848 --instance server1 MyRMIServer
To list the lifecycle modules that are deployed on a server instance, use the asadmin list-lifecycle-modules command. The syntax is as follows, with defaults shown for optional parameters that have them:
asadmin list-lifecycle-modules --user admin_user [--password admin_password] [--host localhost] [-port 4848] instance_name
For example:
asadmin list-lifecycle-module --user jadams --password secret --host localhost --port 4848 server1
The Administration Interface
You can also use the Administration interface to deploy a lifecycle module. Follow these steps:
- Open the Applications component under your server instance.
- Go to the Life Cycle Modules page.
- Click on the Deploy button.
- Enter the following information:
Name (required) - The name of the life cycle module.
Class Name (required) - The fully qualified name of the life cycle module's class file.
Classpath (optional) - The classpath for the life cycle module. Specifies where the module is located. The default location is under the application root directory.
Load Order (optional) - Determines the order in which life cycle modules are loaded at startup. Modules with smaller integer values are loaded sooner. Values can range from 101 to the operating system's MAXINT. Values from 1 to 100 are reserved.
Failure Fatal (optional) - Determines whether the server is shut down if the life cycle module fails. The default is false.
Enable (optional) - Determines whether the life cycle module is enabled. The default is true.
- Click on the OK button.
Deploying an RMI/IIOP Client
Deployment is only necessary for clients that communicate with EJBs. Deploying an RMI/IIOP client is a three-step process:
- Deploy the EAR or EJB JAR to be accessed by the RMI/IIOP client.
- Assemble the necessary client files and deploy the client.
- After deployment, a client JAR file is created in the following location for an application:
instance_dir/applications/j2ee-apps/app_name/app_nameClient.jar
or in the following location for an individually deployed module:
instance_dir/applications/j2ee-modules/module_name/module_nameClient.jar
The client JAR contains the ties and necessary classes for the RMI/IIOP client. Copy this file to the client machine, and set the APPCPATH environment variable on the client to point to this JAR.
You are now ready to run the client. For more information, see the Sun ONE Application Server Developer's Guide to Clients.
Deploying a J2EE CA Resource Adapter
You deploy a connector module in one of the ways described in "Tools for Deployment".
Deploying Static Content
Static content (HTML, images, etc.) can be hosted both on the web server and on the Sun ONE Application Server. However, when a WAR is registered, the static content gets deployed on the application server. All of the samples shipped with Sun ONE Application Server host the static content on the application server.
For example, to access a static file index.html on the application server, use:
http://server:port/NASApp/<context_root/index.html
Access to Shared Frameworks
When J2EE applications and modules use shared framework classes (such as components 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 about the system classloader, see "About Classloaders".
The Application Deployment Descriptor Files
Sun ONE Application Server applications include two deployment descriptor files:
- A J2EE standard file (application.xml), described in the Java Servlet Specification, v2.3, Chapter 13, "Deployment Descriptors."
- An optional Sun ONE Application Server specific file (sun-application.xml), described in this section.
For more information on application deployment descriptor files, see the Sun ONE Application Server Developer's Guide.