
[[implementing-the-porting-package]]
= 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 an abstract class
`tck.arquillian.porting.lib.spi.AbstractTestArchiveProcessor`,  which serves as a base class for vendor implementation-specific code to augment test deployment artifacts with vendor specific descriptors. A sample implementation is provided by...

In addition, there is a set of interfaces in the `com.sun.cts.porting` package.
TODO: which of these interfaces is still in use:
com.sun.ts.lib.porting.TSLoginContextInterface
com.sun.ts.lib.porting.TSURLInterface
com.sun.ts.lib.porting.TSJMSAdminInterface (Full Platform Only)
com.sun.ts.lib.porting.TSHttpsURLConnectionInterface


You must create your own implementations of the porting package
abstract classes and interfaces to work with your particular Jakarta Platform, Enterprise
Edition server environment. 


[[overview]]
== Overview

The Jakarta Platform, Enterprise Edition CI uses a set of
component specific deployment descriptors to configure the runtime files that are associated with each deployable component. GlassFish supports 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`, for vendor specific information.

To specify your implementation of the `tck.arquillian.porting.lib.spi.AbstractTestArchiveProcessor` class, you need to create an Arquillian `org.jboss.arquillian.core.spi.LoadableExtension` service implementation that registers your subclass of the `tck.arquillian.porting.lib.spi.AbstractTestArchiveProcessor` class. An example is shown in the following listing:

[source,java]
----
package wildfly.arquillian;

import org.jboss.arquillian.container.test.spi.client.deployment.ApplicationArchiveProcessor;
import org.jboss.arquillian.core.spi.LoadableExtension;
import org.jboss.arquillian.test.spi.enricher.resource.ResourceProvider;

public class JBossTckExtension implements LoadableExtension {
    @Override
    public void register(ExtensionBuilder builder) {
        builder.service(ResourceProvider.class, JBossXmlProcessor.class);<1>
        builder.observer(JBossXmlProcessor.class);<2>
    }
}
----
<1> Call the `builder.service` method passing in your subclass of `tck.arquillian.porting.lib.spi.AbstractTestArchiveProcessor`.
<2> Call the `builder.observer` method passing in your subclass of `tck.arquillian.porting.lib.spi.AbstractTestArchiveProcessor`.

In the above listing, the `tck.arquillian.porting.lib.spi.AbstractTestArchiveProcessor` subclass is the `JBossXmlProcessor.class`.

The following `com.sun.cts.porting` porting interfaces may need to be implemented if the defaults are not sufficient:

* `TSLoginContextInterface`
* `TSURLInterface`
* `TSJMSAdminInterface` (Full Platform Only)
* `TSHttpsURLConnectionInterface` (Full Platform Only)

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

[[tsjte-porting-classes]]
[source,properties]
----
porting.ts.login.class.1=[vendor-login-class]<1>
porting.ts.url.class.1=[vendor-url-class]<2>
porting.ts.jms.class.1=[vendor-jms-class]<3>
porting.ts.HttpsURLConnection.class
.1=[vendor-httpsURLConnection-class]<4> 
----
<1> <<tslogincontextinterface>>
<2> <<tsurlinterface>>
<3> <<tsjmsadmininterface>>
<4> <<tshttpsurlconnectioninterface>>

You can find these interfaces in the `jakarta.tck:common` artifact and the `src/tools/common/src/main/java/com/sun/ts/lib/porting` directory of the TCK distribution.

Include the implementation of the previous interfaces in the
classpaths of the test clients, and the test server
components in the classpath of your Jakarta Platform, Enterprise Edition server

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

Additional implementation details for the porting package are provided in the following sections.

[[porting-package-apis]]
== Porting Package APIs

The following sections describe the API in the Jakarta EE {tck_version} Platform TCK porting
package. The implementation classes used with the Jakarta Platform,
Enterprise Edition CI are located in the
`https://github.com/jakartaee/platform-tck/tree/main/tools/common/src/main/java/com/sun/ts/lib/porting/implementation` 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:

* <<abstracttestarchiveprocessor>>
* <<tsjmsadmininterface>>
* <<tslogincontextinterface>>
* <<tsurlinterface>>
* <<tshttpsurlconnectioninterface>>

[[abstracttestarchiveprocessor]]
=== AbstractTestArchiveProcessor

