Assembling and Deploying J2EE Applications

This chapter describes Sun ONE Application Server modules and how these modules are assembled separately or together in an application. For design considerations that affect assembly, see "Modularizing 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 chapter.

Overview of Assembly and Deployment

Application assembly (also known as packaging) is the process of combining discrete components of an application into a single unit that can be deployed to a J2EE-compliant application server. A package can be classified either as a module or as a full-fledged application. This section covers the following topics:

Modules

A J2EE module is a collection of one or more J2EE components of the same container type (for example, web or EJB) with deployment descriptors of that type. One descriptor is J2EE standard, the other is Sun 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 sun-ejb-jar.xml). If the EJB component is an entity bean with container managed persistence, a .dbschema file and a CMP mapping descriptor, sun-cmp-mapping.xml, must be included as well.

Application Client Container JAR File: An ACC client is a Sun ONE Application Server specific type of J2EE client. An ACC client supports the standard J2EE Application Client specifications, and in addition, supports direct access to the Sun ONE Application Server. Its deployment descriptors are application-client.xml and sun-application-client.xml.

Resource RAR File: RAR files apply to J2EE CA connectors. A connector module is like a device driver. It is a portable way of allowing EJB components to access a foreign enterprise system. Each Sun 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.

Applications

A J2EE application is a logical collection of one or more J2EE modules tied together by application deployment descriptors. Components can be assembled at either the module or the application level. Components can also be deployed at either the module or the application level.

The following diagram illustrates how components are assembled into modules and then assembled into a Sun 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 WAR, JAR, and EAR files as standard packages for components and applications, and XML-based deployment descriptors for customizing parameters.

J2EE standard deployment descriptors are described in the J2EE specification, v1.3. You can find the specification here:

The following table 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.

Table 4-1 J2EE Standard Descriptors
Deployment Descriptor	Where to Find More Information
application.xml	Java 2 Platform Enterprise Edition Specification, v1.3, Chapter 8, “Application Assembly and Deployment - J2EE:application XML DTD”
web.xml	Java Servlet Specification, v2.3 Chapter 13, “Deployment Descriptor,” and JavaServer Pages Specification, v1.2, Chapter 7, “JSP Pages as XML Documents,” and Chapter 5, “Tag Extensions”
ejb-jar.xml	Enterprise JavaBeans Specification, v2.0, Chapter 16, “Deployment Descriptor”
application-client.xml	Java 2 Platform Enterprise Edition Specification, v1.3, Chapter 9, “Application Clients - J2EE:application-client XML DTD”
ra.xml	Java 2 Enterprise Edition, J2EE Connector Architecture Specification, v1.0, Chapter 10, “Packaging and Deployment.”

Sun ONE Application Server Descriptors

Sun ONE Application Server uses additional deployment descriptors for configuring features specific to the Sun ONE Application Server. The sun-application.xml and sun-web.xml files are optional; all the others are required.

The DTD schema files for all the Sun ONE Application Server deployment descriptors are located in the install_dir/lib/dtds directory.

The following table 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.

Table 4-2 Sun ONE Application Server Descriptors
Deployment Descriptor	Where to Find More Information
sun-application.xml	"The Application Deployment Descriptor Files".
sun-web.xml	Sun ONE Application Server Developer’s Guide to Web Applications
sun-ejb-jar.xml and sun-cmp-mapping.xml	Sun ONE Application Server Developer’s Guide to Enterprise JavaBeans Technology
sun-application-client.xml and sun-acc.xml	Sun ONE Application Server Developer’s Guide to Clients
sun-ra.xml	Sun ONE J2EE CA Service Provider Implementation Administrator’s Guide

Naming Standards


Note	The Sun ONE Application Server deployment descriptors must have 600 level access privileges on UNIX systems.

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 a Sun ONE Application Server instance. 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, for entity beans that use CMP,.dbschema file names must be unique within an application.

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

JNDI Naming

When clients or web applications communicate with EJB components, or when web applications or EJB components require services provided by JDBC or other resources, a naming service is what allows these components to locate and talk to each other. A naming service maintains a set of bindings, which relate names to objects. The J2EE naming service is JNDI (the Java Naming and Directory Interface).

In Sun ONE Application Server, containers provide their components a naming environment, or context, which allows components to look up other distributed components and resources. A Context object provides the methods for binding names to objects, unbinding names from objects, renaming objects, and listing the bindings.

JNDI also provides subcontext functionality. Much like a directory in a file system, a subcontext is a context within a context. This hierarchical structure permits better organization of information. For naming services that support subcontexts, the Context class also provides methods for creating and destroying subcontexts.

JNDI names for EJB components must be unique. 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.

The following table describes JNDI subcontexts for connection factories in Sun ONE Application Server. The left column lists Resource Manager types, the middle column lists Connection Factory types, and the right column lists JNDI subcontexts.


Note	To avoid collisions with names of other enterprise resources in JNDI, and to avoid portability problems, all names in a Sun ONE Application Server application should begin with the string java:comp/env.

Table 4-3 JNDI subcontexts for connection factories
Resource Manager Type	Connection Factory Types	JNDI Subcontext
JDBC	javax.sql.DataSource	java:comp/env/jdbc
JMS	javax.jms.TopicConnectionFactory javax.jms.QueueConnectionFactory	java:comp/env/jms
JavaMail	javax.mail.Session	java:comp/env/mail
URL	java.net.URL	java:comp/env/url
Connector	javax.resource.cci.ConnectionFactory	java:comp/env/eis

Directory Structure

When you deploy an application, the application is expanded to an open directory structure, and the directories holding the individual modules are named with _jar, _war and _rar suffixes. If you use the asadmin deploydir command to deploy a directory instead of an EAR file, your directory structure must follow this same convention.

Module and application directory structures follow the structure outlined in the J2EE specification. Here is an example directory structure of a simple application containing a web module, an EJB module, and a client module.

+ converter_1/

|--- converterClient.jar

|--+ META-INF/

| |--- MANIFEST.MF

| |--- application.xml

| '--- sun-application.xml

|--+ war-ic_war/

| |--- index.jsp

| |--+ META-INF/

| | |--- MANIFEST.MF

| '--+ WEB-INF/

| |--- web.xml

| '--- sun-web.xml

|--+ ejb-jar-ic_jar/

| |--- Converter.class

| |--- ConverterBean.class

| |--- ConverterHome.class

| '--+ META-INF/

| |--- MANIFEST.MF

| |--- ejb-jar.xml

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

'--+ app-client-ic_jar/

|--- ConverterClient.class

'--+ META-INF/

|--- MANIFEST.MF

|--- application-client.xml

'--- sun-application-client.xml

Here is an example directory structure of an individually deployed connector module.

Runtime Environments

Module Runtime Environment

The following figure illustrates the environment for individually deployed module-based deployment.

instance_dir/applications/j2ee-modules/module_name
instance_dir/generated/ejb/j2ee-modules/module_name
instance_dir/generated/jsp/j2ee-modules/module_name

The applications directory contains the directory structures described in "Directory Structure". The generated/ejb directory contains the stubs and ties that an ACC client needs to access the module; the generated/jsp directory contains compiled JSPs.

<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 illustrates the environment for application-based deployment.

instance_dir/applications/j2ee-apps/app_name
instance_dir/generated/ejb/j2ee-apps/app_name
instance_dir/generated/jsp/j2ee-apps/app_name

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

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. This section includes the following topics:

The Classloader Hierarchy

Classloaders in the Sun ONE Application Server runtime follow a hierarchy that is illustrated here:

