Java[tm] Application Verification Kit (AVK) for the Enterprise 1.4.2 User's Guide

Java AVK for the Enterprise Tools

You will use the following tools to verify your application suite:

• The Application Server asant tool, which you use to run the static archive tests and to translate deployment descriptors
• The Application Server deployment tool, which you run with the <JAVKE_HOME>/appserver/bin/deploytool command
• The Java AVK for the Enterprise reporting tool, which you run with the <JAVKE_HOME>/bin/reporttool command

Verifying an Application Suite

This section describes the steps to verify an application suite using the Java AVK for the Enterprise.

Here is an overview of these steps:

1. Add the Java AVK for the Enterprise Ant tasks to the build.xml file(s) for your application suite.
2. Perform static verification tests on each module.
3. Start the instrumented Application Server.
4. Create resources for the application suite.
5. Specify runtime information for each module.
6. Deploy the application suite on the instrumented Application Server.
7. Create an exclude list for component libraries, if your application suite uses them.
8. Execute the application suite and use its functionality in a way that exercises 80% of its EJB methods and accesses 100% of its JSP pages and servlets.
9. Stop the instrumented J2EE server.
10. Run the reporting tool to produce verification results.
11. Interpret the results produced by the reporting tool.

The following sections describe these steps in detail.

Adding the Ant Tasks to your Build File

You will find a sample build.xml file containing the Java AVK for the Enterprise Ant tasks in the following directory:

<JAVKE_HOME>/samples

This file also contains some sample Ant targets that you can run in order to become familiar with the tasks before you adapt them for your own code. The code for running the targets is also in the samples directory.

You can either add the necessary code to the build.xml file for your application, or you can create a separate targets file (javke_targets.xml, for example) and include it in the application build.xml file:

<!DOCTYPE project [
  <!ENTITY javke_targets SYSTEM "./javke_targets.xml">
]>
 ...
&javke_targets;

The tasks you can use are defined as follows in the sample build.xml file:

<taskdef name="ArchiveTest"
classname="org.apache.tools.ant.taskdefs.optional.sun.verification.StaticArchive
Test" 
classpath="${cpath}" />

<taskdef name="TranslateRuntimeDD" 
classname="org.apache.tools.ant.taskdefs.optional.sun.verification.TranslateRuntimeDD" 
classpath="${cpath}"/>

You must define the classpath to include the following:

<property name="cpath" value="${avk.home}/lib/javke-ant.jar"/>

You must also define a property named avk.home whose value is the directory where the Java AVK for the Enterprise is installed. The samples directory has a build.properties file that defines this property; you can add the property to your own build.properties file or define the property explicitly.

The file in the samples directory contains sample targets that use the tasks:

• The static-archive-test target uses the ArchiveTest task to validate an archive file against the J2EE specifications.
• The translate-dd target uses the TranslateRuntimeDD task to convert runtime deployment descriptors from other application servers into Application Server deployment descriptors.

You do not have to have the Application Server running in order to use these tasks.

The following sections provide details about using the tasks.

Note: The SourceScan task, which scans source code for proprietary APIs, is still available but is obsolete. The ArchiveTest task has been enhanced to detect proprietary APIs. You can continue to use the SourceScan task at this release if you do not wish to modify your build files at this time. However, the task will be removed from a future release of the Java AVK for the Enterprise.

Performing Static Verification Tests

The tasks that perform the static verification tests do the following:

• Perform static archive testing on each component to determine compatibility with the J2EE specifications
• Convert runtime deployment descriptors from other application servers into Application Server deployment descriptors

Static Archive Testing

Use the ArchiveTest task to ensure that your application modules comply with the J2EE specifications. This task identifies and reports problems with the module file components' method signatures and other static inconsistencies. It looks at all components of the file and reports any inconsistencies with the API and deployment descriptors defined in the J2EE specifications. It also validates the packaging and structure of the modules. For example, the following target in the sample build.xml file scans the WAR file bookstore.war:

<target name="static-archive-test" description="static archive tests for 
application containing web components, reporting on all tests">
  <ArchiveTest appName="${avk.home}/samples/bookstore/bookstore.war"
               reportingOpts="a" />
</target>

