Sun ONE Application Server 7 Developer's Guide |
Assembling and Deploying J2EE ApplicationsThis module 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 module.
The following topics are presented in this module:
- Overview of Assembly and Deployment
- Assembling Modules and Applications
- Deploying Modules and Applications
- Apache Ant Assembly and Deployment Tool
- The Application Deployment Descriptor Files
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
- Applications
- J2EE Standard Descriptors
- Sun ONE Application Server Descriptors
- Naming Standards
- JNDI Naming
- Directory Structure
- Runtime Environments
- Classloaders
- Sample Applications
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.
Sun ONE Application Server also supports lifecycle modules. See "Developing Lifecycle Listeners" for more information.
EJB JAR and Web modules can also be assembled as separate JAR or WAR files and deployed separately, outside of any application, as in the following figure.
   Module Assembly and Deployment
Applications
A J2EE application is a logical collection of one or more J2EE modules tied together by application deployment descriptors. Components can be assembled at either the module or the application level. Components can also be deployed at either the module or the application level.
The following diagram illustrates how components are assembled into modules and then assembled into a Sun ONE Application Server application EAR file ready for deployment.
   Application Assembly and 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:
To check the correctness of these deployment descriptors prior to deployment, see "The Deployment Descriptor Verifier".
The following table shows where to find more information about J2EE standard deployment descriptors. The left column lists the deployment descriptors, and the right column lists where to find more information about those descriptors.
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.
To check the correctness of these deployment descriptors prior to deployment, see "The Deployment Descriptor Verifier".
The following table shows where to find more information about 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.
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 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.
Directory Structure
When you deploy an application, the application is expanded to an open directory structure, and the directories holding the individual modules are named with _jar, _war and _rar suffixes. If you use the asadmin deploydir command to deploy a directory instead of an EAR file, your directory structure must follow this same convention.
Module and application directory structures follow the structure outlined in the J2EE specification. Here is an example directory structure of a simple application containing a web module, an EJB module, and a client module.
+ converter_1/
|--- converterClient.jar
|--+ META-INF/
| |--- MANIFEST.MF
| |--- application.xml
| '--- sun-application.xml
|--+ war-ic_war/
| |--- index.jsp
| |--+ META-INF/
| | |--- MANIFEST.MF
| '--+ WEB-INF/
| |--- web.xml
| '--- sun-web.xml
|--+ ejb-jar-ic_jar/
| |--- Converter.class
| |--- ConverterBean.class
| |--- ConverterHome.class
| '--+ META-INF/
| |--- MANIFEST.MF
| |--- ejb-jar.xml
| '--- sun-ejb-jar.xml
'--+ app-client-ic_jar/
|--- ConverterClient.class
'--+ META-INF/
|--- MANIFEST.MF
|--- application-client.xml
'--- sun-application-client.xml
Here is an example directory structure of an individually deployed connector module.
+ MyConnector/
|--- readme.html
|--- ra.jar
|--- client.jar
|--- win.dll
|--- solaris.so
'--+ META-INF/
|--- MANIFEST.MF
|--- ra.xml
'--- sun-ra.xml
Runtime Environments
Whether you deploy an individual module or an application, deployment affects both the file system and the server configuration. See the following "Module runtime environment" and "Application runtime environment" figures.
Module Runtime Environment
The following figure illustrates the environment for individually deployed module-based deployment.
   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 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.
Lifecycle modules (see "Developing Lifecycle Listeners") are extracted as follows:
instance_dir/applications/lifecycle-modules/module_name
Configuration entries are added in the server.xml file 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 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 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.
Configuration entries are added in the server.xml file 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.
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:
   Classloader runtime hierarchy
Note that this is not a Java inheritance hierarchy, but a delegation hierarchy. In the delegation design, a classloader delegates classloading to its parent before attempting to load a class itself. A classloader parent can be either the System Classloader or another custom classloader. If the parent classloader can't load a class, the findClass() method is called on the classloader subclass. In effect, a classloader is responsible for loading only the classes not available to the parent.
The 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.
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.
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
- Using the Common Classloader
- Packaging the Client JAR for One Application in Another Application
Using the System Classloader
To use the System Classloader, do one of the following, then restart the server:
- Go to the server instance page in the Administration interface, select the JVM Settings tab, select the Path Settings option, edit the Classpath Suffix field, and select Save.
- Edit the classpath-suffix attribute of the java-config element in the server.xml file. For details about server.xml, see the Sun ONE Application Server Administrator's Configuration File Reference.
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.
To package the client JAR for one application in another application:
- 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.
Most Sun ONE Application Server samples have the following directory structure:
- The docs directory contains instructions for how to use the sample.
- The src directory contains:
The build.xml file, which defines asant targets for the sample (see "Apache Ant Assembly and Deployment Tool")
Deployment descriptors
- The build, assemble, and javadocs directories are generated as a result of targets specified in the build.xml file.
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.
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.
The following figure shows the structure of the helloworld sample:
   The helloworld sample