Note that this is not a Java inheritance hierarchy, but a delegation hierarchy. In the delegation design, a classloader delegates classloading to its parent before attempting to load a class itself. A classloader parent can be either the System Classloader or another custom classloader. If the parent classloader can’t load a class, the findClass() method is called on the classloader subclass. In effect, a classloader is responsible for loading only the classes not available to the parent.

The exception is the Web Classloader, which follows the delegation model in the Servlet specification. The Web Classloader looks in the local classloader before delegating to its parent. You can make the Web Classloader delegate to its parent first by setting delegate="true" in the class-loader element of the sun-web.xml file. For details, see the Developer’s Guide to Web Applications.

The following table describes Sun ONE Application Server classloaders. The left column lists the classloaders, and the right column lists descriptions of those classloaders and the files they examine.


Note	The Web Classloader for a web component of a web service must delegate to its parent classloader, so you must set delegate="true" in the class-loader element of the sun-web.xml file in this case.

Table 4-4 Sun ONE Application Server classloaders
Classloader	Description
Bootstrap	The Bootstrap Classloader loads all the JDK classes.
System	The System Classloader loads most of the core Sun ONE Application Server classes. It is created based on the classpath-prefix, server-classpath, and classpath-suffix attributes of the java-config element in the server.xml file. The environment classpath is included if env-classpath-ignored="false" is set in the java-config element.
Common	The Common Classloader loads classes in the instance_dir/lib/classes directory, followed by JAR and ZIP files in the instance_dir/lib directory. No special classpath settings are required. The existence of these directories is optional; if they don’t exist, the Common Classloader is not created.
Shared	The Shared Classloader is a single instance that loads classes (such as individually deployed connector modules) that are shared across all applications.
LifeCycleModule	The LifeCycleModule Classloader is the parent classloader for lifecycle modules. Each lifecycle module’s classpath is used to construct its own classloader.
EJB	The EJB Classloader loads the enabled EJB classes in a specific enabled EJB module or J2EE application. One instance of this classloader is present in each classloader universe. The EJB Classloader is created with a list of URLs that point to the locations of the classes it needs to load.
Web	The Web Classloader loads the servlets and other classes in a specific enabled web module or J2EE application. One instance of this classloader is present in each classloader universe. The Web Classloader is created with a list of URLs that point to the locations of the classes it needs to load.
JSP Engine	The JSP Engine Classloader loads compiled JSP classes of enabled JSPs. One instance of this classloader is present in each classloader universe. The JSP Engine Classloader is created with a list of URLs that point to the locations of the classes it needs to load.

Classloader Universes

Access to components within applications and modules installed on the server occurs within the context of isolated classloader universes, each of which has its own EJB, Web, and JSP Engine classloaders.

Application Universe: Each J2EE application has its own classloader universe, which loads the classes in all the modules in the application.

Individually Deployed Module Universe: Each individually deployed EJB JAR, web WAR, or lifecycle module has its own classloader universe, which loads the classes in the module.



Note	In iPlanet Application Server 6.x, individually deployed modules shared the same classloader. In Sun ONE Application Server 7, each individually deployed module has its own classloader universe.



Note	A resource such as a file that is accessed by a servlet, JSP, or EJB component must be in a directory pointed to by the classloader’s classpath. For example, the web classloader’s classpath includes these directories: module_name/WEB-INF/classes module_name/WEB-INF/lib If a servlet accesses a resource, it must be in one of these directories or it will not be loaded.

Circumventing Classloader Isolation

Since each application or individually deployed module classloader universe is isolated, an application or module cannot load classes from another application or module. This prevents two similarly named classes in different applications from interfering with each other.

To circumvent this limitation for libraries, utility classes, or individually deployed modules accessed by more than one application, you can include the relevant path to the required classes in one of these ways:

Using the System Classloader

To use the System Classloader, do one of the following, then restart the server:

Using the System Classloader makes an application or module accessible to any other application or module across the server instance.

Using the Common Classloader

To use the Common Classloader, copy the JAR and ZIP files into the instance_dir/lib directory or copy the .class files into the instance_dir/lib/classes directory, then restart the server.

Using the Common Classloader makes an application or module accessible to any other application or module across the server instance.

Packaging the Client JAR for One Application in Another Application

By packaging the client JAR for one application in a second application, you allow an EJB or web component in the second application to call an EJB component in the first (dependent) application, without making either of them accessible to any other application or module.

Packaging the client JAR for one application in another application has trade-offs. After you enable the -nolocalstubs option, you can deploy multiple applications that contain client JARs of other applications without restarting the server. However, using the -nolocalstubs option may degrade server performance.

As an alternative, you can have the Common Classloader load client JAR of the dependent application as described in "Using the Common Classloader". Server performance is better, but you must restart the server to make the dependent application accessible, and it is accessible across the server instance. This approach is recommended for a production environment.

Add the -nolocalstubs option to the server instance’s rmic options in one of these ways, then restart the server:

Go to the server instance page in the Administration interface, select the JVM Settings tab, select the General option, add -nolocalstubs to the rmic Options field, and select Save.

Add -nolocalstubs to the rmic-options attribute of the java-config element in server.xml. For details about server.xml, see the Sun ONE Application Server Administrator’s Configuration File Reference.

After you make this change, all subsequently deployed EJB components can only be accessed remotely.



Note	Using the -nolocalstubs option may degrade server performance.

Deploy the dependent application.

Add the dependent application’s client JAR file to the calling application.

For a calling EJB component, add the client JAR file at the same level as the EJB component. Then add a Class-Path entry to the MANIFEST.MF file of the calling EJB component. The Class-Path entry has this syntax:

Class-Path: filepath1.jar filepath2.jar ...

Each filepath is relative to the directory or JAR file containing the MANIFEST.MF file. For details, see the J2EE specification, section 8.1.1.2, “Dependencies.”

For a calling web component, add the client JAR file under the WEB-INF/lib directory.

For most applications, packaging the client JAR file with the calling EJB component should suffice. You do not need to package the client JAR file with both the EJB and web components unless the web component is directly calling the EJB component in the dependent application. If you need to package the client JAR with both the EJB and web components, set delegate="true" in the class-loader element of the sun-web.xml file. This changes the Web Classloader so it follows the standard classloader delegation model and delegates to its parent before attempting to load a class itself.

Deploy the calling application.



Note	The calling EJB or web component must use the JNDI name of the EJB component in the dependent application. Using an ejb-ref mapping won’t work.

Sample Applications

Sample applications that you can examine and deploy are included in Sun ONE Application Server, in the install_dir/samples directory. The samples are organized in categories such as ejb, jdbc, connectors, i18n, and so on. Each sample category is further divided into subcategories. For example, under the ejb category are stateless, stateful, security, mdb, bmp, and cmp subcategories.

The install_dir/samples/common.xml file defines properties common to all sample applications and implements targets needed to compile, assemble, deploy and undeploy sample applications. In most sample applications, the build.xml file includes common.xml.

After you deploy the sample in Sun ONE Application Server, you can invoke it using the following URL:

For a detailed description of the sample and how to deploy and run it, see the associated documentation at:


Note	Before using the samples under install_dir/samples/webservices, make sure to copy the Java XML Pack JAR files into the jre/lib/endorsed directory to override the JAR files bundled with the JDK.

Assembling Modules and Applications

Assembling (or packaging) modules and applications in Sun ONE Application Server conforms to all of the customary J2EE-defined specifications. The only difference is that when you assemble in Sun ONE Application Server, you include Sun ONE Application Server-specific deployment descriptors (such as sun-web.xml and sun-ejb-jar.xml) that enhance the functionality of the application server.

Tools for Assembly

The Sun ONE Application Server provides these methods for assembling a module or an application:

Apache Ant

Sun ONE Studio