The appName attribute is required. The value can be the path name of an EAR, JAR, WAR, or RAR file. If you use the task without defining any other attributes, it scans all modules in the archive and reports all failures and warnings. At the end, it provides the path names where you can find the results:

>asant static-archive-test
Buildfile: build.xml

static-archive-test:
     [exec] Dec 12, 2005 6:16:46 PM APIRepository Initialize
     [exec] INFO: C:\Sun\AppServer\lib\verifier\standard-apis.xml
     [exec] Dec 12, 2005 6:16:47 PM com.sun.enterprise.tools.verifier.BaseVerifier preVerification
     [exec] INFO: Verifying: [ bookstore ]
     [exec] Dec 12, 2005 6:16:47 PM com.sun.enterprise.tools.verifier.apiscan.packaging.Archive listAllExtDirs
     [exec] INFO: Extension Dir Path is C:\jdk1.5.0_05\jre\lib\ext;C:\Sun\AppServer\domains\domain1\lib\ext
     [exec] Dec 12, 2005 6:16:47 PM com.sun.enterprise.tools.verifier.web.WebVerifier getClassPath
     [exec] INFO: Using CLASSPATH C:\Documents and Settings\me\Local Settings\Temp\exploded20051212061646\
bookstore\WEB-INF\classes\;C:\DOCUME~1\me\LOCALS~1\Temp\.vc0.0327003
     [exec] Dec 12, 2005 6:16:47 PM com.sun.enterprise.tools.verifier.tests.web.AllJSPsMustBeCompilable compile
     [exec] INFO: Starting to compile JSPs with archiveUri C:\DOCUME~1\me\LOCALS~1\Temp\exploded20051212061646\bookstore
     [exec] Dec 12, 2005 6:16:47 PM com.sun.enterprise.tools.verifier.tests.web.AllJSPsMustBeCompilable compile
     [exec] INFO: JSPC classpath C:\Documents and Settings\me\Local Settings\Temp\exploded20051212061646\
bookstore\WEB-INF\classes\;C:\DOCUME~1\me\LOCALS~1\Temp\.vc0.0327003;C:\Sun\AppServer\lib\j2ee.jar;C:\Sun\
AppServer\lib\jaxrpc-api.jar;C:\Sun\AppServer\lib\jaxr-api.jar;C:\Sun\AppServer\lib\saaj-api.jar;C:\Sun\AppServer\
lib\mail.jar;
     [exec] Dec 12, 2005 6:16:48 PM com.sun.enterprise.tools.verifier.ReportHandler writeToConsole
     [exec] INFO:
     [exec] # of Failures : 0
     [exec] # of Warnings : 0
     [exec] # of Errors   : 0
     [exec] Dec 12, 2005 6:16:48 PM com.sun.enterprise.tools.verifier.ReportHandler writeToConsole
     [exec] INFO: Look in file "C:\Sun\javke1.4.2\reporttool\static\bookstore.war.txt" for detailed results.
     [echo] See "C:\Sun\javke1.4.2\reporttool\static\verifierSummary.html" for results.

BUILD SUCCESSFUL

You can use the attributes listed in Table 3 to change the reports.

For example, you could specify the following to generate reports showing only failures, on only the application client and enterprise bean components of an EAR file:

<target name="archive-test" description="static archive tests">
  <ArchiveTest appName="./MyApp.ear" 
               reportingOpts="f" 
               partitionOpts="appclient,ejb" />
</target>

The summary page from the static archive tests shows the failures, warnings, passes and nonapplicable test results for each of the modules of the J2EE platform contained in the application. Each result contains a link to detailed information, including a description of the test that was run, the assertion in the specification being tested, and the name of the test. In addition, the summary includes a section that lists any errors the static archive tests encountered.

If your code contains proprietary APIs, you will need to provide portable, functionally equivalent alternative code that can be executed instead of the proprietary APIs. You will need to rebuild your application using the alternative code in order to verify it.

Note: For a few static archive tests, execution of the tests stops after the first failed test. Once you have corrected a failure, run the static archive test task again in order to find and correct further failures.

Translating Runtime Deployment Descriptors

