Enabling a third-party JAX-WS application in WebSphere Application Server V6.1

Nikhil ThakerSenior Software EngineerWeb Services ArchitectIBM, Austin, TX

January, 2010

© Copyright International Business Machines Corporation 2010. All rights reserved.

This article describes how you can use a third-party Java™ API for XML Web services (JAX-WS) engine in WebSphere Application Server V6.1. It describes how to deploy an application using an external third-party JAX-WS engine, as well as limitations and potential issues.

The article is intended only for WebSphere Application Server instances with the Feature Pack for Web Services installed.

Introduction ............................................................................................................................ 2 Limitations of using third-party JAX-WS runtimes ........................................................... 2 Required configuration changes ......................................................................................... 3 Class loader configuration .................................................................................................. 3

Building and deploying an Axis2 Web services application .................................................. 5 Build the Axis2 application ................................................................................................ 5 Deploy the Axis2 WAR ...................................................................................................... 6 Troubleshoot Axis2 deployment ...................................................................................... 14

Building and deploying a CXF Web services application ................................................... 18 Build the CXF application ................................................................................................ 19 Deploy the CXF application ............................................................................................. 19 Troubleshoot CXF application deployment ...................................................................... 21

Building and deploying a Metro Web services application ................................................. 21 Build the Metro application .............................................................................................. 21 Deploy the Metro application ........................................................................................... 22 Troubleshoot Metro application deployment ................................................................... 24

Disabling the IBM JAX-WS implementation ....................................................................... 24 Summary ............................................................................................................................... 25 Resources .............................................................................................................................. 26 About the author ................................................................................................................... 26

Introduction Some WebSphere Application Server (hereafter Application Server) users would like to leverage a third-party JAX-WS engine like Axis2 or Apache CXF by having these runtimes embedded in an application EAR file. There are several reasons you might want to do this, such as to use features specific to the third-party runtimes, to reuse code, or to achieve application consistency in a multi-vendor or multi-version environment.

When such a third-party application is deployed on Application Server, the Application Server JAX-WS Web services engine must be disabled so it doesn’t conflict with the third-party implementation. Starting with WebSphere V6.1 Fixpack 29, configuration options were added to enable this on a per-application or per-server basis.

Use of third-party JAX-WS runtimes has limitations and requires certain configuration changes. In some cases, it may also require manual intervention to resolve issues that occur during deployment and runtime. These limitations and issues vary based on theexternal runtime.

This article demonstrates how to use an application EAR that has Axis2, Apache CXF, and Metro runtimes embedded in it.

Notes: 1. WebSphere does not claim support for any of the third-party JAX-WS runtimes.

IBM ensures successful deployment of such applications only. See the Tech Note for more information.

2. This document does not imply IBM is endorsing the use of any of the third-party runtimes mentioned in this document on WebSphere Application Server.

Limitations of using third-party JAX-WS runtimesFollowing are the observed limitations when deploying an application EAR with a third-party JAX-WS on Application Server:

• The WebSphere runtime restricts the usage of application modules that use both • IBM’s JAX-WS implementation and an external JAX-WS implementation in the

same application EAR. You can use the IBM JAX-WS implementation or an external implementation in a single application EAR, but not both. This limitation ensures that the Application Server runtime does not conflict with the external third-party JAX-WS implementation.

• Most of the external third-party JAX-WS runtimes include various JAR libraries, and some of those are already loaded by the Application Server runtime, causing conflicts. If you try to deploy an application with an external JAX-WS

implementation and there is a conflicting JAR file in the application, you’ll have to remove the conflicting JARs. Some of these conflicts are described in the sections Troubleshoot Axis2 deployment and Troubleshoot CXF application deployment. Following are the JARs known to conflict with the Application Server runtime:• saaj-api.jar• saaj-impl.jar• xalan.jar• xercesImpl.jar• xml-apis.jar• jaxb-api.jar• jaxb-impl.jar

• Once an application with third-party JAX-WS runtime is deployed on Application Server, it won’t be recognized as a service client or provider and therefore users won’t be able to attach application level policy sets. Users will have to rely on external runtimes to support Quality of Service (QoS). Following is a list of Application Server features that users won’t be able to use when they choose to de-ploy an application that uses third-party JAX-WS implementations:

• WS-Security, WS-RM, WS-Transaction, policy sets • WSDM • JNDI lookup to retrieve JAX-WS service or port instance • Fine-grained administration of services and endpoints

Required configuration changesThe following configuration changes are required to use a third-party JAX-WS runtime.

Class loader configurationWebSphere Application Server V6.1made several changes to the class loading mechanism. The majority of these changes are related to the use of the Open Services Gateway Initia-tive (OSGi) and the use of the cass loading hierarchy. When using third-party runtimes that are embedded in a WAR file, you need to configure WebSphere to use proper class loading hierarchies so that the third-party runtime and application build on these runtimes is proper-ly loaded and configured. Figure 1 shows the class loader hierarchy in WebSphere Applica-tion Server 6.1.

For more information on class loaders, see WebSphere Applicaton Server V6.1: Class Loader Problem Determination (PDF).

When using third-party JAX-WS runtimes, you need to make the following changes:• For Axis2, ensure that the runtime JARs located in the WEB-INF/lib folder and the cus-

tomer application under WEB-INF/Servicejars or WEB-INF/Services are in a WAR module class loader for the application and runtime to work correctly.

• For Axis2, Apache CXF, and Metro applications, you must select the proper class load-ing order so the JAR files from WAR module class loader are picked up before any JARs from other WebSphere Application Server class loaders are picked up.

We’ll cover these configuration changes in detail in the WAR deployment sections for each third-party runtime.

Class loader policy changes• In order to use an external JAX-WS runtime, you’ll need to change the class loader Or-

der policy in Application Server at the module level. For V6.1, this policy needs to be set to “Classes loaded with application class loader First.”

• For third-party runtimes such as Axis2, CXF, and Metro, you need to change the WAR class loader policy to “Single class loader for application” along with “Classes loaded with application class loader First.”

Changing the class loader policy as described ensures that the external third-party JAX-WS runtime and its dependent JAR files are first in the class loader search path, so that Application Server will use the third-party implementation.

• In order to deploy and run applications with third-party JAX-WS runtimes, you need to configure Application Server to turn off Web services annotation scanning. The IBM JAX-WS engine interferes with external runtimes when it does annotation scanning during deployment of WAR modules. Annotation scanning can be turned off at appli-cation level or at server level. To do this, complete the steps in Disabling IBM JAX-WS implementation.

Building and deploying an Axis2 Web services applica-tionThis section describes the steps to build, deploy, and run an Axis2 Web services application, as well as how to troubleshoot potential problems.

Build the Axis2 applicationTo build an Axis2 application, do the following:

1. Download the latest release of the Axis2 runtime.2. The Axis2 runtime is packaged as a WAR called axis2.war, which can be imported

into Rational Application Developer (hereafter Application Developer) as a dynamic Web project. When you import the axis2.war into Application Developer, you’ll notice that the WebContent/WEB-INF/lib has all the dependent jars that you’ll need to build an Axis2 application.

3. Create a new Java project in Application Developer. Update the build path to add a Web application library and point it to the imported axis2.war.

4. Follow the instructions in the Axis2 documentation to build a JAX-WS Web service application.

5. Package your service as a JAR file, then create a folder called WebContent/WEB-INF/servicejars under axis2.war, as shown below, and place the packaged jar in the new folder.

6. Follow the instructions in Deploy the Axis2 WAR to deploy axis2.war.

Note: IBM recommends this as the preferred method of service deployment for JAX-WS applications. The steps that describe deploying Axis2 war files use this approach. However, you can also package your application as an Axis2 AAR file. If you’re using AAR files, ensure that the META-INF/Services.xml file contains the correct metadata information. The following shows sample services.xml content:

<serviceGroup> <service name="EchoMessageService"> <description> Hello Service </description> <messageReceivers> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out" class="org.apache.axis2.jaxws.server.JAXWSMessageReceiver"/> </messageReceivers> <parameter locked="false" name="ServiceClass">org.test.addnum-ber.AddNumbersImpl </parameter> </service></serviceGroup>