You can use Sun ONE Studio 4 to assemble J2EE applications and modules. For more information about using Sun ONE Studio, see the Sun ONE Studio 4, Enterprise Edition Tutorial.

The Deployment Descriptor Verifier

The verifier tool validates both J2EE and Sun One Application Server specific deployment descriptors against their corresponding DTD files and gives errors and warnings if a module or application is not J2EE and Sun One 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.

Command Line Syntax


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

The following table shows the options for the verifier tool. The left column lists options, and the right column lists descriptions of those options.

Table 4-5 verifier options
Option	Description
-v	Turns on verbose debug mode.
-d output_dir	Writes test results to the output_dir, which must already exist. By default, the results files are created in the system-defined tmp directory.
-ra	Sets the output report level to display all results. This is the default in both verbose and non verbose modes.
-rw	Sets the output report level to display only warning and failure results.
-rf	Sets the output report level to display only failure results.

For example, the following command runs the verifier in verbose mode and writes all the results of static verification of the ejb.jar file to the output directory ResultsDir:

If the verifier runs successfully, a result code of 0 is returned. This does not mean that no verification errors occurred. A non-zero error code is returned if the verifier fails to run.

Ant Integration

You can integrate the verifier into an Ant build file as a target and use the Ant call feature to call the target each time an application or module is assembled. This is because the main method in com.sun.enterprise.tools.verifier.Verifier is callable from user Ant scripts. The main method accepts the arguments described in the "verifier options" table.

Sample Results Files

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

---------------------------
STATIC VERIFICATION RESULTS
---------------------------
----------------------------------
NUMBER OF FAILURES/WARNINGS/ERRORS
----------------------------------

# of Failures : 3
# of Warnings : 6
# of Errors : 0

-----------------------------
RESULTS FOR EJB-RELATED TESTS
-----------------------------
--------------
FAILED TESTS :
--------------

Test Name : tests.ejb.session.TransactionTypeNullForContainerTX
Test Assertion : Session bean with bean managed transaction demarcation test
Test Description : For [ TheGreeter ]
Error: Session Beans [ TheGreeter ] with [ Bean ] managed transaction demarcation should not have container transactions defined.

...

---------------
PASSED TESTS :
---------------

Test Name : tests.ejb.session.ejbcreatemethod.EjbCreateMethodStatic
Test Assertion : Each session Bean must have at least one non-static ejbCreate method test
Test Description : For [ TheGreeter ] For EJB Class [ samples.helloworld.ejb.GreeterEJB ] method [ ejbCreate ] [ samples.helloworld.ejb.GreeterEJB ] properly declares non-static ejbCreate(...) method.

...

-----------
WARNINGS :
-----------

Test Name : tests.ejb.businessmethod.BusinessMethodException
Test Assertion : Enterprise bean business method throws RemoteException test
Test Description :

Test Name : tests.ejb.ias.beanpool.IASEjbBeanPool
Test Assertion :
Test Description : WARNING [IAS-EJB ejb] : bean-pool should be defined for Stateless Session and Message Driven Beans

...

---------------------
NOTAPPLICABLE TESTS :
---------------------

Test Name : tests.ejb.entity.pkmultiplefield.PrimaryKeyClassFieldsCmp
Test Assertion : Ejb primary key class properly declares all class fields within subset of the names of the container-managed fields test.
Test Description : For [ TheGreeter ] class com.sun.enterprise.tools.verifier.tests.ejb.entity.pkmultiplefield. PrimaryKeyClassFieldsCmp expected Entity bean, but called with Session.

Test Name : tests.ejb.entity.ejbcreatemethod.EjbCreateMethodReturn
Test Assertion : Each entity Bean may have zero or more ejbCreate methods which return primary key type test
Test Description : For [ TheGreeter ] class com.sun.enterprise.tools.verifier.tests.ejb.entity.ejbcreatemethod. EjbCreateMethodReturn expected Entity bean, but called with Session bean.

...

-----------------------------------
RESULTS FOR OTHER XML-RELATED TESTS
-----------------------------------
---------------
PASSED TESTS :
---------------

Test Name : tests.dd.ParseDD
Test Assertion : Test parses the deployment descriptor using a SAX parser to avoid the dependency on the DOL
Test Description : PASSED [EJB] : [ remote ] and [ home ] tags present.
PASSED [EJB]: session-type is Stateless.
PASSED [EJB]: trans-attribute is NotSupported.
PASSED [EJB]: transaction-type is Bean.

...

Assembling a WAR Module

Create a working directory, and copy the contents of your web module into it. Make sure it has the structure described in the Sun ONE Application Server Developer’s Guide to Web Applications.

Create two deployment descriptor files with these names: web.xml (required) and sun-web.xml (optional). For more information about these files, see the Sun ONE Application Server Developer’s Guide to Web Applications.



Tip	The first time, you can assemble the WAR module and create the deployment descriptors using Sun ONE Studio. The resulting WAR file can be extracted to yield the deployment descriptors.

Execute this command to create the WAR file:

jar -cvf module_name.war *



Tip	The assembly process can be automated using the Ant tool. To learn more, see "Apache Ant Assembly and Deployment Tool".

Assembling an EJB JAR Module

Create a working directory, and copy the contents of your module into it. Make sure it has the structure described in the Sun ONE Application Server Developer’s Guide to Enterprise JavaBeans Technology.

Create two deployment descriptor files with these names: ejb-jar.xml and sun-ejb-jar.xml (both required). For more information about these files, see the Sun ONE Application Server Developer’s Guide to Enterprise JavaBeans Technology. If the EJB component is an entity bean with container-managed persistence, you must also create a .dbschema file and a sun-cmp-mapping.xml file.



Tip	The first time, you can assemble the EJB JAR module and create the deployment descriptors using Sun ONE Studio. The resulting EJB JAR file can be extracted to yield the deployment descriptors.

Execute this command to create the JAR file:

jar -cvf module_name.jar *



Tip	The assembly process can be automated using the Ant tool. To learn more, see "Apache Ant Assembly and Deployment Tool".



Note	According to the J2EE specification, section 8.1.1.2, “Dependencies,” you cannot package utility classes within an individually deployed EJB module. Instead, package the EJB module and utility JAR within an application using the JAR Extension Mechanism Architecture. For other alternatives, see "Circumventing Classloader Isolation".

Assembling a Lifecycle Module

Assembling an Application


Tip	The assembly process can be automated using the Ant tool. To learn more, see "Apache Ant Assembly and Deployment Tool".

Create a working directory, and copy the contents of your application into it, including all modules. Make sure it has the structure described in the Sun ONE Application Server Developer’s Guide to Enterprise JavaBeans Technology.

Create two deployment descriptor files with these names: application.xml (required) and sun-application.xml (optional). For more information about these files, see "Sample Application XML Files".



Tip	The first time, you can assemble the application and create the deployment descriptors using Sun ONE Studio. The resulting EAR file can be extracted to yield the deployment descriptors.

Execute this command to create the J2EE application EAR file:

jar -cvf app_name.ear *



Tip	The assembly process can be automated using the Ant tool. To learn more, see "Apache Ant Assembly and Deployment Tool".

Assembling an ACC Client

This section provides some brief pointers for assembling ACC clients, but you should first read the Sun ONE Application Server Developer’s Guide to Clients.

Create a working directory, and copy the contents of your module into it. Make sure it has the structure described in the Sun ONE Application Server Developer’s Guide to Clients.

Create deployment descriptor files with these names: application-client.xml and sun-application-client.xml (both required). For more information about these files, see the Sun ONE Application Server Developer’s Guide to Clients.



Tip	The first time, you can assemble the client JAR module and create the deployment descriptors using Sun ONE Studio. The resulting client JAR file can be extracted to yield the deployment descriptors.