Every application server has its own runtime deployment descriptors that specify implementation-specific aspects of deployment. An application that previously ran on another J2EE server must convert its runtime deployment descriptors to work with the Application Server. This process does not replace your original module or application; instead, it creates a new one with new deployment descriptors.

Use the TranslateRuntimeDD task to generate the deployment descriptors. For example, the following target in the sample build.xml file converts the deployment descriptors for the EAR file HelloWorld.ear from WebLogic 6 to the Application Server:

<target name="translate-dd" description="translate runtime DD for 
deployment">
  <TranslateRuntimeDD 
archiveName="${avk.home}/samples/weblogic_6_x/HelloWorld/HelloWorld.ear"
                      srcServer="weblogic6" />

Both the archiveName and the srcServer attributes are required. The srcServer attribute specifies the server that was used to generate the application. It can have any one of the following values:

If you run the translate-dd target, it generates the following output:

>asant translate-dd
Buildfile: build.xml

translate-dd:
     [echo] Some xml files may not have translated correctly.
     [java]       [war] Warning: selected war files include a WEB-INF/web.xml 
which will be ignored (please use webxml attribute to war task)
     [java]       [ear] Warning: selected ear files include a 
META-INF/application.xml which will be ignored (please use appxml attribute to 
ear task)

     [java] BUILD SUCCESSFUL
     [java] Total time: 3 seconds
     [echo] See "C:\Sun\javke1.4.2\reporttool\translate\translationSummary.html" 
for results.
     [echo] We attempted to create an ear file even if minor errors occurred. 
The application with translated deployment descriptors is in a new .ear file 
located in C:\Sun\javke1.4.2\reporttool\translate\Input_Archives\asmtbuild 

BUILD SUCCESSFUL

Do not use the new EAR file created by the task. Instead, open the translationSummary.html file in a web browser. This file shows the locations of the new runtime descriptors, which begin with the prefix sun-. Add these descriptors to your original application.

Note: The task also generates new standard descriptors (application.xml, ejb-jar.xml, web.xml); do not add these to your application.

Starting the Instrumented Application Server

After you perform static archive testing, start the Application Server with instrumentation turned on. The installation process for the Java AVK for the Enterprise modifies the server configuration files to enable instrumentation. As a result, when you start the server, instrumentation is enabled.

To start the server, use the following command:

Use the --verbose option to display the server log output:

asadmin start-domain --verbose domain1

For database access, you can use the Derby database that is part of the Application Server. It has a preconfigured Java Database Connectivity (JDBC^TM) resource and connection pool. See the Sun Java System Application Server Platform Edition 8.2 Developer's Guide for details on using the JDBC API for database access.

If your application uses a database, start the database now. Use the following command:

asadmin start-database

Creating Resources for the Application Suite

If your application uses server resources, you create them administratively. For example, you can use the Admin Console or the asadmin command to create JDBC resources, Java Message Service (JMS) resources and destinations, connector resources, users and groups for security realms, and the like.

To use the Admin Console, open the URL http://localhost:4848/ in a browser. Enter your administrative username and password (created when you installed the Application Server).

You can use the Admin Console help system, the asadmin help command, and the J2EE 1.4 Tutorial to learn more.

Specifying Runtime Information

Before you deploy your application, you should open each module in the Application Server deployment tool and verify that the runtime information required by the Application Server is correct. Much of this information consists of the Java Naming and Directory Interface^TM (JNDI) API names of any resources used by the application. To do this, perform the following steps:

1. Start the deployment tool with no arguments:

UNIX:	<JAVKE_HOME>/appserver/bin/deploytool
Windows:	<JAVKE_HOME>\appserver\bin\deploytool

2. Choose Open from the File menu to open each module in your application suite in the deploytool.
3. Expand each module in turn. For each module, look at the Sun-specific Settings. Start with the module as a whole. The Sun-specific Settings dialog has several panes you can view. Work your way down through the JAR and WAR files to the individual component level. Fill in or correct any values your application needs.
4. Choose Save from the File menu to save each module.

Specific places where you need to set runtime information include the following tabs in the right-hand pane of the deploytool:

• EJB Refs tab: Specify the JNDI name if the enterprise bean uses a remote interface.
• Resource Refs tab: Specify the JNDI name for each resource.
• Message Destinations tab -- Specify the JNDI name of the target destination resource. You may also need to specify the physical destination name.
• Resource Env Refs tab -- Specify the JNDI name of the target destination resource.
• Web Services tab -- specify the WSDL publish location.
• Entity tab (for an entity bean) -- see Generating Database Tables for Entity Beans.
• Message-Driven tab (for a message-driven bean) -- Specify the JNDI name of the associated connection factory for the message-driven bean.

Generating Database Tables for Entity Beans

For each entity bean in your application suite, you need to generate database tables. You may use the Derby database that comes with the Application Server. It has a preconfigured JDBC connection pool called DerbyPool and a preconfigured JDBC resource called jdbc/__default. You can use this resource or create your own administratively with the Admin Console.

If you have a database that needs to be prepopulated with data, the simplest way to this is to create an asant task. The task and the property and path settings it uses would look like this:

  <property name="db.delimiter"  value=";" />
  <property name="db.root"  value="${j2ee.home}/derby" />
  <property name="db.driver"  value="org.apache.derby.jdbc.ClientDriver" />
  <property name="db.datasource"  value="org.apache.derby.jdbc.ClientDataSource" />
  <property name="db.host"  value="localhost" />
  <property name="db.port"  value="1527" />
  <property name="db.sid"  value="sun-appserv-samples" />
  <property name="db.url"  
value="jdbc:derby://${db.host}:${db.port}/${db.sid};create=true;" />
  <property name="db.user"  value="APP" />
  <property name="db.pwd"  value="APP" />
  <property name="db.jvmargs"  value="-ms16m -mx32m" />
  <property name="sql.script"  value="YOUR SCRIPT PATH NAME HERE" />
  
  <path id="db.classpath">
    <fileset dir="${db.root}/lib">
      <include name="*.jar"/>
    </fileset>
  </path>

  <target name="create-db" depends="init"
     description="Create database tables and populate database." >

     <sql driver="${db.driver}"
          url="${db.url}"
          userid="${db.user}"
          password="${db.password}"
          classpathref="db.classpath"
          delimiter="${db.delimiter}"
          autocommit="false"
          onerror="abort" >
          
  </target>

You need to specify the SQL script that will create the database and modify the properties as needed.

If your entity bean uses container-managed persistence, you can specify the resource in the deploytool and create tables as follows:

1. In the tree view, select the node for the entity bean.
2. Click the Entity tab, then click CMP Database (Sun-specific).
3. In the JNDI Name field of the dialog box, type the name of the JDBC resource, either the preconfigured one (jdbc/__default) or the one you created (jdbc/resource_name). For all other settings, the bean will use the default values.
4. Click Create Database Mappings.
5. In the dialog box, verify that Automatically Generate Necessary Tables is selected. Select the Datasource Vendor (Derby), then click OK.
6. Click Table Generation Settings.
7. Verify that Create Tables on Deploy and Delete Tables on Undeploy are both checked, then click OK.
8. Click Close.
9. Choose Save from the File menu to save the modified application.

For more information on using container-managed persistence for entity beans, see the Sun Java System Application Server Platform Edition 8.2 Developer's Guide.

Deploying the Application Suite

Next, deploy the application suite on the instrumented Application Server. In the deploytool, select each application or module and choose Tools->Deploy.

If you are new to the Application Server, you can learn how to create, package, and deploy an application by following the instructions in the Getting Started chapter of the J2EE 1.4 Tutorial.

Creating an Exclude List for Component Libraries

The Java AVK for the Enterprise reporting tool by default processes all deployed EAR files and standalone modules, assuming that they are part of the same application suite. Normally, you should undeploy any modules that are not part of the application suite that you are verifying.

Often, however, an application suite includes component libraries that are used by the application but are not part of it. Such libraries generally come from another vendor and have already been verified. You can configure the Java AVK for the Enterprise to exclude these libraries, or modules within them, from the runtime verification process.

For example, suppose that vendor Wombat has developed an application named WombatApp that it wants to verify. WombatApp depends on another application, KangarooApp (a component library) in order to be functional. KangarooApp is supplied by vendor Kangaroo, which has already verified it. Vendor Wombat wants to verify only WombatApp and not KangarooApp.

