Migrating JAX-RPC applications to Liberty by using Gradle

You can use the Liberty JAX-RPC conversion tool for Gradle to convert JAX-RPC applications to use JAX-WS technology so that they can run on Liberty. This tool is a Gradle 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.

Gradle 7.x
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 Gradle 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-gradle-plugin-1.x.jar, the installation process is the same.
1. Download the Liberty JAX-RPC conversion tool for Gradle zip file from IBM Fix Central and extract the files locally.
  The archive contains the following files: jaxrpc-tools-gradle/liberty-jaxrpc-gradle-plugin-1.0.jar, jaxrpc-tools-gradle/build.gradle, and jaxrpc-tools-gradle/liberty-jarxrpc-gradle-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-gradle/liberty-jarxrpc-gradle-plugin-1.0.jar.sig signature file and the Liberty public key to verify the authenticity and integrity of the jaxrpc-tools-gradle/liberty-jaxrpc-gradle-plugin-1.0.jar file 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 Maven Publish Plug-in to install the conversion tool plug-in by running the following command.
```
gradle publishToMavenLocal -b jaxrpc-tools-gradle/build.gradle
```
Add the following plug-in configuration to your project build.gradle file.
```
buildscript {
    repositories {
        mavenLocal()
        mavenCentral()
    }
    dependencies {
        classpath "com.ibm.websphere.appserver.tools:liberty-jaxrpc-gradle-plugin:1.0"
    }
}

apply plugin: "com.ibm.websphere.appserver.tools.liberty-jaxrpc-gradle"

group = "com.ibm.test"
version = "1.0-SNAPSHOT"

libertyJAXRPC {

...

}
```
To run the plug-in in your build lifecycle, you must determine the appropriate task dependencies for the validateWSDL or replaceJAXRPC tasks for your build environment.

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 libertyJAXRPC section of the build.gradle file to validate and convert your JAX-RPC application.
For more information, see the configuration parameters and configuration examples in the following sections.
Validate and convert your application by running the appropriate Gradle task from the command line.
The validateWSDL task validates whether a JAX-RPC application can be converted to use JAX-WS. The replaceJAXRPC task first validates that an application can be converted to JAX-RPC. If the application passes validation then task also converts it. The following examples show the command for each task.
- ```
gradle validateWSDL 
```
- ```
gradle replaceJAXRPC
```
The replaceJAXRPC task implicitly runs the validateWSDL task before it converts the application. Do not configure the validateWSDL task with the replaceJAXRPC task. The validateWSDL task is intended for preliminary analysis to help determine which applications are good candidates for conversion.

Results

The validateWSDL task 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 replaceJAXRPC task, the original application is located in the build/jax-rpc-tools-apps/originalApplications directory and the converted application is located in the build/jax-rpc-tools-apps/convertedApplications directory. A change log that is named <original_archive_name>.change.log is generated in the build directory for each converted application.
You can also convert a JAX-RPC application by using a multi-module Gradle project.

Configuration parameters

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

Table 1. Configuration parameters for the Gradle 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.
`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`.

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 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 `replaceJAXRPC` task, 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 `validateWSDL` task 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 libertyJAXRPC extension in your build.gradle file.

Convert an application from JAX-RPC technology to JAX-WS technology with the replaceJAXRPC task by using the appLocation parameter.

libertyJAXRPC {
    applications {
        testApp {
            appLocation = file(`src/test/resources/TestApp.war`)
        }
    }
}

Convert an application from JAX-RPC technology to JAX-WS technology with the replaceJAXRPC task by using the configuration from the libertyJAXRPC section.
```
libertyJAXRPC {
    applications {
        testApp {
            appLocation = file(`src/test/resources/TestApp.war`)
        }
    }
}
```

Validate a WSDL file with the validateWSDL task by using a URL in the wsdlLocation parameter.

libertyJAXRPC {
    applications {
        testApp {
            wsdlLocation = `http://localhost:9080/TestApp/services/TestAppIF?wsdl`        
        }
    }
}

Validate the WSDL files within the specified application with the validateWSDL task by using the appLocation parameter.

libertyJAXRPC {
    applications {
        testApp {
            appLocation = file(`src/test/resources/TestApp.war`)        
        }
    }
}

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

You can use a multi-module Gradle project to convert an existing JAX-RPC application to JAX-WS and deploy it to Liberty. In this configuration, a top-level settings.gradle 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.

The following example shows the top-level settings.gradle file, which includes two submodules.
```
rootProject.name = 'service'
include 'replace', 'run'
```

The following example shows the application conversion build.gradle file in the replace submodule, which configures the JAX-RPC conversion. The appLocation parameter specifies the path to the application to be converted.

buildscript {
    repositories {
        mavenLocal()
        mavenCentral()
    }
    dependencies {
        classpath "com.ibm.websphere.appserver.tools:liberty-jaxrpc-gradle-plugin:1.0"
    }
}

apply plugin: "com.ibm.websphere.appserver.tools.liberty-jaxrpc-gradle"

group = "com.ibm.test"
version = "1.0-SNAPSHOT"

libertyJAXRPC {
    applications {
        DemoRPC {
            appLocation = file("src/test/resources/DemoRPC.war")
        }
    }
}

The following example shows the build.gradle file for the run submodule.

buildscript {
    repositories {
        mavenLocal()
        mavenCentral()
    }
    dependencies {
        classpath "io.openliberty.tools:liberty-gradle-plugin:3.2"
    }
}

apply plugin: "liberty"

repositories {
    mavenLocal()
    mavenCentral()
}

dependencies {
    libertyApp "com.ibm.test:DemoRPC:1.0-SNAPSHOT"
}

liberty {
    server {
        name = "test"
        looseApplication = false
        bootstrapProperties = ['httpPort':'9080', 'httpsPort':'9443']
    }
}

libertyStart.dependsOn "deploy"
deploy.dependsOn ":replace:replaceJAXRPC"
build.dependsOn 'libertyStart'

For this multi-module project, you must define a server.xml file in the src/main/liberty/config directory of the run submodule 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="${httpPort}"
              httpsPort="${httpsPort}" />

    <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.
```
gradle :run:libertyStart -i -s
```
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.