Execute this command to create the client JAR file:

jar -cvfm module_name.jar META-INF/MANIFEST.MF *



Tip	The assembly process can be automated using the Ant tool. To learn more, see "Apache Ant Assembly and Deployment Tool".

For a brief description of how to deploy an ACC client and prepare the client machine, see "Deploying an ACC Client".

Assembling a J2EE CA Resource Adapter

This section provides some brief pointers for assembling J2EE CA resource adapters, but you should first read the Sun ONE J2EE CA Service Provider Implementation Administrator’s Guide.

The following XML connector files are required for deploying a connector to the application server.

The ra.xml file is based on the J2EE CA specification and is packaged with the connector. The sun-ra.xml file contains Sun ONE Application Server specific information.

Create a working directory, and copy the contents of your module into it. Make sure it has the structure described in the Sun ONE J2EE CA Service Provider Implementation Administrator’s Guide.

Create two deployment descriptor files with these names: ra.xml and sun-ra.xml. For more information about these files, see the Sun ONE J2EE CA Service Provider Implementation Administrator’s Guide.



Tip	The first time, you can assemble the RAR module and create the deployment descriptors using Sun ONE Studio. The resulting RAR file can be extracted to yield the deployment descriptors.

Execute this command to create the RAR file:

jar -cvf module_name.rar *



Tip	The assembly process can be automated using the Ant tool. To learn more, see "Apache Ant Assembly and Deployment Tool".

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

When you deploy an application or module, a unique name is generated in the Sun ONE Application Server deployment descriptors file. Redeploying an application changes this name. Do not change this name manually. 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. This prevents a partial deployment that could leave the server in an inconsistent state.

The Deployment Life Cycle

After an application is initially deployed, it may be modified and reloaded, redeployed, disabled, re-enabled, and finally undeployed (removed from the server). This section covers the following topics related to the deployment life cycle:

Dynamic Deployment

You can deploy, redeploy, and undeploy an application or module without restarting the server. This is called dynamic deployment.

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.

Dynamic Reloading

If dynamic reloading is enabled, you do not have to redeploy an application or module when you change its code or deployment descriptors. All you have to do is copy the changed JSP or class files into the deployment directory for the application or module. The server checks for changes periodically and redeploys the application, automatically and dynamically, with the changes.

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

In addition, to load new servlet files, reload EJB related changes, or reload deployment descriptor changes, you must do the following:


Note	You can overwrite a previously deployed application by using the --force option of asadmin deploy or by checking the appropriate box in the Administration interface during deployment. However, you must remove a preconfigured resource before you can update it. Redeploying an application changes its automatically generated name.

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 the reload-interval property to -1.

Tools for Deployment

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

Apache Ant

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.

The asadmin Command


Note	In Sun ONE Studio, deploying a module or application is referred to as executing it. Execution also includes making sure the server is running and displaying the correct URL to activate the module or application.

You can use the asadmin command to deploy or undeploy applications and individually deployed modules on local servers. Concurrent deployment on multiple machines or instances is not supported. This section describes the asadmin command only briefly. For full details, see the Sun ONE Application Server Administrator’s Guide.

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, or client. The syntax is as follows, with defaults shown for optional parameters that have them:

asadmin deploy --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--virtualservers virtual_servers] [--type application|ejb|web|connector] [--contextroot contextroot] [--force=true] [--precompilejsp=false] [--verify=false] [--name component_name] [--upload=true] [--retrieve local_dirpath] [--instance instance_name] filepath

asadmin deploy --user jadams --password secret --host localhost --port 4848 --type ejb --instance server1 packagingEJB.jar

If upload is set to false, the filepath must be an absolute path on the server machine.

asadmin deploydir

The asadmin deploydir command deploys an application or module in an open directory structure. The structure must be as specified in "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] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--virtualservers virtual_servers] [--type application|ejb|web|connector] [--contextroot contextroot] [--force=true] [--precompilejsp=false] [--verify=false] [--name component_name] [--instance instance_name] dirpath

asadmin deploydir --user jadams --password secret --host localhost --port 4848 --type ejb --instance server1 packagingEJB

If upload is set to false, the filepath must be an absolute path on the server machine.

asadmin undeploy


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

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, connector, or client. The syntax is as follows, with defaults shown for optional parameters that have them:

asadmin undeploy --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--type application|ejb|web|connector] [--instance instance_name] component_name

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:

Deployment by Module or Application

You can deploy applications or individual modules that are independent of applications. The runtime and file system implications of application-based or individual module-based deployment are described in "Runtime Environments".

Individual module-based deployment is preferable when components need to be accessed by:

Modules can be combined into an EAR file and then deployed as a single module. This is similar to deploying the modules of the EAR independently.

Deploying a WAR Module

You can precompile JSPs during deployment by checking the appropriate box in the Administration interface or by using the --precompilejsp option of the asadmin deploy or asadmin deploydir command. The sun-appserv-deploy and sun-appserv-jspc Ant tasks also allow you to precompile JSPs.

You can keep the generated source for JSPs 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 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 JSP precompilation and the -keepgenerated property, see the Sun ONE Application Server Developer’s Guide to Web Applications.

Deploying an 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 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

The asadmin Command

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] [--passwordfile password_file] [--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

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] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--instance instance_name] module_name

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] [--passwordfile password_file] [--host localhost] [--port 4848] instance_name

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:

Deploying an ACC Client

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

If you wish to execute the client on the Sun ONE Application Server machine to test it, you can use the appclient script in the install_dir/bin directory. If you are using the default server instance, the only required option is -client. For example:

The -xml parameter, which specifies the location of the sun-acc.xml file, is also required if you are not using the default instance.

Before you can execute an ACC client on a different machine, you must prepare the client machine:

You are now ready to execute the client. For more information, see the Sun ONE Application Server Developer’s Guide to Clients.

Deploying a J2EE CA Resource Adapter

Access to Shared Frameworks

When J2EE applications and modules use shared framework classes (such as utility classes and libraries) the classes can be put in the path for the System Classloader or the Common Classloader rather than in an application or module. If you assemble a large, shared library into every module that uses it, the result is a huge file that takes too long to register with the server. In addition, several versions of the same class could exist in different classloaders, which is a waste of resources.

Apache Ant Assembly and Deployment Tool

You can use the automated assembly features available through Ant, a Java-based build tool available through the Apache Software Foundation:

Ant is a java-based build tool that is extended using Java classes. Instead of using shell commands, you declare the assembly steps using an XML document. Each task is run by an object that implements a particular task interface.

Apache Ant 1.4.1 is provided with Sun ONE Application Server (or with the operating system for bundled Solaris 9). The sample applications provided with Sun ONE Application Server have Ant build.xml files; see "Sample Applications".

Ant Tasks for Sun ONE Application Server 7

Use the Ant tasks provided by Sun ONE Application Server for assembling, deploying, and undeploying modules and applications, and for configuring the server instance. The tasks are as follows:

sun-appserv-deploy

Deploys any of the following to a local or remote Sun ONE Application Server instance.

Subelements

The following table describes subelements for the sun-appserv-deploy task. These are objects upon which this task acts. The left column lists the subelement name, and the right column describes what the element specifies.

Attributes

sun-appserv-deploy subelements
Element	Description
server	A Sun ONE Application Server instance.
component	A component to be deployed.
fileset	A set of component files that match specified parameters.

The following table describes attributes for the sun-appserv-deploy task. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute specifies.

