Migrating JAX-RPC applications to Liberty by using Maven

You can use the Liberty JAX-RPC conversion tool for Maven to convert JAX-RPC applications to use JAX-WS technology so that they can run on Liberty. This tool is a Maven plug-in that supports the conversion of JAX-RPC client and service applications.

Before you begin

The following prerequisites must be installed to use this tool.

Maven 3.5.0 or later.
Java SE
- Versions 1.0 and 1.1 of the conversion tool support Java SE 8.
- Versions 1.2 and later of the conversion tool support Java SE 8 and Java SE 11.

Although the tool itself does not require any specific Liberty version, the converted applications that it creates can run only on version 21.0.0.11 or later.

About this task

The Liberty JAX-RPC conversion tool for Maven can validate whether a traditional WebSphere application that uses JAX-RPC technology can be converted into an application that uses JAX-WS technology. If the application passes validation, the tool can convert the application binary to JAX-WS so that it can run on Liberty. However, the dynamic invocation interface (DII), which uses the javax.xml.rpc.Call interface, is not supported. Also, to convert JAX-RPC service applications, the wsdl files must either be located within the service application or be referenced by a URL in the deployment descriptor file for the conversion to succeed. This tool is available only to licensed WebSphere® Application Server Liberty users.

Procedure

Install the JAX-RPC conversion tool.
These steps refer to version 1.0 of the JAX-RPC conversion tool. Although subsequent versions of the tool might be reflected in the package and file names on IBM Fix Central, for example liberty-jaxrpc-maven-plugin-1.x.jar, the installation process is the same.
1. Download the Liberty JAX-RPC conversion tool for Maven zip file from IBM Fix Central and extract the files locally.
  The archive contains the following files: jaxrpc-tools-maven/liberty-jaxrpc-maven-plugin-1.0.jar, jaxrpc-tools-maven/pom.xml, and jaxrpc-tools-maven/liberty-jarxrpc-maven-plugin-1.0.jar.sig.
2. Optional: Verify the digital signature of the JAX-RPC conversion tool archive .jar file.
  
  You can use the jaxrpc-tools-maven/liberty-jarxrpc-maven-plugin-1.0.jar.sig signature file and the Liberty public key to verify the authenticity and integrity of the jaxrpc-tools-maven/liberty-jaxrpc-maven-plugin-1.0.jar by running the openssl command. You can obtain the Liberty public key from the Public Key link on the IBM Fix Central page for the JAX-RPC conversion tool. For more information about running the openssl command, see step 2 of Verifying Liberty release packages.
3. From a command-line interface, go to the directory that contains the extracted zip file and use the Apache Maven Install Plug-in to install the conversion tool plug-in by running the following command.
```
mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -Dfile=./jaxrpc-tools-maven/liberty-jaxrpc-maven-plugin-1.0.jar -DpomFile=./jaxrpc-tools-maven/pom.xml
```
  On Windows systems, the file name values for the .jar and .xml files must be enclosed in quotes, as shown in the following example.
```
mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -Dfile="./jaxrpc-tools-maven/liberty-jaxrpc-maven-plugin-1.0.jar" -DpomFile="./jaxrpc-tools-maven/pom.xml"
```

Add the following plug-in configuration to your project pom.xml file.

<properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>
<plugin>
    <groupId>com.ibm.websphere.appserver.tools</groupId>
    <artifactId>liberty-jaxrpc-maven-plugin</artifactId>
    <version>1.0</version>
    <executions>
        <execution>
            <id>…</id>
            <phase>...</phase>
            <goals>
                <goal>…</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
           ...
    </configuration>
</plugin>

To run the plug-in in your build lifecycle, you must determine the appropriate phase for your build environment to bind the validate-wsdl or replace-jaxrpc goals.

This example uses version 1.0 of the JAX-RPC conversion tool. Replace the version number in your configuration to reflect the version of the tool that you downloaded from IBM Fix Central.

Define the configuration parameter in your pom.xml file to validate and convert your JAX-RPC application.
To run the plug-in on a specific archive, you can specify its location in the appLocation parameter of the application subparameter. Alternatively, if the archive is already specified in your Maven project dependencies, you can set the checkDependencies parameter to true. For more information, see the configuration parameters and configuration examples in the following sections.
Validate and convert your application by running the appropriate Maven goal.
The validate-wsdl goal validates whether a JAX-RPC application can be converted to use JAX-WS. The replace-jaxrpc goal first validates that an application can be converted to JAX-RPC. If the application passes validation then the goal also converts it. You can run either goal with the liberty-jaxrpc prefix, as shown in the following examples.
- ```
mvn liberty-jaxrpc:validate-wsdl
```
- ```
mvn liberty-jaxrpc:replace-jaxrpc
```
The replace-jaxrpc goal implicitly runs the validate-wsdl goal before it converts the application. Do not configure the validate-wsdl goal with the replace-jaxrpc goal. The validate-wsdl goal is intended for preliminary analysis to help determine which applications are good candidates for conversion.

