Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer's Guide

- Previous: Overview of Assembly and Deployment
- Next: Deploying Modules and Applications

# Assembling Modules and Applications

Assembling (or packaging) modules and applications in Application Server conforms to all of the customary J2EE-defined specifications. The only difference is that when you assemble in Application Server, you include Application Server specific deployment descriptors that enhance the functionality of the Application Server.

For example, when you assemble an EJB JAR module, you must create two deployment descriptor files with these names: `ejb-jar.xml` and `sun-ejb-jar.xml` (both required). If the EJB component is an entity bean with container-managed persistence, you can also create a `.dbschema` file and a `sun-cmp-mapping.xml` file, but these are not required. For more information about `sun-ejb-jar.xml` and `sun-cmp-mapping.xml`, see Appendix A, Deployment Descriptor Files.

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.

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

- deploytool

- Apache Ant

- The Deployment Descriptor Verifier

## deploytool

You can use the deploytool, provided with the Application Server, to assemble J2EE applications and modules, configure deployment parameters, perform simple static checks, and deploy the final result. For more information about using the deploytool, see the J2EE 1.4 Tutorial at `http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html`.

## Apache Ant

Ant can help you assemble and deploy modules and applications. For details, see asant Assembly and Deployment Tool.

## The Deployment Descriptor Verifier

The verifier tool validates both J2EE and Application Server specific deployment descriptors against their corresponding DTD files and gives errors and warnings if a module or application is not J2EE and Application Server compliant. You can verify deployment descriptors in EAR, WAR, RAR, and JAR files.

The verifier tool is not simply an XML syntax verifier. Rules and interdependencies between various elements in the deployment descriptors are verified. Where needed, user application classes are introspected to apply validation rules.

The verifier is integrated into Application Server deployment, the deploytool, and the sun-appserv-deploy Ant task. You can also run it as a stand-alone utility from the command line. The verifier is located in the install-dir`/bin` directory.

When you run the verifier during Application Server deployment, the output of the verifier is written to the tempdir`/verifier-results/` directory, where tempdir is the temporary directory defined in the operating system. Deployment fails if any failures are reported during the verification process. The verifier also logs information about verification progress to the standard output.

For details on all the assertions tested by the verifier, see the assertions documentation provided at `http://java.sun.com/j2ee/avk/index.html`.

Tip –

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

This section covers the following topics:

- Command Line Syntax

- Ant Integration

- Sample Results Files

### Command Line Syntax

The verifier tool’s syntax is as follows:

    verifier [options] file

The file can be an EAR, WAR, RAR, or JAR file.

The following table shows the options for the `verifier` tool.

Table 3–4 Verifier Options

Short Form | Long Form | Description
--- | --- | ---
`-v` | `--verbose` | Turns on verbose mode.
`-d` output-dir | `--destdir` | Writes test results to the output-dir, which must already exist. By default, the results files are created in the current directory.
`-r` level | `--reportlevel` level | Sets the output report level to one of the following values: `a` or `all` - Reports all results. This is the default in both verbose and non verbose modes. `w` or `warnings` - Reports only warning and failure results. `f` or `failures` - Reports only failure results.
`-n` | `--notimestamp` | Does not append the timestamp to the output file name.
`-?` | `--help` | Displays help for the verifier command. If you use this option, you do not need to specify an EAR, WAR, RAR, or JAR file.
`-V` | `--version` | Displays the verifier tool version. If you use this option, you do not need to specify an EAR, WAR, RAR, or JAR file.
`-u` | `--gui` | Opens a graphical interface for performing verification. If you use this option, you do not need to specify an EAR, WAR, RAR, or JAR file. For more information, see the verifier online help.

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 -r a -d ResultsDir ejb.jar

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

If the verifier runs successfully, a result code of `0` is returned. This does not mean that no verification errors occurred. A nonzero 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 Table 3–4.

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

    ...

- Previous: Overview of Assembly and Deployment
- Next: Deploying Modules and Applications

- © 2010, Oracle Corporation and/or its affiliates