sun-appserv-deploy attributes
Attribute	Default	Description
file	none	(optional if a component or fileset subelement is present, otherwise required) The component to deploy. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. If upload is set to false, this must be an absolute path on the server machine.
name	file name without extension	(optional) The display name for the component being deployed.
type	determined from the file or directory name extension	(optional) The type of component being deployed. Valid types are application, ejb, web, and connector. If not specified, the file (or directory) extension is used to determine the component type: .ear for applicaton, .jar for ejb, .war for web, and .rar for connector. If it’s not possible to determine the component type using the file extension, the default is application.
force	true	(optional) If true, the component is overwritten if it already exists on the server. If false, sun-appserv-deploy fails if the component exists.
retrievestubs	client stubs not saved	(optional) The directory where client stubs are saved. This attribute is inherited by nested component elements.
precompilejsp	false	(optional) If true, all JSPs found in an enterprise application (.ear) or web application (.war) are precompiled. This attribute is ignored for other component types. This attribute is inherited by nested component elements.
verify	false	(optional) If true, syntax and semantics for all deployment descriptors are automatically verified for correctness. This attribute is inherited by nested component elements.
contextroot	file name without extension	(optional) The context root for a web module (WAR file). This attribute is ignored if the component is not a WAR file.
upload	true	(optional) If true, the component is transferred to the server for deployment. If the component is being deployed on the local machine, set upload to false to reduce deployment time.
virtualservers	default virtual server only	(optional) A comma-separated list of virtual servers to be deployment targets. This attribute applies only to application (.ear) or web (.war) components and is ignored for other component types. This attribute is inherited by nested server elements.
user	admin	(optional) The username used when logging into the application server administration instance. This attribute is inherited by nested server elements.
password	none	The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
host	localhost	(optional) Target server. When deploying to a remote server, use the fully qualified hostname. This attribute is inherited by nested server elements.
port	4848	(optional) The administration port on the target server. This attribute is inherited by nested server elements.
instance	name of default instance	(optional) Target application server instance. This attribute is inherited by nested server elements.
sunonehome	see description	(optional) The installation directory for the local Sun ONE Application Server 7 installation, which is used to find the administrative classes. If not specified, the command checks to see if the sunone.home parameter has been set. Otherwise, administrative classes must be in the system classpath.

Examples

<sun-appserv-deploy
  file="${assemble}/simpleapp.ear"
  name="simpleapp"
  type="application"
  force="true"
  precompilejsp="false"
  verify="false"
  upload="true"
  user="admin"
  password="${password}"
  host="localhost"
  port="4848"
  instance="${default-instance-name}"
  sunonehome="${sunone.home}" />

This example deploys multiple components to the same Sun ONE Application Server instance running on a remote server:

<sun-appserv-deploy password="${password}" host="greg.sun.com"
      sunonehome="/opt/sunone" >
  <component file="${assemble}/simpleapp.ear"/>
  <component file="${assemble}/simpleservlet.war"
    contextroot="test"/>
  <component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

This example deploys multiple components to two Sun ONE Application Server instances running on remote servers. In this example, both servers are using the same admin password. If this were not the case, each password could be specified in the server element.

<sun-appserv-deploy password="${password}" sunonehome="/opt/sunone" >
  <server host="greg.sun.com"/>
  <server host="joe.sun.com"/>
  <component file="${assemble}/simpleapp.ear"/>
  <component file="${assemble}/simpleservlet.war"
    contextroot="test"/>
  <component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

This example deploys the same components as the previous example because the three components match the fileset criteria, but note that it’s not possible to set some component-specific attributes. All component-specific attributes (name, type, and contextroot) use their default values.

<sun-appserv-deploy password="${password}" host="greg.sun.com"
sunonehome="/opt/sunone" >
<fileset dir="${assemble}" includes="**/*.?ar" />
</sun-appserv-deploy>

sun-appserv-undeploy

Undeploys any of the following from a local or remote Sun ONE Application Server instance.

Subelements

The following table describes subelements for the sun-appserv-undeploy task. These are objects upon which this task acts. The left column lists the subelement name, and the right column describes what the element specifies.

Attributes

sun-appserv-undeploy subelements
Element	Description
server	A Sun ONE Application Server instance.
component	A component to be deployed.
fileset	A set of component files that match specified parameters.

The following table describes attributes for the sun-appserv-undeploy task. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute specifies.

sun-appserv-undeploy attributes
Attribute	Default	Description
name	file name without extension	(optional if a component or fileset subelement is present or the file attribute is specified, otherwise required) The display name for the component being undeployed.
file	none	(optional) The component to undeploy. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded.
type	determined from the file or directory name extension	(optional) The type of component being undeployed. Valid types are application, ejb, web, and connector. If not specified, the file (or directory) extension is used to determine the component type: .ear for applicaton, .jar for ejb, .war for web, and .rar for connector. If it’s not possible to determine the component type using the file extension, the default is application.
user	admin	(optional) The username used when logging into the application server administration instance. This attribute is inherited by nested server elements.
password	none	The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
host	localhost	(optional) Target server. When deploying to a remote server, use the fully qualified hostname. This attribute is inherited by nested server elements.
port	4848	(optional) The administration port on the target server. This attribute is inherited by nested server elements.
instance	name of default instance	(optional) Target application server instance. This attribute is inherited by nested server elements.
sunonehome	see description	(optional) The installation directory for the local Sun ONE Application Server 7 installation, which is used to find the administrative classes. If not specified, the command checks to see if the sunone.home parameter has been set. Otherwise, the administrative classes must be in the system classpath.

Examples

<sun-appserv-undeploy
  name="simpleapp"
  type="application"
  user="admin"
  password="${password}"
  host="localhost"
  port="4848"
  instance="${default-instance-name}"
  sunonehome="${sunone.home}" />

This example demonstrates using the archive files (EAR and WAR, in this case) for the undeployment, using the component name and type (for undeploying the EJB component in this example), and undeploying multiple components.

<sun-appserv-undeploy password="${password}">
  <component file="${assemble}/simpleapp.ear"/>
  <component file="${assemble}/simpleservlet.war"/>
  <component name="simplebean" type="ejb"/>
</sun-appserv-undeploy>

As with the deployment process, components can be undeployed from multiple servers in a single command. This example shows the same three components being removed from two different instances of Sun ONE Application Server 7. In this example, the passwords for both instances are the same.

<sun-appserv-undeploy password="${password}">
  <server host="greg.sun.com"/>
  <server host="joe.sun.com"/>
  <component file="${assemble}/simpleapp.ear"/>
  <component file="${assemble}/simpleservlet.war"/>
  <component name="simplebean" type="ejb"/>
</sun-appserv-undeploy>

sun-appserv-instance

Starts, stops, restarts, creates, or removes one or more application server instances.

Subelements

The following table describes subelements for the sun-appserv-instance task. These are objects upon which this task acts. The left column lists the subelement name, and the right column describes what the element specifies.

Attributes

sun-appserv-instance subelements
Element	Description
server	A Sun ONE Application Server instance.

The following table describes attributes for the sun-appserv-instance task. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute specifies.