Results

The validate-wsdl goal produces console output that specifies whether the application passed validation. A WSDL file that is not valid for conversion produces output with details on the issues that were found.
After you successfully run the replace-jaxrpc goal, the original application is located in the target/jax-rpc-tools-apps/originalApplications directory and the converted application is located in the target/jax-rpc-tools-apps/convertedApplications directory. A change log that is named <original_archive_name>.change.log is generated in the target directory for each converted application.
You can also convert a JAX-RPC application by using a multi-module Maven project.

Configuration parameters

The following tables list the configuration parameters that are available for the Liberty JAX-RPC conversion tool for Maven.

Table 1. Configuration parameters for the Maven JAX-RPC conversion plug-in
Parameter	Description
`applications`	Multiple application blocks can be added to the applications configuration. This parameter is required if no project application or dependencies are specified.
`checkDependencies`	If this parameter is set to `true`, the project dependencies are checked for application artifacts of type `war` or `ear`. Do not set this parameter to `true` if the `applications` parameter is configured. The default value is `false`.
`eeLevel`	An optional string that specifies which level of Java EE is used when deployment descriptors are converted. The valid values are `7` or `8`. The default value is `7`.
`interopRequired`	An optional Boolean value that indicates whether the WSDL files are checked for conditions that might make the application not interoperate with a JAX-RPC client or service after conversion. If interoperability is not required, set this parameter to `false`. The default value is `true`.
`verboseLog`	An optional Boolean value that controls the level of logging. When this parameter is set to `true`, all `DEBUG` log messages from the Maven plug-in are displayed as `INFO` log messages. The default value is `false`. You can also specify this logging configuration by including `-Dliberty.jaxrpc.verbose.log` on the command line.

If you specify the applications parameter, it must contain at least one application subparameter. This subparameter specifies the application to process and must contain either a appLocation or wsdlLocation parameter. The following table lists the parameters that are available for the application subparameter.

Table 2. Configuration parameters for the application subparameter
Parameter	Description
`appLocation`	The location of the application WAR or EAR file to process. This parameter is required for the `replace-jaxrpc` goal, or if no project application is specified and the `wsdlLocation` parameter is not set.
`eeLevel`	An optional string value that specifies which level of Java EE is used when deployment descriptor files are converted. Valid values are 7 and 8. If this parameter is not specified, the `eeLevel` value from the common configuration is used.
`interopRequired`	An optional Boolean value that indicates whether the WSDL files are checked for conditions that might make the application not interoperate with a JAX-RPC client or service after conversion. If this parameter is not specified, the `interopRequired` value from the common configuration is used.
`wsdlLocation`	Location of the WSDL file or WSDL URL. This parameter is valid only for the `validate-wsdl` goal and is required when the `appLocation` parameter is not set and no project application is specified.

Configuration examples

The following examples demonstrate different configuration options for the configuration parameter in your Maven pom.xml file.

Convert an application from JAX-RPC technology to JAX-WS technology with the replace-jaxrpc goal by using the appLocation parameter.

<configuration>
    <applications>
        <application>
            <appLocation>apps/DemoRPC.war</appLocation>
        </application>
    </applications>
</configuration>

Convert an application that is specified in the Maven project dependencies from JAX-RPC technology to JAX-WS technology with the replace-jaxrpc goal by using the checkDependencies parameter.
```
<configuration>
    <checkDependencies>true</checkDependencies>
</configuration>
```

Validate a WSDL file with the validate-wsdl goal by using a URL in the wsdlLocation parameter.

<configuration>
    <applications>
        <application>
            <wsdlLocation>http://localhost:9080/DemoRPC/services/HelloIF?wsdl
</wsdlLocation>
        </application>
    </applications>
</configuration>

Validate the WSDL files with the validate-wsdl goal within the project dependencies by using the checkDependencies parameter.
```
<configuration>
    <checkDependencies>true</checkDependencies>
</configuration>
```

Converting a JAX-RPC application by using a multi-module Maven project