The test harness test classes use Arquillian to deploy test artifacts to the containers of the Jakarta EE server being tested. The deployment methods include a `TestArchiveProcessor` interface as showin in the following code fragment:

[source,java]
----
@ExtendWith(ArquillianExtension.class)
@Tag("platform")
@Tag("ejb_remote_async_optional")
@Tag("web_optional")
@Tag("tck-javatest")

@TestMethodOrder(MethodOrderer.MethodName.class)
public class JsfClientEjblitejsfTest extends com.sun.ts.tests.ejb30.bb.async.stateful.metadata.JsfClient {
    static final String VEHICLE_ARCHIVE = "ejbbb_async_stateful_metadata_ejblitejsf_vehicle";

...
        @TargetsContainer("tck-javatest")
        @OverProtocol("javatest")
        @Deployment(name = VEHICLE_ARCHIVE, order = 2)
        public static WebArchive createDeploymentVehicle(@ArquillianResource TestArchiveProcessor archiveProcessor) {
        ...
        }
----

The `TestArchiveProcessor` interface is what the `AbstractTestArchiveProcessor` abstrct class vendors should subclass implements. The `TestArchiveProcessor` interface method of interest ar shown in the following code fragment:

[source,java]
----
public interface TestArchiveProcessor {
    /**
     * Called to process a client archive (jar) that is part of the test deployment.
     * @param clientArchive - the appclient archive
     * @param testClass - the TCK test class
     * @param sunXmlUrl - the URL to the sun-application-client.xml file
     */
    void processClientArchive(JavaArchive clientArchive, Class<?> testClass, URL sunXmlUrl);
    /**
     * Called to process a ejb archive (jar) that is part of the test deployment.
     * @param ejbArchive - the ejb archive
     * @param testClass - the TCK test class
     * @param sunXmlUrl - the URL to the sun-ejb-jar.xml file
     */
    void processEjbArchive(JavaArchive ejbArchive, Class<?> testClass, URL sunXmlUrl);
    /**
     * Called to process a web archive (war) that is part of the test deployment.
     * @param webArchive - the web archive
     * @param testClass - the TCK test class
     * @param sunXmlUrl - the URL to the sun-web.xml file
     */
    void processWebArchive(WebArchive webArchive, Class<?> testClass, URL sunXmlUrl);
    /**
     * Called to process a resource adaptor archive (rar) that is part of the test deployment.
     * @param rarArchive - the resource archive
     * @param testClass - the TCK test class
     * @param sunXmlUrl - the URL to the sun-ra.xml file
     */
    void processRarArchive(JavaArchive rarArchive, Class<?> testClass, URL sunXmlUrl);
    /**
     * Called to process a persistence unit archive (par) that is part of the test deployment.
     * @param parArchive - the resource archive
     * @param testClass - the TCK test class
     * @param persistenceXmlUrl - the URL to the sun-ra.xml file
     */
    void processParArchive(JavaArchive parArchive, Class<?> testClass, URL persistenceXmlUrl);
    /**
     * Called to process an enterprise archive (ear) that is part of the test deployment.
     * @param earArchive - the application archive
     * @param testClass - the TCK test class
     * @param sunXmlUrl - the URL to the sun-application.xml file
     */
    void processEarArchive(EnterpriseArchive earArchive, Class<?> testClass, URL sunXmlUrl);
}
----

For each type of Jakarta EE component archive that is included in a test deployment, one or more of these methods will be called with the component archive, the test harness test class, and a possibly null URL for the GlassFish/Sun version of the vendor descriptor. Not all test deployments include a GlassFish/Sun version of the vendor descriptor. Those that do not will pass in a `null` descriptor URL. Vendors could choose to transform the GlassFish version of the descriptor, or use some other scheme such as the test package/class name to locate their equivalent vendor specific descriptor.

[[tsjmsadmininterface]]
=== TSJMSAdminInterface (Full Platform Only)

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.

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

[[tslogincontextinterface]]
=== 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.

[[tsurlinterface]]
=== 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 `com.sun.ts.lib.porting.implementation.SunRIURL` implementation of this class from the jakarta.tck:common artifact can be used.

[[tshttpsurlconnectioninterface]]
=== TSHttpsURLConnectionInterface (Full Platform Only)

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

=======================================================================


