Configure Tomcat 6 for JAX-WS

As a servlet container, Tomcat is not a full J2EE container hence requires some additional configuration in order to support JAX-WS. This article describes this configuration step-by-step:

1. Download a copy of the JAX-WS library – Instructions here were tested this on version 2.1.5 (https://jax-ws.dev.java.net/2.1.5/)
2. Copy the file JAXWS2.1.5-20081030.jar to an appropriate folder on your computer – say, /root/tools/ JAXWS2.1.5-20081030.jar
3. Execute the jar: java –jar JAXWS2.1.5-20081030.jar
4. This in effect unpacks the files contained in this jar. You should get a folder /root/tools/jaxws-ri containing the supporting libraries, docs, tools and samples. Let’s call this path $JAX-WS-HOME$.
5. Copy the jar files in $JAX-WS-HOME$/lib/ to the Tomcat (let’s call the install path for this $CATALINA_HOME$) library$CATALINA_HOME$/lib and $CATALINA_HOME$/shared/lib path.
6. Create an folder in the Tomcat installation directory called “endorsed”. The full path should be$CATALINA_HOME$/endorsed.
7. Copy the files “jaxb-api.jar” and “jaxws-api.jar” from the “$JAX_WS_HOME$/lib” to the “$CATALINA_HOME$/endorsed/”folder.
8. Edit the Tomcat configuration file “$CATALINA_HOME$/conf/catalina.properties” (You might want to take a backup before you edit it). There should be a property with the key “shared.loader”. Make sure the path $CATALINA_HOME$/shared/lib/*.jar is included in the comma separated list of paths in the value for this property. For example it could look like :shared.loader=/etc/tomcat/shared/lib/*.jar. That’s the main set of configuration that needs to be done.
9. Before running tomcat, ensure the following property is to be set on the script used to start tomcat:
   -Djava.endorsed.dirs=$CATALINA_HOME$\endorsed
10. This ensures the two jars we copied into the endorsed folder are picked up.
11. Start tomcat.

UPDATE: This post makes assumptions about your source and web-archive being correctly set up. When I was doing this, I was working in a Contract-First approach and I wrote a quick guide to that here. This covers how your web.xml and sun-jaxws.xml file should be done. When I get sometime I'll upload a redacted version of my code as it has some work stuff. Good luck!

Contract-First Web Services in practice - part 5 of 5 (Java / J2EE)

This is the last article in the series of 5 and today we're looking at contract first development in Java/J2EE. I've left this for last after considering PHP and NET due to the various application servers and technologies in which this is possible. Java is also my forte hence I'm not shying away from this challenge. We'll look at JAX-WS on J2EE and Tomcat.

JAX-WS / EE5 Application Servers

If you prefer the blue pill and like the neat, java 5+, annotation heavy, jaxws-does-everything-for-you alternate reality, then you're in for a treat. The JAX-WS RI is available in most J2EE servers. I've picked JBOSS (the 4.2.2 GA) which is what I was using for work. JBOSS ships with wstools in the bin directory. Run the command "wsconsume -k SampleService.wsdl". This creates client stubs and a server interface "com.kimenye.SampleServicePortType". This is the class to be implemented. Once this is done, create a web.xml file and create a servlet with the servlet-class as the implementation created. Package this as a web-archive, and pop it into the deploy directory of the app server.

Tomcat 6

Tomcat 6 is a servlet container and not a full J2EE container hence it is not compulsory for it to provide JAX-WS. See my post on how to configure Tomcat 6 to use JAX-WS. Follow the steps below to implement the sample service:

1. Use "wsimport" tool to create the service stubs. This tool is available from the bin directory of an unpacked JAX-WS installation. The full command to run is : wsimport -keep SampleService.wsdl
2. Create a web application in your preffered IDE. Copy the artifacts generated from the wsimport into your source. Implement the port type interface. For our example this class will be com.kimenye.ProvisionServicePortType. Compile the implementations and the generated classes.
   
3. Copy the wsdl into a folder named wsdl under the WEB-INF directory.
4. Create a file named sun-jaxws.xml in the WEB-INF directory and fill in the content below:
   view plaincopy to clipboardprint?

   1. <endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
   2. version="2.0">
   3. 
      
   4. <endpoint name="SampleService" interface="com.applicationsnet.service.soap.SampleServicePortType"
   5. implementation=com.kimenye.SampleServiceImpl" wsdl="WEB-INF/wsdl/SampleService.wsdl"
   6. service="{http://kimenye.com/}SampleService" port="{http://kimenye.com/}SampleServicePort"
   7. url-pattern="/SampleService" />
   8. 
      
   9. </endpoints>

   <endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"<br /> version="2.0"><br /><br /> <endpoint name="SampleService" interface="com.applicationsnet.service.soap.SampleServicePortType"<br /> implementation=com.kimenye.SampleServiceImpl" wsdl="WEB-INF/wsdl/SampleService.wsdl"<br /> service="{http://kimenye.com/}SampleService" port="{http://kimenye.com/}SampleServicePort"<br /> url-pattern="/SampleService" /><br /><br /></endpoints>
5. Edit the web.xml file to include the content below:
   view plaincopy to clipboardprint?

   1. <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   2. xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
   3. version="2.4">
   5. <description>sample</description>
   6. <display-name>sample</display-name>
   8. <listener>
   9. <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class>
   10. </listener>
   12. <servlet>
   13. <description>Sample End-Point</description>
   14. <display-name>Sample End-Point</display-name>
   15. <servlet-name>SampleServicePortType</servlet-name>
   16. <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
   17. <load-on-startup>1</load-on-startup>
   18. </servlet>
   20. <servlet-mapping>
   21. <servlet-name>SampleServicePortType</servlet-name>
   22. <url-pattern>/SampleService</url-pattern>
   23. </servlet-mapping>
   24. </web-app>

   <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br /> xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"<br /> version="2.4"><br /><br /> <description>sample</description><br /> <display-name>sample</display-name><br /><br /> <listener><br /> <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class><br /> </listener><br /><br /> <servlet><br /> <description>Sample End-Point</description><br /> <display-name>Sample End-Point</display-name><br /> <servlet-name>SampleServicePortType</servlet-name><br /> <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class><br /> <load-on-startup>1</load-on-startup><br /> </servlet><br /> <br /> <servlet-mapping><br /> <servlet-name>SampleServicePortType</servlet-name><br /> <url-pattern>/SampleService</url-pattern><br /> </servlet-mapping><br /></web-app>
6. Create the web-archive file and copy it to your tomcat web applications directory.
7. Edit the startup script for tomcat to include the property : -Dcom.sun.xml.ws.fault.SOAPFaultBuilder.disableCaptureStackTrace=false – This is related to how the soap faults are formatted and is IMPORTANT!
8. Start tomcat and enjoy!