type=page status=published title=Implementing the Porting Package next=commonappdeploy.html prev=building.html ~~ 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.
=======================================================================
[[GFASD]][[overview]]
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:
[source,oac_no_warn]
----
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).
[[GFAUG]][[porting-package-apis]]
11.2 Porting Package APIs
~~~~~~~~~~~~~~~~~~~~~~~~~
The following sections describe the API in the Jakarta EE 9 Platform TCK 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:
* link:#GFASM[TSDeploymentInterface2]
* link:#GKLJO[Ant-Based Deployment Interface]
* link:#GFASI[TSJMSAdminInterface]
* link:#GFATH[TSLoginContextInterface]
* link:#GFATO[TSURLInterface]
* link:#GFASJ[TSHttpsURLConnectionInterface]
[[GFASM]][[tsdeploymentinterface2]]
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:
----
[[GKLJO]][[ant-based-deployment-interface]]
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.
[[GKLJF]][[creating-your-own-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.
=======================================================================
[[GFASI]][[tsjmsadmininterface]]
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
[[GFATH]][[tslogincontextinterface]]
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.
[[GFATO]][[tsurlinterface]]
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.
[[GFASJ]][[tshttpsurlconnectioninterface]]
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.
=======================================================================