sun-appserv-instance attributes
Attribute	Default	Description
action	none	The control command for the target application server. Valid values are start, stop, restart, create, and delete. A restart sends the stop command followed by the start command. The restart command is not supported on Windows.
debug	false	(optional) If action is set to start or restart, specifies whether the server starts in debug mode. This attribute is ignored for other values of action. If true, the instance generates additional debugging output throughout its lifetime. This attribute is inherited by nested server elements.
instanceport	none	(optional unless action is create) If a new instance is being created, this attribute specifies its port number. Otherwise, this attribute is ignored. This attribute is inherited by nested server elements.
local	false	(optional) If true, an instance on the local machine (in other words,localhost) is the target for the action, an administration server need not be running, and the host, port, user, and password attributes are ignored. If false, an administration server must be running and the host, port, user, and password attributes must be set appropriately. This attribute is inherited by nested server elements.
domain		(optional unless local="true" and there are multiple local domains) The target domain for a local action. If local="false" this attribute is ignored. This attribute is inherited by nested server elements.
user	admin	(optional) The username used when logging into the application server administration instance. This attribute is inherited by nested server elements.
password	none	(required unless local is set to true)The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
host	localhost	(optional) Target server. If it is a remote server, use the fully qualified hostname. This attribute is inherited by nested server elements.
port	4848	(optional) The administration port on the target server. This attribute is inherited by nested server elements.
instance	name of default instance	Target application server instance. This attribute is inherited by nested server elements.
sunonehome	see description	(optional) The installation directory for the local Sun ONE Application Server 7 installation, which is used to find the administrative classes. If not specified, the command checks to see if the sunone.home parameter has been set. Otherwise, the administrative classes must be in the system classpath.

Examples

<sun-appserv-instance action="start" password="${password}"
instance="${default-instance-name}"/>

<sun-appserv-instance
  action="start"
  user="admin"
  password="${password}"
  host="localhost"
  port="4848"
  instance="${default-instance-name}"
  sunonehome="${sunone.home}" />

Multiple servers can be controlled using a single command. In this example, two servers are restarted, and in this case each server uses a different password:

<sun-appserv-instance action="restart"
    instance="${default-instance-name}"/>
  <server host="greg.sun.com" password="${password.greg}"/>
  <server host="joe.sun.com" password="${password.joe}"/>
</sun-appserv-instance>

<sun-appserv-instance
  action="create" instanceport="8080"
  password="${password}"
  instance="development" />

<sun-appserv-instance
  action="create"
  instanceport="8080"
  user="admin"
  password="${password}"
  host="localhost"
  port="4848"
  instance="development"
  sunonehome="${sunone.home}" />

Instances can be created on multiple servers using a single command. This example creates a new instance named qa on two different servers. In this case, both servers use the same password.

<sun-appserv-instance
    action="create"
    instanceport="8080"
    instance="qa"
    password="${password}>
  <server host="greg.sun.com"/>
  <server host="joe.sun.com"/>
</sun-appserv-instance>

<sun-appserv-instance
    action="delete"
    instance="qa"
    password="${password}>
  <server host="greg.sun.com"/>
  <server host="joe.sun.com"/>
</sun-appserv-instance>

Different instance names and instance ports can also be specified using attributes of the server subelement:

<sun-appserv-instance action="create" password="${password}>
  <server host="greg.sun.com" instanceport="8080" instance="qa"/>
  <server host="joe.sun.com" instanceport="9090"
    instance="integration-test"/>
</sun-appserv-instance>

sun-appserv-component

Enables or disables the following J2EE component types that have been deployed to Sun ONE Application Server 7.

You don’t need to specify the archive to enable or disable a component: only the component name is required. You can use the component archive, however, because it implies the component name.

Subelements

The following table describes subelements for the sun-appserv-component task. These are objects upon which this task acts. The left column lists the subelement name, and the right column describes what the element specifies.

Attributes

sun-appserv-component subelements
Element	Description
server	A Sun ONE Application Server instance.
component	A component to be deployed.
fileset	A set of component files that match specified parameters.

The following table describes attributes for the sun-appserv-component task. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute specifies.

sun-appserv-component attributes
Attribute	Default	Description
action	none	The control command for the target application server. Valid values are enable and disable.
name	file name without extension	(optional if a component or fileset subelement is present or the file attribute is specified, otherwise required) The display name for the component being enabled or disabled.
file	none	(optional) The component to enable or disable. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded.
type	determined from the file or directory name extension	(optional) The type of component being enabled or disabled. Valid types are application, ejb, web, and connector. If not specified, the file (or directory) extension is used to determine the component type: .ear for applicaton, .jar for ejb, .war for web, and .rar for connector. If it’s not possible to determine the component type using the file extension, the default is application.
user	admin	(optional) The username used when logging into the application server administration instance. This attribute is inherited by nested server elements.
password	none	The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
host	localhost	(optional) Target server. When enabling or disabling a remote server, use the fully qualified hostname. This attribute is inherited by nested server elements.
port	4848	(optional) The administration port on the target server. This attribute is inherited by nested server elements.
instance	name of default instance	(optional) Target application server instance. This attribute is inherited by nested server elements.
sunonehome	see description	(optional) The installation directory for the local Sun ONE Application Server 7 installation, which is used to find the administrative classes. If not specified, the command checks to see if the sunone.home parameter has been set. Otherwise, the administrative classes must be in the system classpath.

Examples

<sun-appserv-component
  action="disable"
  name="simpleapp"
  password="${password}" />

<sun-appserv-component
  action="enable"
  name="simpleapp"
  password="${password}" />

<sun-appserv-component
  action="enable"
  name="simpleapp"
  type="application"
  user="admin"
  password="${password}"
  host="localhost"
  port="4848"
  instance="${default-instance-name}"
  sunonehome="${sunone.home}" />

This example demonstrates disabling multiple components using the archive files (EAR and WAR, in this case) and using the component name and type (for an EJB component in this example).

<sun-appserv-component action="disable" password="${password}">
  <component file="${assemble}/simpleapp.ear"/>
  <component file="${assemble}/simpleservlet.war"/>
  <component name="simplebean" type="ejb"/>
</sun-appserv-component>

Components can be enabled or disabled on multiple servers in a single task. This example shows the same three components being enabled on two different instances of Sun ONE Application Server 7. In this example, the passwords for both instances are the same.

<sun-appserv-component action="enable" password="${password}">
  <server host="greg.sun.com"/>
  <server host="joe.sun.com"/>
  <component file="${assemble}/simpleapp.ear"/>
  <component file="${assemble}/simpleservlet.war"/>
  <component name="simplebean" type="ejb"/>
</sun-appserv-component>

sun-appserv-admin

Enables arbitrary administrative commands and scripts to be executed on the Sun ONE Application Server 7. This is useful for cases where a specific Ant task hasn’t been developed or a set of related commands are in a single script.

Subelements

The following table describes subelements for the sun-appserv-admin task. These are objects upon which this task acts. The left column lists the subelement name, and the right column describes what the element specifies.

Attributes

sun-appserv-admin subelements
Element	Description
server	A Sun ONE Application Server instance.

The following table describes attributes for the sun-appserv-admin task. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute specifies.

sun-appserv-admin attributes
Attribute	Default	Description
command	none	(exactly one of these is required: command, commandfile, or explicitcommand) The command to execute. If the user, password, host, port, or instance attributes are also specified, they are automatically inserted into the command before execution. If any of these options are specified in the command string, the corresponding attribute values are ignored.
commandfile	none	(exactly one of these is required: command, commandfile, or explicitcommand) The command script to execute. If commandfile is used, the values of all other attributes are ignored. Be sure to end the script referenced by commandfile with the exit command; if you omit exit, the Ant task may appear to hang after the command script is called.
explicitcommand	none	(exactly one of these is required: command, commandfile, or explicitcommand) The exact command to execute. No command processing is done, and all other attributes are ignored.
user	admin	(optional) The username used when logging into the application server administration instance. This attribute is inherited by nested server elements.
password	none	(optional) The password used when logging into the application server administration instance. This attribute is inherited by nested server elements.
host	localhost	(optional) Target server. If it is a remote server, use the fully qualified hostname. This attribute is inherited by nested server elements.
port	4848	(optional) The administration port on the target server. This attribute is inherited by nested server elements.
instance	name of default instance	(optional) Target application server instance. This attribute is inherited by nested server elements.
sunonehome	see description	(optional) The installation directory for the local Sun ONE Application Server 7 installation, which is used to find the administrative classes. If not specified, the command checks to see if the sunone.home parameter has been set. Otherwise, the administrative classes must be in the system classpath.