You can use a multi-module Maven project to convert an existing JAX-RPC application to JAX-WS and deploy it to Liberty . In this configuration, a top-level pom.xml file specifies two submodules: one to convert and repackage the application and another to install and run it on an instance of Liberty

This example uses version 1.0 of the JAX-RPC conversion tool. Replace the version number in your configuration to reflect the version of the tool that you downloaded from IBM Fix Central.

Configure your top-level pom.xml file with two submodules, as shown in the following example.

<project>
    ….
    <modules>
        <module>repackage-app</module>
        <module>run-app-on-liberty</module>
    </modules>
    ….
</project>

Configure the submodule to repackage the JAX-RPC application.

The following example shows the application conversion pom.xml file in the repackage-app submodule, which configures the JAX-RPC conversion tool. The appLocation parameter specifies the path to the application to be converted. The replace-jaxrpc goal is bound to the compile phase of the build lifecycle.

<project>
    ….
    <groupId>demo</groupId>
    <artifactId>demo-run-war</artifactId>
    <version>1.0-SNAPSHOT </version>
    <packaging>pom</packaging>
    ….
    <build>
        <plugins>
            <plugin>
                <groupId>com.ibm.websphere.appserver.tools</groupId>
                <artifactId>liberty-jaxrpc-maven-plugin</artifactId>
                <version>1.0</version>
                <configuration>
                    <applications>
                        <application>
                             <appLocation>/path/to/app/demo.war</appLocation>
                        </application>
                     </applications>
               </configuration>
               <executions>
                   <execution>
                       <id>replace </id>
                       <phase>compile</phase>
                       <goals>
                           <goal>replace-jaxrpc</goal>
                       </goals>
                   </execution>
               </executions>
            </plugin>
        </plugins>
    </build>
    ….
</project>

Configure the other submodule to run the converted application on Liberty.

The following example shows the pom.xml file for the run-app-on-liberty submodule.

<project>
    <groupId>demo</groupId>
    <artifactId>run-demo-war-liberty</artifactId>
    <version>1.0-SNAPSHOT </version>
    <packaging>pom</packaging>
    ….
    <dependencies>
        <dependency>
            <groupId>demo</groupId>
            <artifactId>demo</artifactId>
            <version>1.0-SNAPSHOT</version>
            <type>war</type>
        </dependency>
    <dependencies>
    … 
    <build>
        <plugins>
            <plugin>
                <groupId>io.openliberty.tools</groupId>
                <artifactId>liberty-maven-plugin</artifactId>
                <version>3.4</version>
                <configuration>
                     <serverName>demoServer</serverName>
                     <deployPackages>dependencies</deployPackages>
                     <stripVersion>true</stripVersion>
                     <looseApplication>false</looseApplication>
               </configuration>
               <executions>
                   <execution>
                       <id>create-and-run-liberty-server </id>
                       <phase>install</phase>
                       <goals>
                           <goal>create</goal>
                           <goal>deploy</goal>
                           <goal>start</goal>
                       </goals>
                   </execution>
                   …..
              </executions>
            </plugin>
        </plugins>
    </build>
    ….
</project>

For this multi-module project, you must define a server.xml file in the src/main/liberty/config directory of the run-app-on-liberty subproject that is similar to the following example. Your application might require more features than the ones shown here. For example, client applications might need to specify the jndi-1.0 feature.

<server description="demo server">
    <featureManager>
        <feature>localConnector-1.0</feature>
        <feature>servlet-4.0</feature>
        <feature>jaxws-2.2</feature>
        ….
    </featureManager>
    …     
    <httpEndpoint id=" defaultHttpEndpoint" httpPort="9080" httpsPort="9443"/>
    <application name="DemoRPC" id="DemoRPC" context-root="DemoRPC/services" location="demo.war" type="war">
    </application>
    … 
</server>

If you are converting and deploying an EJB application, the configuration to specify the context root within the application element is slightly different. You must specify the context root within the http-publishing context-root subelement, as shown in the following example.
```
<application name="DemoRPC" id="DemoRPC" location="demo.war" type="war">
   <webservices-bnd>
       <http-publishing context-root="DemoRPC/services"/>
   </webservices-bnd>
</application>
```

To convert the application, start the Liberty and deploy the application to the server, run the following command from the directory that defines the multi-module project.
```
mvn clean install
```
You can now connect your existing JAX-RPC client application to the newly deployed JAX-WS service application on Liberty, or connect your newly deployed JAX-WS client application to your existing JAX-RPC service application.