Adding CommonApps Templates

Note

This has been completed.

Related to issue https://github.com/jakartaee/platform-tck/issues/1409, we need to add the Arquillian deployment method code for the applications referenced in the platform-tck/common/src/main/java/com/sun/ts/lib/harness/commonarchives.properties to the jakartaee-tck-tools CommonApps.stg. This page is a HOWTO on doing that.

First, the format of the commonarchives.properties entries is:

commonarchives.test_pkg_path=commonarchive_app_path

so, for example, this entry:

commonarchives.com/sun/ts/tests/ejb/ee/tx/session=com/sun/ts/tests/ejb/ee/tx/txbean

The test_pkg_path is "com/sun/ts/tests/ejb/ee/tx/session" and the commonarchive_app_path is "com/sun/ts/tests/ejb/ee/tx/txbean".

To map the commonarchive_app_path to a location in the platform-tck repository, use the 5th part as the module name. For the commonarchive_app_path of "com/sun/ts/tests/ejb/ee/tx/txbean", the module name is "ejb", and the files for this common archive will be under ejb/src/main/java/com/sun/ts/tests/ejb/ee/tx/txbean in the platform-tck repository.

To determine what the deployment method should be for this case, go to the platform-tck/ejb/src/main/java/com/sun/ts/tests/ejb/ee/tx/txbean/build.xml file and look for the "package" target definition:

  <target name="package">

      <ts.ejbjar descriptor="ejb_tx_txbean_ejb.xml" archivename="ejb_tx_txbean">
        <fileset dir="${class.dir}"
                 includes="com/sun/ts/tests/ejb/ee/tx/txbean/AppException.class, 
                           com/sun/ts/tests/ejb/ee/tx/txbean/SysException.class"/>
      </ts.ejbjar>

      <ts.ejbjar descriptor="ejb_tx_txbean2_ejb.xml" archivename="ejb_tx_txbean2">
        <fileset dir="${class.dir}"
                 includes="com/sun/ts/tests/ejb/ee/tx/txbean/AppException.class, 
                           com/sun/ts/tests/ejb/ee/tx/txbean/SysException.class"/>
      </ts.ejbjar>

      <ts.ear archivename="ejb_tx_txbean" excludedfiles="ejb_tx_txbean2_ejb.jar"/>

      <ts.ear archivename="ejb_tx_txbean2" excludedfiles="ejb_tx_txbean_ejb.jar"/>

  </target>

This says the common archive deployment is going to be made up of two ears, ejb_tx_txbean and ejb_tx_txbean2, each of which contain a single ejb. The first ejb jar is named ejb_tx_txbean and contains AppException.class and SysException.class, both in the same package as the build.xml file. This ejb jar uses the ejb_tx_txbean_ejb.xml as the ejb jar META-INF/ejb-jar.xml standard descriptor. Since there is also a ejb_tx_txbean_ejb.jar.sun-ejb-jar.xml file in the package directory, that should be included as the META-INF/sun-ejb-jar.xml descriptor.

The second ejb jar is named ejb_tx_txbean2 and contains AppException.class and SysException.class, both in the same package as the build.xml file. This ejb jar uses the ejb_tx_txbean2_ejb.xml as the ejb jar META-INF/ejb-jar.xml standard descriptor. Since there is also a ejb_tx_txbean2_ejb.jar.sun-ejb-jar.xml file in the package directory, that should be included as the META-INF/sun-ejb-jar.xml descriptor.