After you deploy the sample in Sun ONE Application Server, you can invoke it using the following URL:
http://server:port/helloworld
For a detailed description of the sample and how to deploy and run it, see the associated documentation at:
install_dir/samples/ejb/stateless/simple/docs/index.html
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.
This section covers the following topics:
- Tools for Assembly
- 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
Tools for Assembly
The Sun ONE Application Server provides these methods for assembling a module or an application:
Apache Ant
Ant can help you assemble and deploy modules and applications. For details, see "Apache Ant Assembly and Deployment Tool".
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.
The verifier is also integrated into the sun-appserv-deploy Ant task.
Tip Using the verifier tool can help you avoid runtime errors that are difficult to debug.
This section covers the following topics:
Command Line Syntax
The verifier tool's syntax is as follows:
verifier [options] file
The file can be an EAR, WAR, RAR, or JAR file.
The following table shows the options for the verifier tool. The left column lists options, and the right column lists descriptions of those options.
For example, the following command runs the verifier in verbose mode and writes all the results of static verification of the ejb.jar file to the output directory ResultsDir:
verifier -v -ra -d ResultsDir ejb.jar
The results files are ejb.jar_verifier.txt and ejb.jar_verifier.xml.
If the verifier runs successfully, a result code of 0 is returned. This does not mean that no verification errors occurred. A non-zero error code is returned if the verifier fails to run.
Ant Integration
You can integrate the verifier into an Ant build file as a target and use the Ant call feature to call the target each time an application or module is assembled. This is because the main method in com.sun.enterprise.tools.verifier.Verifier is callable from user Ant scripts. The main method accepts the arguments described in the "verifier options" table.
Example code for an Ant verify target is as follows:
<target name="verify">
<echo message="Verification Process for ${testfile}"/>
<java classname="com.sun.enterprise.tools.verifier.Verifier"
fork="yes">
<sysproperty key="com.sunone.enterprise.home"
value="${appserv.home}"/>
<sysproperty key="verifier.xsl"
value="${appserv.home}/verifier/config" />
<!-- uncomment the following for verbose output -->
<!--<arg value="-v"/>-->
<arg value="${assemble}/${ejbjar}" />
<classpath path="${appserv.cpath}:${java.class.path}"/>
</java>
</target>Sample Results Files
Here is a sample results XML file:
<static-verification>
<ejb>
<failed>
<test>
<test-name>
tests.ejb.session.TransactionTypeNullForContainerTX
</test-name>
<test-assertion>
Session bean with bean managed transaction demarcation test
</test-assertion>
<test-description>
For [ TheGreeter ] Error: Session Beans [ TheGreeter ] with [ Bean ] managed transaction demarcation should not have container transactions defined.
</test-description>
</test>
</failed>
</ejb>
...
</static-verification>Here is a sample results TXT file:
---------------------------
STATIC VERIFICATION RESULTS
---------------------------
----------------------------------
NUMBER OF FAILURES/WARNINGS/ERRORS
----------------------------------
# of Failures : 3
# of Warnings : 6
# of Errors : 0
-----------------------------
RESULTS FOR EJB-RELATED TESTS
-----------------------------
--------------
FAILED TESTS :
--------------
Test Name : tests.ejb.session.TransactionTypeNullForContainerTX
Test Assertion : Session bean with bean managed transaction demarcation test
Test Description : For [ TheGreeter ]
Error: Session Beans [ TheGreeter ] with [ Bean ] managed transaction demarcation should not have container transactions defined.
...
---------------
PASSED TESTS :
---------------
Test Name : tests.ejb.session.ejbcreatemethod.EjbCreateMethodStatic
Test Assertion : Each session Bean must have at least one non-static ejbCreate method test
Test Description : For [ TheGreeter ] For EJB Class [ samples.helloworld.ejb.GreeterEJB ] method [ ejbCreate ] [ samples.helloworld.ejb.GreeterEJB ] properly declares non-static ejbCreate(...) method.
...
-----------
WARNINGS :
-----------
Test Name : tests.ejb.businessmethod.BusinessMethodException
Test Assertion : Enterprise bean business method throws RemoteException test
Test Description :
Test Name : tests.ejb.ias.beanpool.IASEjbBeanPool
Test Assertion :
Test Description : WARNING [IAS-EJB ejb] : bean-pool should be defined for Stateless Session and Message Driven Beans
...
---------------------
NOTAPPLICABLE TESTS :
---------------------
Test Name : tests.ejb.entity.pkmultiplefield.PrimaryKeyClassFieldsCmp
Test Assertion : Ejb primary key class properly declares all class fields within subset of the names of the container-managed fields test.
Test Description : For [ TheGreeter ] class com.sun.enterprise.tools.verifier.tests.ejb.entity.pkmultiplefield. 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
To assemble a WAR module, follow these steps:
- 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
To assemble an EJB JAR module, follow these steps:
- 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
To assemble a lifecycle module, follow these steps:
- Create a working directory, and copy the contents of your module into it.
- 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".
For general information about lifecycle modules, see "Developing Lifecycle Listeners."
Assembling an Application
To assemble an application, follow these steps:
- 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.
To assemble an ACC client JAR module, follow these steps:
- 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.
- 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.
- ra.xml
- sun-ra.xml (including security map)
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.
To assemble a connector RAR module, follow these steps:
- 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
- The Deployment Life Cycle
- Tools for Deployment
- Deployment by Module or Application
- Deploying a WAR Module
- Deploying an EJB JAR Module
- Deploying a Lifecycle Module
- Deploying an ACC Client
- Deploying a J2EE CA Resource Adapter
- Access to Shared Frameworks
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.
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.
Disabling a Deployed Application or Module
You can disable a deployed application or module without removing it from the server. Disabling an application makes it inaccessible to clients.
To disable an application or module, you can do one of the following:
- Set enabled="false" for the application or module in the server.xml file. For details about server.xml, see the Sun ONE Application Server Administrator's Configuration File Reference.
- Use the Administration interface:
Open the Applications component under your server instance.
Go to the page for the type of application or module. For example, for a web application, go to the Web Apps page.
Check the box for the application or module you wish to disable.
Select the Disable button. The status listed on this page for the application or module changes to Disabled.
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.
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.
For details, see the Sun ONE Application Server Administrator's Guide.
- 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 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
Ant can help you assemble and deploy modules and applications. For details, see "Apache Ant Assembly and Deployment Tool".
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
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.
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, 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
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
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
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
If upload is set to false, the filepath must be an absolute path on the server machine.
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, 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
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 Apps, Web Apps, Connector Modules, or EJB Modules page.
- Click on the Deploy button. (You can also undeploy, enable, or disable an application or module from this page.)
- Enter the full path to the module or application directory or archive file (or click on Browse to find it), then click on the OK button.
- Enter the module or application name.
- For a web module, enter the context root.
- Assign the application or web module to one or more virtual servers by checking the boxes next to the virtual server names.
- You can also redeploy the module or application if it already exists (called forced deployment) by checking the appropriate box. This is optional.
- You can run the verifier to check your deployment descriptor files. This is optional. For details about the verifier, see "The Deployment Descriptor Verifier".
- Other fields are displayed depending on the type of module. Check appropriate boxes and enter appropriate values. Required fields are marked with asterisks (*).
- Click on the OK button.
To deploy a lifecycle module, see "Deploying a Lifecycle Module".
Deployment by Module or Application
You can deploy applications or individual modules that are independent of applications. The runtime and file system implications of application-based or individual module-based deployment are described in "Runtime Environments".
Individual module-based deployment is preferable when components need to be accessed by:
- Other modules
- J2EE Applications
- ACC clients (Module-based deployment allows shared access to a bean from an ACC client, a servlet, or an EJB component.)
Modules can be combined into an EAR file and then deployed as a single module. This is similar to deploying the modules of the EAR independently.
Deploying a WAR Module
You deploy a WAR module as described in "Tools for Deployment".
You can precompile 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 deploy an EJB JAR module as described in "Tools for Deployment".
You can keep the generated source for stubs and ties by adding the -keepgenerated flag to the rmic-options attribute of the java-config element in 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 "Developing Lifecycle Listeners."
You can deploy a lifecycle module using the following tools:
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
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] [--passwordfile password_file] [--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] [--passwordfile password_file] [--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 Lifecycle Modules page.
- Click on the Deploy button.
- Enter the following information:
Name (required) - The name of the lifecycle module.
Class Name (required) - The fully qualified name of the lifecycle module's class file.
Classpath (optional) - The classpath for the lifecycle module. Specifies where the module is located. The default location is under the application root directory.
Load Order (optional) - Determines the order in which lifecycle 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.
Fatal Failure (optional) - Determines whether the server is shut down if the lifecycle module fails. The default is false.
Lifecycle Enabled (optional) - Determines whether the lifecycle module is enabled. The default is true.
- Click on the OK button.
Deploying an ACC Client
Deployment is only necessary for clients that communicate with EJB components. To deploy an ACC client:
- Assemble the necessary client files (as described in "Assembling an ACC Client").
- Assemble the EJB components to be accessed by the client.
- Package the client and EJB components together in an application.
- Deploy the application.
- After deployment, a client JAR file is created in the following location:
instance_dir/applications/j2ee-apps/app_name/app_nameClient.jar
The client JAR contains the ties and necessary classes for the ACC client. Copy this file to the client machine, and set the APPCPATH environment variable on the client to point to this JAR.
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:
appclient -client converterClient.jar
The -xml parameter, which specifies the location of the sun-acc.xml file, is also required if you are not using the default instance.
Before you can execute an ACC client on a different machine, you must prepare the client machine:
- Use the package-appclient script in the install_dir/bin directory to create the ACC package JAR file. This JAR file is created in the install_dir/lib/appclient directory.
- Copy the ACC package JAR file to the client machine and unjar it. This creates a directory structure under an appclient directory.
- Configure the sun-acc.xml file, located in the appclient/appserv/lib/appclient directory.
- Configure the asenv.conf (asenv.bat on Windows) file, located in the appclient/appserv/bin directory.
- Copy the client JAR to 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
You deploy a connector module as described in "Tools for Deployment".
Access to Shared Frameworks
When J2EE applications and modules use shared framework classes (such as utility classes and libraries) the classes can be put in the path for the System Classloader or the Common Classloader rather than in an application or module. If you assemble a large, shared library into every module that uses it, the result is a huge file that takes too long to register with the server. In addition, several versions of the same class could exist in different classloaders, which is a waste of resources.
For more information, see "Circumventing Classloader Isolation".
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:
http://jakarta.apache.org/ant/
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".
Make sure you have done these things before using Ant:
- Include install_dir/bin in the PATH environment variable (/usr/sfw/bin for bundled Solaris 9). The Ant script provided with Sun ONE Application Server, asant, is located in this directory. For details on how to use asant, see the sample applications documentation in the install_dir/samples/docs/ant.html file.
- If you are executing platform-specific applications, such as the exec or cvs task, the ANT_HOME environment variable must be set to the Ant installation directory.
This section covers the following Ant-related topics:
For information about standard Ant tasks, see the Ant documentation:
http://jakarta.apache.org/ant/manual/index.html
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
- sun-appserv-undeploy
- sun-appserv-instance
- sun-appserv-component
- sun-appserv-admin
- sun-appserv-jspc
sun-appserv-deploy
Deploys any of the following to a local or remote Sun ONE Application Server instance.
- Enterprise application (EAR file)
- Web application (WAR file)
- Enterprise Java Bean (EJB-JAR file)
- Enterprise connector (RAR file)
- Application client
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.
   sun-appserv-deploy subelements
Element
Description
A Sun ONE Application Server instance.
A component to be deployed.
A set of component files that match specified parameters.
Attributes
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.
Examples
Here is a simple application deployment script with many implied attributes:
<sun-appserv-deploy
file="${assemble}/simpleapp.ear"
password="${password}" />Here is an equivalent script showing all the implied attributes:
<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.
- Enterprise application (EAR file)
- Web application (WAR file)
- Enterprise Java Bean (EJB-JAR file)
- Enterprise connector (RAR file)
- Application client
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.
   sun-appserv-undeploy subelements
Element
Description
A Sun ONE Application Server instance.
A component to be deployed.
A set of component files that match specified parameters.
Attributes
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.
Examples
Here is a simple application undeployment script with many implied attributes:
<sun-appserv-undeploy name="simpleapp" password="${password}" />
Here is an equivalent script showing all the implied attributes:
<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.
   sun-appserv-instance subelements
Element
Description
A Sun ONE Application Server instance.
Attributes
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.
Examples
This example starts the local Sun ONE Application Server 7 instance:
<sun-appserv-instance action="start" password="${password}"
instance="${default-instance-name}"/>Here is an equivalent script showing all the implied attributes:
<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>This example creates a new Sun ONE Application Server 7 instance:
<sun-appserv-instance
action="create" instanceport="8080"
password="${password}"
instance="development" />Here is an equivalent script showing all the implied attributes:
<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>These instances can also be removed from their respective servers:
<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.
- Enterprise application (EAR file)
- Web application (WAR file)
- Enterprise Java Bean (EJB-JAR file)
- Enterprise connector (RAR file)
- Application client
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.
   sun-appserv-component subelements
Element
Description
A Sun ONE Application Server instance.
A component to be deployed.
A set of component files that match specified parameters.
Attributes
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.
Examples
Here is a simple example of disabling a component:
<sun-appserv-component
action="disable"
name="simpleapp"
password="${password}" />Here is a simple example of enabling a component:
<sun-appserv-component
action="enable"
name="simpleapp"
password="${password}" />Here is an equivalent script showing all the implied attributes:
<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.
   sun-appserv-admin subelements
Element
Description
A Sun ONE Application Server instance.
Attributes
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-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
none
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.
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
none
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>These instances can also be removed from their respective servers:
<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:
<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>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.
<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>You can enable or disable components on multiple servers. This example shows the same three components being enabled on two different instances. Both servers use the same password.
<sun-appserv-component action="enable" 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>component
Specifies a J2EE component. Allows a single task to act on multiple components. The component attributes override corresponding attributes in the parent task; therefore, the parent task attributes function as default values.
Subelements
none
Attributes
The following table describes attributes for the component element. 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.
<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 to multiple servers. This example shows the same three components being removed from two different instances. Both servers use the same password.
<sun-appserv-undeploy 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>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).
<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>You can enable or disable multiple components on multiple servers. This example shows the same three components being enabled on two different instances. Both servers use the same password.
<sun-appserv-component action="enable" 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>fileset
Selects component files that match specified parameters. When fileset is included as a subelement, the name and contextroot attributes of the containing element must use their default values for each file in the fileset. For more information, see:
http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html
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.
This section covers the following topics:
- The sun-application_1_3-0.dtd File
- Elements in the sun-application.xml File
- Sample Application XML 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.
Note Do not edit the sun-application_1_3-0.dtd file; its contents change only with new versions of Sun ONE Application Server.
For general information about DTD files and XML, see the XML specification at:
Each element defined in a DTD file (which may be present in the corresponding XML file) can contain the following:
Subelements
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.
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:
<!ELEMENT element-name (#PCDATA)>
For example:
<!ELEMENT role-name (#PCDATA)>
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:
<role-name>manager</role-name>
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
This section describes the following elements in the sun-application.xml file:
- sun-application
- web
- web-uri
- context-root
- pass-by-reference
- unique-id
- security-role-mapping
- role-name
- principal-name
- group-name
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.
web
Specifies the application's web tier configuration.
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 subelements
Element
Required
Description
only one
Contains the web URI for the application.
only one
Contains the web context root for the application.
web-uri
Contains the web URI for the application. Must match the corresponding element in the application.xml file.
Subelements
none
context-root
Contains the web context root for the application. Overrides the corresponding element in the application.xml file.
Subelements
none
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
none
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
none
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
none
principal-name
Contains the principal (user) name.
Subelements
none
group-name
Contains the group name.
Subelements
none
Sample Application XML Files
This section includes the following:
Sample application.xml File
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN' 'http://java.sun.com/dtd/application_1_3.dtd'>
<application>
<display-name>app_stateless-simple</display-name>
<description>Application description</description>
<module>
<ejb>stateless-simpleEjb.jar</ejb>
</module>
<module>
<web>
<web-uri>stateless-simple.war</web-uri>
<context-root>helloworld</context-root>
</web>
</module>
</application>
Sample sun-application.xml File
<?xml version="1.0" encoding="UTF-8"?>
<!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'>
<sun-application>
<unique-id>67488732739338240</unique-id>
</sun-application>