If you’re packaging your Axis2 application as an AAR file, you can lace the AAR file in the WebContent/WEB-INF/Services folder of the imported Axis2.war, as shown below, and update the Service.list file with the name of the AAR file. Or, you can de-ploy the axis2.war file as described in Deploy the Axis2 WAR and follow the instruc-tions in the link Deploy the application using Axis2 administration.

Deploy the Axis2 WARComplete the following steps to deploy an Axis2 runtime on Application Server V6.1:

1. Turn off Web services annotation scanning as described in Disabling IBM JAX-WS implementation.

2. If you are using the servicejars folder to host Axis2 JAX-WS applications, add ser-vicejars/<application.jar> to the classpath, so the Application Server class loaders can pick up the JAX-WS service implementation and generated artifacts. To add the service jar to the classpath, edit META-INF/MANIFEST.MF and add the following:

Class-Path: axis2.war/WEB-INF/servicejars/<applicationname>.jar

3. Open the Application Server administrative console and select Applications => Application Types => WebSphere enterprise applications, as shown below.

4. Click Install as shown below.

5. Follow the wizard and install the axis2.war file that was downloaded from the Apache Web site.

6. Select Class loading and update detection, as shown below.

7. Select Classes loaded with application class loader first for Class loader order and Single class loader for application for WAR class loader policy, as shown below.

8. Go to the general properties of the module file, and select Classes loaded with application class loader first for Class loader order, as shown below.

9. Click Apply and save your changes, then restart the server and ensure that the ap-plication has deployed and started successfully.

The class loading configuration you did in the previous steps yields the class loader hi-erarchy shown below. As you can see, the Application Server module class loader is at the top of the hierarchy and contains WEB-INF/Lib and WEB-INF/classes in its class

path. This ensures that the Axis2 runtime JARs are picked up before any WebSphere JARs.

Note: In some cases, when building Web services from a Java class (bottom-up Web services development), it may note be necessary to follow steps 6 and 7 to modify the Class loading and update detection. This is true when these simple applications don’t have generated artifacts and the annotated Web service implementation classes are in the module class path.

Deploy the application using Axis2 administration

Note: We recommend you use the servicejars method described above to deploy Axis2 ap-plications.

Complete the following steps to deploy an Axis2 Web services application using the Axis administration screen in your browser:

1. First complete the steps to deploy the Axis2 runtime on WebSphere, as described in Deploy the Axis2 WAR.

2. Point your Web browser to http://localhost:9080/axis2-admin/, as shown below. Change the default port number of 9080 as needed. Note that in this example, the context-root for axis2.war was “/” but you can choose to use axis2 as the context-root, in which case the URL would be http://localhost:9080/ax-is2/axis2-admin/.

3. Enter the username and password for the administrator screen. The user and password are located in the axis2.xml file that was deployed with the axis2.war.

4. Select Upload Service, as shown below.

5. Browse to the Axis2 AAR file you want to deploy and click upload.

6. If the file deploys successfully, you’ll see the following message.

7. Select Available Services to verify that the service is available.

8. Execute the Axis2 JAX-WS client to invoke the service.

Troubleshoot Axis2 deployment While testing Axis2 JAR file deployment and execution, we identified the following issues.

Error message: The system is attempting to engage a module that is not available: addressing

This problem indicates that Axis2 configuration has the addressing module enabled and the addressing module MAR file cannot be read or is not in the classpath. To fix this, do the following:

1. Make sure you have correctly completed the steps in the Deploy the Axis2 WAR.2. If you don't intend to use the addressing module, comment out the addressing

module <module ref="addressing"/> in WEB-INF\conf\axis2.xml file in axis2.war.

3. If you want to use addressing and you have followed the deployment steps described above, add the Addressing<version>.mar file located in

WEB-INF/modules to the class path by editing META-INF/MANIFEST.MF and adding the following line:

Class-Path: axis2.war/WEB-INF/modules/addressing-1.4.1.mar

Then redeploy axis2.war as described in Deploy the Axis2 WAR. 4. After redeploying axis2.war, ensure that the addressing mar is in the WAR module

