Implementing the Porting Package

11 Implementing the Porting Package

Some functionality in the Jakarta Platform, Enterprise Edition platform is not completely specified by an API. To handle this situation, the Jakarta EE 8 CTS test suite defines a set of interfaces in the com.sun.cts.porting package, which serve to abstract any implementation-specific code. The CTS also provides implementations of these interfaces to work with the Jakarta Platform, Enterprise Edition CI.

You must create your own implementations of the porting package interfaces to work with your particular Jakarta Platform, Enterprise Edition server environment. You also need to create a deployment plan for each deployable component (EAR, EJB JAR, WAR, and RAR files) in the test suite as defined by the Jakarta Platform, Enterprise Edition platform and JSR-88. There is a new getDeploymentPlan() method on the TSDeploymentInterface2 interface, which returns an input stream to your deployment plan.

Note	Vendors are required to intrepret the `ior-security-config` specified in the EJB runtime XML file and configure the EJB according to the specified values. For more information, see The security-role-mapping Element.

11.1 Overview

The Jakarta Platform, Enterprise Edition CI uses a set of module-name-with-extension`.sun-standard-deployment-desc-component-prefix.xml` files that are associated with each deployable component. A CTS DeploymentInfo object parses the contents of several runtime XML files: sun-application_1_4-0.xml, sun-application-client_1_4-0.xml, sun-ejb-jar_2_1-0.xml, and sun-web-app_2_4-0.xml, and makes their content available to create deployment plans by means of the getDeploymentPlan() method.

To use specific implementations of these classes, you simply modify the following entries in the porting class .1 section of the ts.jte environment file to identify the fully-qualified class names:

porting.ts.deploy2.class.1=[vendor-deployment-class]
porting.ts.login.class.1=[vendor-login-class]
porting.ts.url.class.1=[vendor-url-class]
porting.ts.jaxrpc.class.1=[vendor-jaxrpc-class]
porting.ts.jms.class.1=[vendor-jms-class]
porting.ts.HttpsURLConnection.class.1=[vendor-httpsURLConnection-class]

The <TS_HOME>/src/com/sun/ts/lib/porting directory contains the interfaces and Factory classes for the porting package.

Note	You must not modify any of the CTS VRelease 8 source code. Create your own implementations of these interfaces and point to them in the appropriate section of the `ts.jte` file.

Note the change to the deployment porting property above. It has changed to be deploy2. This is because there is a new deployment porting interface because of the standardization of a deployment API in Java Platform, Enterprise Edition. Any functionality that is still not addressed by this API is part of the new interface com.sun.ts.lib.porting.TSDeploymentInterface2.

Make sure your porting class implementations meet the following requirements:

Implement the following porting interfaces:
- TSDeploymentInterface2
- TSLoginContextInterface
- TSURLInterface
- TSJMSAdminInterface
- TSHttpsURLConnectionInterface
- TSJAXRPCInterface
Include the implementation of the previous interfaces in the classpaths of JavaTest, the test clients, and the test server components:
- In the ts.harness.classpath property in the <TS_HOME>/bin/ts.jte file
- In the CLASSPATH variable of the command.testExecute and command.testExecuteAppClient properties in the ts.jte file
- In the classpath of your Jakarta Platform, Enterprise Edition server

Note that because the JavaTest VM calls certain classes in the CTS porting package directly, porting class implementations are not permitted to exit the VM (for example, by using the System.exit call).

11.2 Porting Package APIs

The following sections describe the API in the Jakarta EE 8 CTS porting package. The implementation classes used with the Jakarta Platform, Enterprise Edition CI are located in the <TS_HOME>/src/com/sun/ts/lib/implementation/sun/javaee directory. You are encouraged to examine these implementations before you create your own.

Detailed API documentation for the porting package interfaces is available in the <TS_HOME>/docs/api directory. The API included in this section are:

TSDeploymentInterface2
Ant-Based Deployment Interface
TSJMSAdminInterface
TSLoginContextInterface
TSURLInterface
TSHttpsURLConnectionInterface
TSJAXRPCInterface

11.2.1 TSDeploymentInterface2

The Jakarta EE 8 CTS test suite provides a new version of the Deployment porting interface. With the introduction of a standard deployment API in the legacy J2EE 1.4 platform (via Jakarta Deployment Specification (Originally JSR-88)), many of the porting methods in the original interface TSDeploymentInterface no longer require implementation-specific functionality. The Jakarta EE 8 CTS test suite provides an implementation of the interface TSDeploymentInterface, which uses only the standard Deployment APIs defined by the Jakarta Platform, Enterprise Edition platform. The following properties are still in the ts.jte file to reflect this and should not be changed:

porting.ts.deploy2.class.1=com.sun.ts.lib.deliverable.cts.deploy.StandardDeployment14
porting.ts.deploy2.class.2=com.sun.ts.lib.deliverable.cts.deploy.StandardDeployment14

The class StandardDeployment14 also requires the following properties to be set in the ts.jte file:

deployManagerJarFile.1=${JAVAEE_HOME}/lib/deployment/sun-deploy.jar
deployManageruri.1=deployer:Sun:AppServer:RI::localhost
deployManageruname.1=foo
deployManagerpasswd.1=bar

These properties are necessary in order to get an instance of and interact with the DeploymentManager for your Jakarta Platform, Enterprise Edition implementation.

The deployManagerJarFile property must point to the JAR file that contains the manifest entries necessary to get your DeploymentManager instance. The deployManageruri property represents the URI that is used to locate your DeploymentManager.

The deployManageruname and deployManagerpasswd properties are used when calling DeploymentFactoryManager.getDeploymentManager.

StandardDeployment14 calls into the new deployment porting interface (TSDeploymentInterface2). Implementers must implement this new interface and set the following property in the ts.jte file to point to their implementation:

porting.ts.deploy2.class.1=com.sun.ts.lib.implementation.sun.JavaEE.SunRIDeployment2

The TSDeployment2 class acts as a Factory object for creating concrete implementations of TSDeploymentInterface2. The concrete implementations are specified by the porting.ts.deploy2.class.1 and porting.ts.deploy2.class.2 properties in the ts.jte file. Each Jakarta Platform, Enterprise Edition implementation must provide an implementation of the interface TSDeploymentInterface2 to support the automatic deployment and undeployment of test applications by the JavaTest test harness. Providing this functionality enables the entire test suite to be run without having to manually deploy/undeploy the Jakarta Platform, Enterprise Edition test applications prior to running the tests. The implementation provided with this release uses the semantics of the Jakarta Platform, Enterprise Edition CI.

11.2.2 Ant-Based Deployment Interface

In addition to the Java-based deployment porting interfaces, Jakarta EE 8 CTS introduces an Ant-based porting interface as well. The Java-based interface is still used for deployment/undeployment during test runs. The Ant-based interface is used when you want to only deploy/undeploy archives associated with a subdirectory of tests. The Ant-based deployment interface is used by the following:

The build.special.webservices.clients target in the ${ts.home}/bin/build.xml file
This target deploys archives to your server implementation and then builds the client classes that use those archives. You must run this target before you run the tests under the ${ts.home}/src/com/sun/ts/tests/webservices12/specialcases directory.
The deploy and undeploy targets in each test subdirectory under the ${ts.home}/src/com/sun/ts/tests directory
To use these targets, which are useful for debugging, you must provide an Ant-based deployment implementation.

11.2.2.1 Creating Your Own Ant-based Deployment Implementation

The Ant-based deployment implementation for the Jakarta EE 8 CI is under ${ts.home}/bin/xml/impl/glassfish directory. To create your own implementation, create a deploy.xml file under the ${ts.home}/bin/xml/impl/<vendor-name> directory. Within the file, create and implement the -deploy and -undeploy targets.

See ${ts.home}/bin/xml/impl/glassfish/deploy.xml to see how these targets are implemented for the Jakarta EE 8 CI .

Note	There is also a Java-based implementation of TSDeploymentInterface (`com.sun.ts.lib.implementation.sun.javaee.glassfish.AutoDeployment`). This implementation, which leverages the Jakarta EE 8 CI implementation of the Ant-based deployment interface, calls the Ant targets programmatically.

11.2.3 TSJMSAdminInterface

Jakarta Messaging-administered objects are implementation-specific. For this reason, the creation of connection factories and destination objects have been set up as part of the porting package. Each Jakarta Platform, Enterprise Edition implementation must provide an implementation of the TSJMSAdminInterface to support their own connection factory, topic/queue creation/deletion semantics.

The TSJMSAdmin class acts as a Factory object for creating concrete implementations of TSJMSAdminInterface. The concrete implementations are specified by the porting.ts.jms.class.1 and porting.ts.jms.class.2 properties in the ts.jte file.

If you wish to create the Jakarta Messaging-administered objects prior to executing any tests, you may use the default implementation of TSJMSAdminInterface, SunRIJMSAdmin.java, which provides a null implementation. In the case of the Jakarta Platform, Enterprise Edition CI Eclipse GlassFish 5.1, the Jakarta Messaging administered objects are created during the execution of the config.vi Ant target.

There are two types of Jakarta Messaging-administered objects:

A ConnectionFactory, which a client uses to create a connection with a JMS provider
A Destination, which a client uses to specify the destination of messages it sends and the source of messages it receives

11.2.4 TSLoginContextInterface

The TSLoginContext class acts as a Factory object for creating concrete implementations of TSLoginContextInterface. The concrete implementations are specified by the porting.ts.login.class.1 property in the ts.jte file. This class is used to enable a program to login as a specific user, using the semantics of the Jakarta Platform, Enterprise Edition CI. The certificate necessary for certificate-based login is retrieved. The keystore file and keystore password from the properties that are specified in the ts.jte file are used.

11.2.5 TSURLInterface

The TSURL class acts as a Factory object for creating concrete implementations of TSURLInterface. The concrete implementations are specified by the porting.ts.url.class.1 property in the ts.jte file. Each Jakarta Platform, Enterprise Edition implementation must provide an implementation of the TSURLInterface to support obtaining URL strings that are used to access a selected Web component. This implementation can be replaced if a Jakarta Platform, Enterprise Edition server implementation requires URLs to be created in a different manner. In most Jakarta Platform, Enterprise Edition environments, the default implementation of this class can be used.

11.2.6 TSHttpsURLConnectionInterface

The TSHttpsURLConnection class acts as a Factory object for creating concrete implementations of TSHttpsURLConnectionInterface. The concrete implementations are specified by the porting.ts.HttpsURLConnection.class.1 and .2 properties in the ts.jte file.

You must provide an implementation of TSHttpsURLConnectionInterface to support the class HttpsURLConnection.

Note	The `SunRIHttpsURLConnection` implementation class uses `HttpsURLConnection` from Java SE 8.

11.2.7 TSJAXRPCInterface

The TSJAXRPC class acts as a Factory object for creating concrete implementations of TSJAXRPCInterface. The concrete implementations are specified by the porting.ts.jaxrpc.class.1 and .2 properties in the ts.jte file.

You must provide an implementation of TSJAXRPCInterface to support the class TSJAXRPC. This class is used to provide as name/value pairs the URL value of the deployed webservice endpoints for those sets of tests which use DII, direct HTTP, or direct SAAJ 1.4 to communicate to the endpoints. SOAP with Attachments API for Java (SAAJ) is included in Java SE 8.