To exclude some or all of an application from verification, you edit the file <JAVKE_HOME>/config/appVerification/AppExcludeList.xml to indicate which application or component of the application must be excluded.

Suppose that WombatApp.ear contains the following modules:

ejb1.jar 
ejb2.jar 
web1.war 
web2.war

And suppose that KangarooApp.ear contains the following modules:

ejb3.jar 
ejb4.jar 
web3.war 
web4.war

To exclude all of KangarooApp from the verification process, you would specify the following:

<exclude-list>
     <j2ee-app>
         <name>KangarooApp</name>
     </j2ee-app>
</exclude-list>

To exclude only two components of KangarooApp, ejb3.jar and web4.war, you would specify the following:

<exclude-list>
     <j2ee-app>
         <name>KangarooApp</name>
         <ejb-bundle>
             <name>ejb3.jar</name>
         </ejb-bundle>
         <web-bundle>
             <name>web4.war</name>
         </web-bundle>
     </j2ee-app>
</exclude-list>

You use the j2ee-app element to specify an application EAR file. Use the ejb-app or web-app tag to specify a standalone EJB JAR file or web WAR file. For example:

    <ejb-app>
        <name>EjbModule</name>
    </ejb-app>
    <web-app>
        <name>WebModule</name>
    </web-app>

For more details, you can find the DTD for for AppExcludeList.xml in the file <JAVKE_HOME>/dtds/application-verification-app-exclude_1_4.dtd.

When you make entries in the AppExcludeList.xml file, do not provide a file extension for standalone module names (EAR files, EJB JAR files, or WAR files). For example, you would not provide a .ear extension for KangarooApp. (This instruction assumes that you observe the convention that the root name of the file is the name of the module. If the names are not the same, use the module name, not the root name of the file.)

Provide a .jar or .war file extension for an EJB JAR or web WAR file contained within an application.

After you edit AppExcludeList.xml, you can perform runtime verification on your application. The applications and components specified in the file will not be included in the verification reports.

The file AppExcludeList.xml contains some fictitious entries that illustrate how to use it. You can leave these entries in the file, remove them, or comment them out.

Executing the Application Suite

After you deploy the application suite, you must run it so as to invoke as much of its functionality as possible. In this step, you either manually or automatically invoke the JSP pages, servlets, and public EJB methods.

Stopping the Instrumented J2EE Server

When you have finished the execution step, stop the server using the following command:

Do not undeploy the application.

This command does several things as the server shuts down. First, it writes all data collected during the test execution of the application suite to disk. In addition, the server performs introspection on the deployed application suite and generates the list of J2EE public APIs (including EJB methods and web components).

Running the Reporting Tool

To use the reporting tool to produce results after the run, use the following command:

<JAVKE_HOME>/bin/reporttool -result

This command generates HTML pages describing all relevant information found during the testing and server shutdown processes.

The HTML pages are generated in the reporttool directory with the top-level page <JAVKE_HOME>/reporttool/results/suiteSummary.html. The results generated by the reporting tool are described in Interpreting the Results.

To remove the results and reports generated by the instrumentation code from the <JAVKE_HOME>/reporttool/results directory, run the reporting tool with the -clear_results option:

<JAVKE_HOME>/bin/reporttool -clear_results

Use this option if an exception was thrown during dynamic checking and you have fixed the problem. In order to remove the exception from the results, you must clear all the results.

Interpreting the Results

The Java AVK for the Enterprise reporting tool compares introspection and instrumentation results and produces reports from that comparison. From the comparison of the results, the reporting tool generates a set of HTML files and displays the URL of the top-level summary report.

The reporting tool provides a status of Pass or Fail when summarizing the results. These numbers are based on the criteria mentioned in Coverage.

The summary page of the generated reports contains pointers to the results of the static archive tests, a summary of the EJB method coverage for each module, and a summary of the web component coverage.

The two kinds of coverage reports are described in the following sections:

• EJB method coverage reports
• Web component coverage reports

EJB Method Coverage Reports

EJB method coverage is reported by EAR file or module. The guideline is that at least 80% of the EJB methods within each module must be covered.

