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

Java AVK for the Enterprise Tools

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

• The Application Server ant tool, which you use to run the static archive tests and to translate deployment descriptors
• The Java AVK for the Enterprise report command (<JAVKE_HOME>/bin/report)

Verifying an Application Suite

This section describes the steps to verify an application suite using 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 Application Server if it is not already running.
4. (Optional) Create resources for the application suite, if necessary.
5. (Optional) Specify runtime information for each module, if necessary.
6. Deploy the application suite on the Application Server.
7. Start a dynamic verification session.
8. Execute the application suite and use its functionality in a way that exercises at least 80% of its EJB methods and accesses 100% of its JSP pages and servlets.
9. Run the reporting tool to generate one or more snapshot reports.
10. Interpret the results.
11. End the dynamic verification session.
12. (Optional) Stop the Application Server.

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:

  <import file="./javke_targets.xml" />

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

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 Java EE 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 Java EE 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 Java EE 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:

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

static-archive-test:
     [exec]  INFO: Verifying: [ bookstore ]
     [exec]  INFO: Compiling JSPs in [ bookstore ]
     [exec]  INFO: 
     [exec] # of Failures : 0
     [exec] # of Warnings : 0
     [exec] # of Errors   : 0
     [exec]  INFO: Look in file "/opt/sun/javke5/reporttool/static/bookstore.war.txt" for detailed results.
     [echo] See "/opt/sun/javke5/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 Java EE 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 Java EE 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 output similar to the following:

>ant translate-dd
Buildfile: build.xml

translate-dd:

     [java] Extracting archives :-
     [java] -------------------


     [java] Extracting: HelloWorld.ear
     [java] xx

     [java] Extracting: helloworld.war
     [java] x

     [java] Extracting: HelloWorldEJB.jar
     [java] x

     [java] Clean up...

     [java] Pre-processing input :-
     [java] -------------------
     [java] ||||||||||||||



     [java] Migration Status :-
     [java] ----------------

     [java] |||||||||||||||||||



     [java] ---------------------- Output SUMMARY ------------------------

     [java] Java:

     [java] Total files processed :             -               0
     [java] Succeded :                  -               0
     [java] Failed :                    -               0
     [java] Partially Processed :               -               0
     [java] Unchanged :                 -               0

     [java] JSP:

     [java] Total files processed :             -               1
     [java] Succeded :                  -               0
     [java] Failed :                    -               0
     [java] Partially Processed :               -               0
     [java] Unchanged :                 -               1

     [java] XML:

     [java] Total files processed :             -               4
     [java] Succeded :                  -               1
     [java] Failed :                    -               0
     [java] Partially Processed :               -               0
     [java] Unchanged :                 -               3

     [java] HTML:

     [java] Total files processed :             -               1
     [java] Succeded :                  -               0
     [java] Failed :                    -               0
     [java] Partially Processed :               -               0
     [java] Unchanged :                 -               1

     [java] Configuration:

     [java] Total files processed :             -               0
     [java] Succeded :                  -               0
     [java] Failed :                    -               0
     [java] Partially Processed :               -               0
     [java] Unchanged :                 -               0


     [java] ---------------------  End of SUMMARY ------------------------



     [echo] See "C:\Sun\javke5\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\javke5\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 Application Server

After you perform static archive testing, start the Application Server.

To start the server's default domain, use the following command:

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

asadmin start-domain --verbose

For database access, you can use the Java DB database that is part of the Application Server. It has a preconfigured Java Database Connectivity (JDBC) resource and connection pool. See the Sun Java System Application Server Platform Edition 9 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. 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 following URL in a browser:

http://localhost:4848/

You can use the Admin Console help system, the asadmin help command, and the Java EE 5 Tutorial to learn more.

Specifying Runtime Information

Before you deploy your application, you should verify that any runtime information required by the Application Server is correct. Much of this information consists of the Java Naming and Directory Interface (JNDI) API names of any resources used by the application.

A Java EE 5 application commonly uses source file annotations to specify resource injection for components. An application from a previous version of Java EE uses runtime deployment descriptors.

In addition, you may need to create database tables for your persistence units or entity beans. For information on doing this, and for details on using the Java Persistence API in the Application Server, see the Sun Java System Application Server Platform Edition 9 Developer's Guide. Some examples in the Java EE 5 Tutorial also show how to create database tables.

Deploying the Application Suite

Next, deploy the application suite on the Application Server. Use the asadmin deploy command or the Admin Console.

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 Java EE 5 Tutorial.

Starting a Dynamic Verification Session

To start a dynamic verification session, use the following command:

This command starts a verification session for the specified applications. First it creates a file named avk.properties in your home directory, if the file does not exist already. In addition, it performs introspection on the deployed application suite and generates the list of Java EE public APIs (including EJB methods and web components). If you do not specify any arguments, all deployed applications except those that are part of the Application Server will be verified.

Dynamic verification uses the call-flow tracing capability of the Application Server.

After you run the startverification command for the first time, perform these steps:

1. Open the file $HOME/avk.properties in a text editor.
2. Add a property named BROWSER and specify the path name of your preferred web browser. For example:

   BROWSER=C:/Program Files/Mozilla Firefox/firefox.exe
   

3. Save and close the file.

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.

Using the report Command

As you execute the application suite, you can use the Java AVK for the Enterprise report command to generate reports that show how much of the application has been exercised.

The report command writes the data collected during the execution of the application suite to disk.

Use the report command as follows:

The command generates HTML pages describing all relevant information found during the testing process. The HTML pages are generated in the following directory:

<AS_HOME>/domains/domain1/logs/reporttool/<timestamp_dir>/results

The name of the <timestamp_dir> indicates the time at which the startverification command was run (for example, 2006-05-02-13-22).

The top-level page of the report is named suiteSummary.html. The report command opens the page in the browser specified in your avk.properties file. If you do not specify the BROWSER property, it looks for the Firefox browser in a default location that is probably incorrect.

The results generated by the command are described in Interpreting 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.

Note: At this release, the link to the results of the static archive tests is always incorrect, reporting that static archive tests were not run.

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.

Ending the Dynamic Verification Session

When you have finished generating reports, end the dynamic verification session. Use the following command:

This command produces a final coverage report and then turns off the the Application Server settings that enable dynamic verification.

Stopping the Application Server

You can leave the Application Server running. If you want to stop the server, use the following command:

Stopping the Application Server also ends the dynamic verification session, if you did not previously end the session.

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

Java AVK for the Enterprise logs all invocations during execution. For EJB components, that means all invocations of public business methods, of the ejbCreate method for stateful session beans and entity beans, and of the ejbRemove method. In addition, Java AVK for the Enterprise 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 report command runs, it compares the instrumentation and introspection results and produces the results. Snapshots from each run will be merged with existing reports.

Obtaining Support for 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 Java EE platform, and portability, refer to the following:

• The Java Tutorial:

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

• The Java EE 5 Tutorial:

  http://java.sun.com/javaee/5/docs/tutorial/doc/index.html

• Sun Java System Application Server Platform Edition 9:

  http://java.sun.com/javaee/downloads/index.jsp

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

  http://docs.sun.com/doc/819-3658

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

  http://docs.sun.com/doc/819-3659

• The Java EE 5 documentation page, containing links to API documentation, specifications, and other documentation:

  http://java.sun.com/javaee/reference/index.jsp

• The Java BluePrints page:

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

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

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