class path as shown below.

After making these changes, the Axis2 application should start with no addressing er-rors.

Error message: java.xml.bind.UnmarshalException

This message ends with “Expected elements are (none)”. This problem is reported when JAX-WS generated artifacts are not found by the JAXBContext. It indicates that the deployed Axis2 JAX-WS service jars are not in the Application Server class path and, therefore, cannot be found. The best way to resolve this problem is to add the Axis2 JAX-WS service jars to your class path by editing META-INF/MANIFEST.MF in axis2.war, and adding the following:

Class-Path: axis2.war/WEB-INF/servicejars/<applicationname>.jar

Commons-logging implementation for Axis2 application doesn’t work

In some cases, we found that the commons-logging implementation didn’t work for applications deployed in the servicejars folder.

WebSphere ships the file commons-logging.properties, which is located in the class loader path. Therefore, this is the properties file that WebSphere picks up by default. It also ships with the log implementation set to JDK14 logging (org.apache.commons.logging.Log=org.apache.commons.logging.impl.JDK14Logger), causing problems when you try to implement commons-logging in Axis2 applications.In some cases, we found that the commons-logging implementation didn’t work for applications deployed in the servicejars folder.

To ensure that commons-logging works:

1. Make sure you have correctly completed the steps in Deploy the Axis2 WAR.2. Ensure that commons-logging.properties and log4j.properties are located in

Axis2.war WEB-INF/Classes folder.3. Ensure your log4j.properties file is configured correctly.4. Modify Commons-logging.properties to have priority=1. The priority flag was

introduced in commons-logging 1.1 to allow ordering based on the priority. This flag ensures that applications commons-logging takes precedence over WebSphere's commons-logging.properties file.

After making these changes, commons-logging should work from Axis2 applications.

Conflicting axis2-saaj-<version>.jarAfter following the steps to deploy an Axis application on Application Server V6.1.0.29, we encountered an error when trying to generate WSDL by clicking the AddNumbers service on the Axis2 administration screen as shown below.

After the failed attempt to generate the WSDL, following errors where seen in the Web-Sphere trace.log:

It’s evident that the “org.apache.axis2.saaj.SAAJMetaFactoryImpl incompatible with javax.xml.soap.SAAJMetaFactory” error message is the result of Axis2 SAAJ problems.

If you don't plan to use Axis2 SAAJ in your application, we recommend that you remove the axis2-saaj-<version>.jar and axis2-saaj-api-<version>.jar files from WEB-INF/lib folder of the axis2.war file and redeploy the service.

If you plan to use Axis2 SAAJ in your application, you’ll need to resolve this issue by setting up class loading in Application Server as described in Deploy the Axis2 WAR, so the SAAJMetaFactoryImpl and SAAJMetaFatory interfaces are loaded from a single class loader. For more information on how to debug the problem, refer to WebSphere Application Server V6.1: Class Loader Problem Determination.

JAXB error: java.lang.NoClassDefFoundError: com.sun.xml.bind.-DatatypeConverterImpl

The above exception contains the following caused by statement:

Caused by: java.lang.ClassCastException: org.apache.xerces.jaxp.datatype-.DatatypeFactoryImpl incompatible with javax.xml.datatype.DatatypeFactory

at javax.xml.datatype.DatatypeFactory.newInstance(Unknown Source)at com.sun.xml.bind.DatatypeConverterImpl.<clinit>(DatatypeConvert-

erImpl.java:743)

This is a classloader limitation. This issue occurs only when a ?wsdl call is used to generate WSDL documentation on Axis2 Server. The problem is that Application Server hips Xerces and Xalan implementations in java/jre/lib/xml.jar. The xml.jar classes are loaded by JDKClassloader, while the xerces<version>.jar packaged in WEB-INF/lib is loaded using CompundClassloader, causing the exception.

This issue can’t be resolved by removing xerces<version>.jar and xml-api<version>.jar from the WAR modules WEB-INF/lib folders, because this will cause the Axis application

to fail with JAXB errors. Application Server lists this as a limitation. Users should not use ?wsdl calls to access WSDL from their clients, instead the WSDL should be packaged with the client applications.