The EJB Method Coverage page expands the EAR file or module contents and lists the JAR files and beans in each file, with the coverage. The Methods Called column shows the number of methods called versus the total number of methods for each bean. Clicking on the bean name brings up the EJB Method Coverage Detail page, which displays the status of each method within that bean. The first table contains the methods that were not called successfully. Either those methods were not called at all, or an exception was thrown during the call. The next table shows all methods that were called successfully. This information can be used to determine which methods need to be invoked to increase the coverage to meet the guidelines if the guidelines were not met.

Web Component Coverage Reports

Web component coverage is reported by context. The guideline is that 100% of the JSP pages and servlets must be called with no exceptions generated.

The table on the summary page reports the percentage of the web components that were called. Clicking on either Passed or Failed brings up the Web Component Coverage page, which lists each component by the context root, whether or not it was called, and if so, whether there was an exception. This information can be used to determine which web components must be called to increase the coverage to meet the guidelines.

The coverage reports do not list JSP pages that are included by other JSP pages using an include directive. Instead, the reports list only the JSP pages that contain the include directives for these pages. JSP pages included with an include action, however, are listed in the coverage reports.

How the Tools Produce Results

This section describes how the tools collect dynamic data and generate metrics using two primary mechanisms: introspection and instrumentation. It covers the following topics:

• Introspection
• Instrumentation
• Additional notes

Introspection

The introspection process generates the list of required EJB methods to be invoked. The list contains all public methods in the bean's remote and local interfaces, the onMessage method for message-driven beans, and all create methods for session and entity beans. It excludes the methods that are on the Exclude List (the file <JAVKE_HOME>/config/appVerification/ExcludeList.xml, not to be confused with AppExcludeList.xml). A list of excluded methods is provided as input to the introspection process, and in addition, other methods are excluded when the tool is dynamically generating the final required list. For example, all CMP and CMR fields supporting set and get methods are excluded from the final list, and all remove methods, finder methods, and the create methods for message-driven beans are excluded as well.

The list of required web components contains all servlets and JSP pages that have entries in the web.xml file and all files ending with .jsp.

This combination of the EJB and web component lists is the master list that determines which EJB methods and web components must be called. This information is used in calculating the percentage numbers.

Instrumentation

The instrumented Application Server has been modified to log all invocations during execution. For EJB components, that means all invocations of public business methods, of the ejbCreate method for session and entity beans, and of the ejbRemove method. In addition, the server records any system exceptions that were thrown while a method was executed. Each web component that is invoked is also recorded. The combination of these two lists is the total list of invoked entities. This total list is used when comparing against what was generated from introspection.

Additional Notes

Each time the reporting tool runs, it compares the instrumentation and introspection results and produces the results.

You may start the server again and call additional J2EE public API methods. Instrumentation results from this run will be merged with existing instrumentation results.

Introspection is run each time the Application Server is shut down. This increases the time required to shut down the server.

Obtaining Support for the Java AVK for the Enterprise

Technical support from Sun is available. For details, go to the Java AVK for the Enterprise web page:

http://java.sun.com/j2ee/verified/avk_enterprise.html

Further Information

For more information about the Java programming language, the J2EE platform, and portability, refer to the following:

• The Java Tutorial:

  http://java.sun.com/docs/books/tutorial/

• The J2EE 1.4 Tutorial:

  http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html

• Sun Java System Application Server Platform Edition 8.2:

  http://wwws.sun.com/software/products/appsrvr_pe/index.html

• Sun Java System Application Server Platform Edition 8.2 Administration Guide:

  http://docs.sun.com/app/docs/doc/819-4712

• Sun Java System Application Server Platform Edition 8.2 Developer's Guide:

  http://docs.sun.com/app/docs/doc/819-4721

• The J2EE 1.4 documentation page, containing links to API documentation, specifications, and other documentation:

  http://java.sun.com/j2ee/1.4/docs/

• The Java BluePrints page:

  http://java.sun.com/blueprints/

• "Build to Spec!", an old but still useful two-part article about portability:

  http://developer.java.sun.com/developer/technicalArticles/J2EE/bu ild/index.html
  http://developer.java.sun.com/developer/technicalArticles/J2EE/bu ild/build2.html