Using this, we can write the following deployment methods:

    @Deployment(name = "ejb_tx_txbean", order = 1, testable = false)
    public static EnterpriseArchive createCommonDeployment() {
        JavaArchive ejb_tx_txbean_ejb = ShrinkWrap.create(JavaArchive.class, "ejb_tx_txbean_ejb.jar");
        // The class files
        ejb_tx_txbean_ejb.addClasses(
                com.sun.ts.tests.ejb.ee.tx.txbean.AppException.class,
                com.sun.ts.tests.ejb.ee.tx.txbean.SysException.class
        );
        URL ejbResURL = ClientTest.class.getResource("com/sun/ts/tests/ejb/ee/tx/txbean/ejb_tx_txbean_ejb.xml");
        if(ejbResURL != null) {
            ejb_tx_txbean_ejb.addAsManifestResource(ejbResURL, "ejb-jar.xml");
        }
        ejbResURL = ClientTest.class.getResource("com/sun/ts/tests/ejb/ee/tx/txbean/ejb_tx_txbean_ejb.jar.sun-ejb-jar.xml");
        if(ejbResURL != null) {
            ejb_tx_txbean_ejb.addAsManifestResource(ejbResURL, "sun-ejb-jar.xml");
        }

        EnterpriseArchive ejb_tx_txbean_ear = ShrinkWrap.create(EnterpriseArchive.class, "ejb_tx_txbean.ear");
        ejb_tx_txbean_ear.addAsModule(ejb_tx_txbean_ejb);

        return ejb_tx_txbean_ear;
    }
    @Deployment(name = "ejb_tx_txbean2", order = 1, testable = false)
    public static EnterpriseArchive createCommonDeployment2() {
        JavaArchive ejb_tx_txbean2_ejb = ShrinkWrap.create(JavaArchive.class, "ejb_tx_txbean2_ejb.jar");
        // The class files
        ejb_tx_txbean2_ejb.addClasses(
                com.sun.ts.tests.ejb.ee.tx.txbean.AppException.class,
                com.sun.ts.tests.ejb.ee.tx.txbean.SysException.class
        );
        URL ejbResURL = ClientTest.class.getResource("com/sun/ts/tests/ejb/ee/tx/txbean/ejb_tx_txbean2_ejb.xml");
        if(ejbResURL != null) {
            ejb_tx_txbean2_ejb.addAsManifestResource(ejbResURL, "ejb-jar.xml");
        }
        ejbResURL = ClientTest.class.getResource("com/sun/ts/tests/ejb/ee/tx/txbean/ejb_tx_txbean2_ejb.jar.sun-ejb-jar.xml");
        if(ejbResURL != null) {
            ejb_tx_txbean2_ejb.addAsManifestResource(ejbResURL, "sun-ejb-jar.xml");
        }

        EnterpriseArchive ejb_tx_txbean2_ear = ShrinkWrap.create(EnterpriseArchive.class, "ejb_tx_txbean2.ear");
        ejb_tx_txbean2_ear.addAsModule(ejb_tx_txbean2_ejb);

        return ejb_tx_txbean2_ear;
    }

There are several conventions in this code. Some need to be followed, some do not. The conventions include:

1. The name value in the @Deployment(name=...) annotation MUST match the base archive name from the build.xml file.
2. The variable names for the archives created SHOULD use the base archive name plus a suffix based on the archive type. The suffixes are:
   • _ejb for ejb jars
   • _web for web archives
   • _ra for resource adaptor archives
3. The archiveName value passed to the ShrinkWrap.create(..., archiveName=) call MUST include this suffix for archives that are added as modules to an EAR. They MUST not be added for the outermost EAR or WAR.
4. When loading a descriptor resources, use the X.class.getResource("absolute-pkg-path-to-descriptor") where X classname of the X.java file you wrote the deployment method in. This will get mapped to an externalized parameter when we move the code to the template.

Arquillian only allows for one deployment archive to be returned per deployment method, so since we have two ears, we need two deployment methods. Now we need to add this to the CommonApps.stg. The start of that file gives the following instructions:

/* To create a new deployment template:
1. Copy the get_deployment_archive_name and imports_deployment_archive_name templates below.
2. Add the lines from the commonarchives.properties file that correspond to the common app you want to add
in the comment.
3. Rename the deployment_archive_name portion to the source directory of the common app.
4. Write the deployment method in you IDE to make sure it compiles, and then paste it in the get_xxxx() method
where the '//put arquillian deployment method here' comment is.
5. Copy the fully qualified class names of any imports you needed other than the standard arquillian ones
into the imports_xxx() method
6. Write a test method in the tck.conversion.ant.api.CommonAppsTest class to test the new deployment method.
Follow the pattern of the validate_helloejbjar() method.
*/

/*
Copy the line from the commonarchives.properties file that corresponds to the common app you want to add here:
here
*/
get_deployment_archive_name(testClient) ::= <<
// put arquillian deployment method here
>>
imports_deployment_archive_name() ::= <<
// put list of imports needed for the arquillian deployment method here.
>>

// Add new common app deployment methods below this line

Ok, so open the CommonApps.stg file in an editor, and after steps 1-3 you would have:

...
// Add new common app deployment methods below this line

/*
#tx session tests' common apps
commonarchives.com/sun/ts/tests/ejb/ee/tx/session=com/sun/ts/tests/ejb/ee/tx/txbean
*/
get_ejb_tx_txbean(testClient) ::= <<
// put arquillian deployment method here
>>
imports_ejb_tx_txbean() ::= <<
// put list of imports needed for the arquillian deployment method here.
>>