In some scenarios, we found that Axis2 applications using a ?wsdl call caused fatal errors and required restarting of the Application Server.

Exception when using javax.xml.transform.TransformerFactoryDuring a ?wsdl call from the client we encountered the following error in the application server trace.log.

The error “java.lang.ClassCastException: com.ibm.xtq.xslt.jaxp.compiler.TransformerFac-toryImpl incompatible with javax.xml.transform.TransformerFactory” occurs because Application Server does not use javax.xml.transform.TransformerFactory defined in the META-INF/services file of xalan-<version>.jar.

You can resolve this issue by creating a jaxp.properties file in <WAS_HOME>\as\java\jre\lib and adding the following properties, as shown below.

Adding the javax.xml.transform.TransformerFactory=org.apache.xalan.proces-sor.

TransformerFactoryImpl property ensures that proper transform factory is used by the Axis2 application.

Building and deploying a CXF Web services application This section describes the steps to build, deploy, and run a CXF Web services application, as well as how to troubleshoot potential problems.

Build the CXF applicationTo build a CXF application, do the following:

1. Download CXF version 2.2.1. 2. Use the Application Developer Create a Dynamic Web Project function and copy

all the dependent files from <apache-cxf-version>/lib into the Web module’s WebContent/WEB-INF/lib folder in your Application Developer environment. You may choose not to copy all the library files from the CXF installation. You can get a list of the dependent files from Apache CXF documentation.

3. Build the Web service application in the above Web module. For more information on how to create a Web service using the CXF runtime, refer to the CXF documentation.

4. Once you’ve built your application, export the ear file from Application Developer and follow the steps in the next section to deploy the application.

Deploy the CXF applicationTo deploy a CXF application, do the following:

1. Turn off Web services annotation scanning as described in Disabling the IBM JAX-WS implementation.

2. Open the Application Server administrative console and select Applications => Application Types => WebSphere enterprise applications, as shown below.

3. Click Install as shown below.

4. Use the wizard to install the exported EAR file from Application Developer. After you’ve installed the file, you’ll see the following:

5. Ensure that the application’s “class loader first” policy is used. This policy ensures that all the Web application libraries will be installed first in the classpath, thereby ensuring that the CXF Web Services provider is used instead of the IBM Web services provider. To do this, go to the General Properties of the module file and change the Class loader order to Classes loaded with application class loader first, as shown below.

6. Click Apply and save your changes.

7. Restart the server and make sure that the application has deployed and started suc-cessfully.

Troubleshoot CXF application deployment

When deploying and executing the CXF application, we encountered the following error message: “java.lang.ClassCastException: org.apache.cxf.transport.servlet.CXFServlet in-compatible with javax.servlet.Servlet.”

This occurs because the CXF runtime ships with a Servlet 2.5 complaint JAR, but WebSphere Application Server V6.1.0.29 supports only a Servlet 2.4 specification. You can resolve this problem by removing geronimo-servlet_2.5_spec-1.2.jar, which is provided with the CXF 2.2.2 JAR, from the WEB-INF/lib folder of the WAR file.

Building and deploying a Metro Web services application This section describes the steps to build, deploy, and run a CXF Web services application, as well as how to troubleshoot potential problems.

Build the Metro applicationTo build a Metro application, complete the following steps:

1. Download Metro 1.5. Follow the instructions on the web site to execute the downloaded JAR.

2. Metro 1.5 comes with a sample, located in the metro/samples folder. For our purposes, we’ll use the samples/fromwsdl. Create the server side artifacts for this sample by running the Ant build script provided in the sample. Enter the following command to create the server artifacts:

cd <METRO_HOME/samples/fromwsdlant server

3. This creates a WAR file called jaxws-fromwsdl.war in the folder samples/fromwsdl/build/war. We’ll use this WAR file to make the application com-patible with Application Server.

4. Using Application Developer, create a dynamic Web project called MetroOnWAS and import the file jaxws-fromwsdl.war in to the project. The WAR file does not in-clude the source for the AddNumbersImpl.java, but if needed you can import that from the samples\fromwsdl\src\fromwsdl\server folder.

