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

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.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 Release 9 TCK 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
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 9 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 is removed
Ant-Based Deployment Interface
TSJMSAdminInterface
TSLoginContextInterface
TSURLInterface
TSHttpsURLConnectionInterface

11.2.1 TSDeploymentInterface2 is removed

TSDeploymentInterface2 + TSDeployment2 are no longer supported since the Jakarta Deployment spec is removed. Please use the TSDeploymentInterface instead. 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:

11.2.2 Ant-Based Deployment Interface

In addition to the Java-based deployment porting interfaces, Jakarta EE 9 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 9 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 9 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 9 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 6.0, 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.