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
- 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
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
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. |
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.
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
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 therepackage-app
submodule, which configures the JAX-RPC conversion tool. TheappLocation
parameter specifies the path to the application to be converted. Thereplace-jaxrpc
goal is bound to thecompile
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 therun-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 therun-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 thejndi-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 thehttp-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>
- If you are converting and deploying an EJB application, the configuration to specify the context
root within the
- 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.