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

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

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

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.

...