sun-appserv-jspc

Precompiles JSP source code into Sun ONE Application Server compatible Java code for initial invocation by Sun ONE Application Server. Use this task to speed up access to JSP pages or to check the syntax of JSP source code. You can feed the resulting Java code to the javac task to generate class files for the JSPs.

Subelements

Attributes

The following table describes attributes for the sun-appserv-jspc task. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute specifies.

sun-appserv-jspc attributes
Attribute	Default	Description
destdir		The destination directory for the generated Java source files.
srcdir		(exactly one of these is required: srcdir or webapp) The source directory where the JSP files are located.
webapp		(exactly one of these is required: srcdir or webapp) The directory containing the web application. All JSP pages within the directory are recursively parsed. The base directory must have a WEB-INF subdirectory beneath it. When webapp is used, sun-appserv-jspc hands off all dependency checking to the compiler.
verbose	2	(optional) The verbosity integer to be passed to the compiler.
classpath		(optional) The classpath for running the JSP compiler.
classpathref		(optional) A reference to the JSP compiler classpath.
uribase	/	(optional) The URI context of relative URI references in the JSP pages. If this context does not exist, it is derived from the location of the JSP file relative to the declared or derived value of uriroot. Only pages translated from an explicitly declared JSP file are affected.
uriroot	see description	(optional) The root directory of the web application, against which URI files are resolved. If this directory is not specified, the first JSP page is used to derive it: each parent directory of the first JSP page is searched for a WEB-INF directory, and the directory closest to the JSP page that has one is used. If no WEB-INF directory is found, the directory sun-appserv-jspc was called from is used. Only pages translated from an explicitly declared JSP file (including tag libraries) are affected.
package		(optional) The destination package for the generated Java classes.
failonerror	true	(optional) If true, JSP compilation fails if errors are encountered.
sunonehome	see description	(optional) The installation directory for the local Sun ONE Application Server 7 installation, which is used to find the administrative classes. If not specified, the command checks to see if the sunone.home parameter has been set. Otherwise, the administrative classes must be in the system classpath.

Example

The following example uses the webapp attribute to generate Java source files from JSP files. The sun-appserv-jspc task is immediately followed by a javac task, which compiles the generated Java files into class files. The classpath value in the javac task must be all on one line with no spaces.

<sun-appserv-jspc
  destdir="${assemble.war}/generated"
  webapp="${assemble.war}"
  classpath="${assemble.war}/WEB-INF/classes"
  sunonehome="${sunone.home}" />
<javac
  srcdir="${assemble.war}/WEB-INF/generated"
  destdir="${assemble.war}/WEB-INF/generated"
  debug="on"
   classpath="${assemble.war}/WEB-INF/classes:${sunone.home}/lib/appse rv-rt.jar:${sunone.home}/lib/appserv-ext.jar">
  <include name="**/*.java"/>
</javac>

Reusable Subelements

Reusable subelements of the Ant tasks for Sun ONE Application Server 7 are as follows. These are objects upon which the Ant tasks act.

server

Specifies a Sun ONE Application Server instance. Allows a single task to act on multiple server instances. The server attributes override corresponding attributes in the parent task; therefore, the parent task attributes function as default values.

Subelements

Attributes

The following table describes attributes for the server element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute specifies.

server attributes
Attribute	Default	Description
user	admin	(optional) The username used when logging into the application server administration instance.
password	none	(optional if specified in the parent task) The password used when logging into the application server administration instance.
host	localhost	(optional) Target server. When targeting a remote server, use the fully qualified hostname.
port	4848	(optional) The administration port on the target server.
instance	name of default instance	(optional) Target application server instance.
domain		(applies to sun-appserv-instance only, optional unless local="true" and there are multiple local domains) The target domain for a local action. If local="false" this attribute is ignored.
instanceport	none	(applies to sun-appserv-instance only, optional unless action is create) If a new instance is being created, this attribute specifies its port number. Otherwise, this attribute is ignored.
debug	false	(applies to sun-appserv-instance only, optional) If action is set to start, specifies whether the server starts in debug mode. This attribute is ignored for other values of action. If true, the instance generates additional debugging output throughout its lifetime.
local	false	(applies to sun-appserv-instance only, optional) If true, an instance on the local machine (in other words, localhost) is the target for the action, an administration server need not be running, and the host, port, user, and password attributes are ignored. If false, an administration server must be running and the host, port, user, and password attributes must be set appropriately.
upload	true	(applies to sun-appserv-deploy only, optional) If true, the component is transferred to the server for deployment. If the component is being deployed on the local machine, set upload to false to reduce deployment time.
virtualservers	default virtual server only	(applies to sun-appserv-deploy only, optional) A comma-separated list of virtual servers to be deployment targets. This attribute applies only to application (.ear) or web (.war) components and is ignored for other component types.

Examples

You can control multiple servers using a single task. In this example, two servers are started, each using a different password. Only the second server is started in debug mode.

<sun-appserv-instance action="start">
  <server host="greg.sun.com" password="${password.greg}"/>
  <server host="joe.sun.com" password="${password.joe}"
    debug="true"/>
</sun-appserv-instance>

You can create instances on multiple servers using a single task. This example creates a new instance named qa on two different servers. Both servers use the same password.

<sun-appserv-instance action="create" instanceport="8080"
    instance="qa" password="${password}>
  <server host="greg.sun.com"/>
  <server host="joe.sun.com"/>
</sun-appserv-instance>

<sun-appserv-instance action="delete" instance="qa"
    password="${password}>
  <server host="greg.sun.com"/>
  <server host="joe.sun.com"/>
</sun-appserv-instance>

You can specify different instance names and instance ports using attributes of the nested server element:

You can deploy multiple components to multiple servers (see the component nested element. This example deploys each component to two Sun ONE Application Server instances running on remote servers. Both servers use the same password.

<sun-appserv-deploy password="${password}" sunonehome="/opt/s1as7" >
  <server host="greg.sun.com"/>
  <server host="joe.sun.com"/>
  <component file="${assemble}/simpleapp.ear"/>
  <component file="${assemble}/simpleservlet.war"
    contextroot="test"/>
  <component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

You can also undeploy multiple components from multiple servers. This example shows the same three components being removed from two different instances. Both servers use the same password.

You can enable or disable components on multiple servers. This example shows the same three components being enabled on two different instances. Both servers use the same password.

component

Specifies a J2EE component. Allows a single task to act on multiple components. The component attributes override corresponding attributes in the parent task; therefore, the parent task attributes function as default values.

Subelements

Attributes

The following table describes attributes for the component element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute specifies.

component attributes
Attribute	Default	Description
file	none	(optional if the parent task is sun-appserv-undeploy or sun-appserv-component) The target component. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. If upload is set to false, this must be an absolute path on the server machine.
name	file name without extension	(optional) The display name for the component.
type	determined from the file or directory name extension	(optional) The type of component. Valid types are application, ejb, web, and connector. If not specified, the file (or directory) extension is used to determine the component type: .ear for applicaton, .jar for ejb, .war for web, and .rar for connector. If it’s not possible to determine the component type using the file extension, the default is application.
force	true	(applies to sun-appserv-deploy only, optional) If true, the component is overwritten if it already exists on the server. If false, the containing element’s operation fails if the component exists.
precompilejsp	false	(applies to sun-appserv-deploy only, optional) If true, all JSPs found in an enterprise application (.ear) or web application (.war) are precompiled. This attribute is ignored for other component types.
retrievestubs	client stubs not saved	(applies to sun-appserv-deploy only, optional) The directory where client stubs are saved.
contextroot	file name without extension	(applies to sun-appserv-deploy only, optional) The context root for a web module (WAR file). This attribute is ignored if the component is not a WAR file.
verify	false	(applies to sun-appserv-deploy only, optional) If true, syntax and semantics for all deployment descriptors is automatically verified for correctness.

Examples

You can deploy multiple components using a single task. This example deploys each component to the same Sun ONE Application Server instance running on a remote server.

<sun-appserv-deploy password="${password}" host="greg.sun.com"
    sunonehome="/opt/s1as7" >
  <component file="${assemble}/simpleapp.ear"/>
  <component file="${assemble}/simpleservlet.war"
    contextroot="test"/>
  <component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

You can also undeploy multiple components using a single task. This example demonstrates using the archive files (EAR and WAR, in this case) and the component name and type (for the EJB component).

<sun-appserv-undeploy password="${password}">
  <component file="${assemble}/simpleapp.ear"/
  <component file="${assemble}/simpleservlet.war"/>
  <component name="simplebean" type="ejb"/>
</sun-appserv-undeploy>

You can deploy multiple components to multiple servers. This example deploys each component to two instances running on remote servers. Both servers use the same password.

You can also undeploy multiple components to multiple servers. This example shows the same three components being removed from two different instances. Both servers use the same password.

You can enable or disable multiple components. This example demonstrates disabling multiple components using the archive files (EAR and WAR, in this case) and the component name and type (for the EJB component).

You can enable or disable multiple components on multiple servers. This example shows the same three components being enabled on two different instances. Both servers use the same password.

fileset

Selects component files that match specified parameters. When fileset is included as a subelement, the name and contextroot attributes of the containing element must use their default values for each file in the fileset. For more information, see:

The Application Deployment Descriptor Files

Sun ONE Application Server applications include two deployment descriptor files:

The sun-application_1_3-0.dtd File

The sun-application_1_3-0.dtd file defines the structure of the sun-application.xml file, including the elements it can contain and the subelements and attributes these elements can have. The sun-application_1_3-0.dtd file is located in the install_dir/lib/dtds directory.

Each element defined in a DTD file (which may be present in the corresponding XML file) can contain the following:

Subelements


Note	Do not edit the sun-application_1_3-0.dtd file; its contents change only with new versions of Sun ONE Application Server.

Elements can contain subelements. For example, the following code defines the sun-application element.

<!ELEMENT sun-application (web*, pass-by-reference?, unique-id?, security-role-mapping*)>

The ELEMENT tag specifies that a sun-application element can contain web, pass-by-reference, unique-id, and security-role-mapping elements.

The following table shows how optional suffix characters of subelements determine the requirement rules, or number of allowed occurrences, for the subelements. The left column lists the subelement ending character, and the right column lists the corresponding requirement rule.

Table 4-6 requirement rules and subelement suffixes
Subelement Suffix	Requirement Rule
element*	Can contain zero or more of this subelement.
element?	Can contain zero or one of this subelement.
element+	Must contain one or more of this subelement.
element (no suffix)	Must contain only one of this subelement.

If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.

Data

Some elements contain character data instead of subelements. These elements have definitions of the following format:

In the sun-application.xml file, white space is treated as part of the data in a data element. Therefore, there should be no extra white space before or after the data delimited by a data element. For example:

Attributes

Elements that have ATTLIST tags contain attributes. None of the elements in the sun-application.xml file contain attributes.

Elements in the sun-application.xml File

sun-application

Defines Sun ONE Application Server specific configuration for an application. This is the root element; there can only be one sun-application element in a sun-application.xml file.

Subelements

The following table describes subelements for the sun-application element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 4-7 sun-application subelements
Element	Required	Description
web	zero or more	Specifies the application’s web tier configuration.
pass-by-reference	zero or one	Determines whether EJB modules use pass-by-value or pass-by-reference semantics.
unique-id	zero or one	Contains the unique ID for the application.
security-role-mapping	zero or more	Maps a role in the corresponding J2EE XML file to a user or group.

web

Subelements

The following table describes subelements for the web element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

web-uri

Contains the web URI for the application. Must match the corresponding element in the application.xml file.

Subelements

context-root

Contains the web context root for the application. Overrides the corresponding element in the application.xml file.

Subelements

pass-by-reference

If false (the default if this element is not present), this application uses pass-by-value semantics, which the EJB specification requires. If true, this application uses pass-by-reference semantics. The setting of this element in the sun-application.xml file applies to all EJB modules in the application.

For an individually deployed EJB module, you can set the same element in the sun-ejb-jar.xml file. If you want to use pass-by-reference at both the bean and application level, the bean level takes precedence over the application level. For details, see the Sun ONE Application Server Developer’s Guide to Enterprise JavaBeans Technology.

Subelements

unique-id

Contains the unique ID for the application. This value is automatically updated each time the application is deployed or redeployed. Do not edit this value.

Subelements

security-role-mapping

Maps roles to users and groups. At least one principal or group name is required, but you do not need to have one of each.

Subelements

The following table describes subelements for the security-role-mapping element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

role-name

Contains the role-name in the security-role element of the application.xml file.

Subelements

principal-name

Subelements

group-name

Subelements

Sample Application XML Files

Sample application.xml File

<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN' 'http://java.sun.com/dtd/application_1_3.dtd'>

Sample sun-application.xml File

<!DOCTYPE sun-application PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.0 J2EE Application 1.3//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-application_ 1_3-0.dtd'>

Element	Required	Description
web-uri	only one	Contains the web URI for the application.
context-root	only one	Contains the web context root for the application.

Chapter 4 Assembling and Deploying J2EE Applications

Overview of Assembly and Deployment

Modules

Applications

J2EE Standard Descriptors

Sun ONE Application Server Descriptors

Naming Standards

JNDI Naming

Directory Structure

Runtime Environments

Module Runtime Environment

Application Runtime Environment

Classloaders

The Classloader Hierarchy

Classloader Universes

Circumventing Classloader Isolation

Using the System Classloader

Using the Common Classloader

Packaging the Client JAR for One Application in Another Application

Sample Applications

Assembling Modules and Applications

Tools for Assembly

Apache Ant

Sun ONE Studio

The Deployment Descriptor Verifier

Command Line Syntax

Ant Integration

Sample Results Files

Assembling a WAR Module

Assembling an EJB JAR Module

Assembling a Lifecycle Module

Assembling an Application

Assembling an ACC Client

Assembling a J2EE CA Resource Adapter

Deploying Modules and Applications

Deployment Names and Errors

The Deployment Life Cycle

Dynamic Deployment

Disabling a Deployed Application or Module

Dynamic Reloading

Tools for Deployment

Apache Ant

Sun ONE Studio

The asadmin Command

asadmin deploy

asadmin deploydir

asadmin undeploy

The Administration Interface

Deployment by Module or Application

Deploying a WAR Module

Deploying an EJB JAR Module

Deploying a Lifecycle Module

The asadmin Command

The Administration Interface

Deploying an ACC Client

Deploying a J2EE CA Resource Adapter

Access to Shared Frameworks

Apache Ant Assembly and Deployment Tool

Ant Tasks for Sun ONE Application Server 7

sun-appserv-deploy

Subelements

Attributes

Examples

sun-appserv-undeploy

Subelements

Attributes

Examples

sun-appserv-instance

Subelements

Attributes

Examples

sun-appserv-component

Subelements

Attributes

Examples

sun-appserv-admin

Subelements

Attributes

sun-appserv-jspc

Subelements

Chapter 4
Assembling and Deploying J2EE Applications