5. Update the WAR module and copy all the JAR files from <METRO_HOME>/lib into the Web module’s WebContent/WEB-INF/lib folder in your Application

Developer environment. 6. Modify the AddNumbersimpl.java as desired. Your Metro sample server-side

artifacts are ready to deploy.7. Once you’ve built your application, export MetroOnWAS from Application

Developer and follow the steps in the next section to deploy the application.

Deploy the Metro applicationTo deploy a Metro application, complete the following steps:

1. Turn off Web services annotation scanning as described in Disabling the IBM JAX-WS implementation.

2. Open the Application Server administrative console and select Applications => Application Types => WebSphere enterprise applications, as shown below.

3. Click Install as shown below.

4. Use the wizard to install the exported EAR file from Application Developer. After you’ve installed the file, you’ll see the following:

5. Ensure that the application’s “class loader first” policy is used. This policy ensures that all the Web application libraries will be installed first in the classpath, thereby ensuring that the CXF Web Services provider is used instead of the IBM Web services provider. To do this, go to the General Properties of the module file and change the Class loader order to Classes loaded with application class loader first, as shown below.

6. Click Apply and save your changes.7. Restart the server and make sure that the application has deployed and started

successfully.

Troubleshoot Metro application deployment When deploying and executing Metro application, we found that the following JARs can cause conflicts when added to the WEB-INF/lib folder of the Metro application WAR file:

• jaxb-api-<version>.jar• jaxb-impl-<version>.jar• jaxb-libs-<version>.jar• jaxb-xjc-<version>.jar• jaxrpc-api-<version>.jar• jaxrpc-impl-<version>.jar• jaxrpc-spi-<version>.jar• xerces-<version>.jar• xml-apis-<version>.jar

If any of these JARs are packaged by the Metro runtime, you’ll have to remove them as they will cause conflict with WebSphere.

Disabling the IBM JAX-WS implementationYou need to disable the IBM JAX-WS implementation to ensure that Application Server doesn’t scan for JAX-WS annotation and perform WebSphere-specific validations on the module that holds CXF application. You can turn off annotation scanning in one of two ways:

1. To turn off annotation scanning for just the deployed module, modify the module’s WebContent/META-INF/ MANIFEST.MF and add the following line DisableIBMJAXWSEngine: true.

2. To turn off annotation scanning for the entire server, use the administrative console to navigate to the Java Virtual Machine, as shown below.

3. As shown below, set the new JVM parameter to: Dcom.ibm.WebSphere.webser-vices.DisableIBMJAXWSEngine=true

SummaryIn this article you learned how to deploy a Web services application built using third-party JAX-WS runtimes like Apache Axis2 and CXF on WebSphere Application Server V7.0. When building JAX-WS Web services applications on WebSphere, we recommend using the JAX-WS implementation provided by Websphere Application Server. However; if you choose to use third-party runtime, you now have an understanding of how to do that and the limitations of doing so.

Resources• Using third-party JAX-WS applications in WebSphere Application Server V7

• WebSphere Application Server V7 Information Center

• WebSphere Application Server V7: Understanding Class Loaders (PDF)

• JSR 224: Java API for XML-Based Web Services (JAX-WS) 2.0

• Axis-based applications fail to work properly in WebSphere Application Server V5.0.2 (Tech Note)

• Axis2 JAX-WS Engine

• Sun Metro

• developerWorks WebSphere Web services and SOA zone : Technical resources, such as articles, tutorials, and downloads for WebSphere Web services solutions.

• developerWorks WebSphere Application Server zone : Technical resources, such as articles, tutorials, and downloads, on WebSphere Application Server.

About the authorNikhil Thaker is an Advisory Software Engineer with IBM Soft-ware Group, and a member of the WebSphere Application Server team that developed Web services JAX-WS implementation. He has more than nine years of experience in Enterprise Application Integration, and has focused on Web services for the past four years. He has worked with various IBM customers as an IT Spe-cialist in Enterprise Application Integration in IBM Global Ser-vices. His industry exposure includes automotive, health care, telecommunication and utilities. You can reach Nikhil at nikhil.v.thaker@us.ibm.com.