Saturday, July 12, 2008

A simple JAX-WS Web Service with Eclipse

Here I am ! this my first post on my technical blog.

For this one, I am going to show you how to create an HelloWorld WS with JAX-WS RI (2.1.3) and Eclipse (3.4). We will use a contract-first method (WSDL to Java) to develop this first WS. We will deploy the WS on Tomcat (6.0).

Creating an Eclipse Project
  • Select the menu File → Other...
  • Select Web → Dynamic Web Project
  • Specify paths and Tomcat as the target runtime
  • Once you have created the project, copy the jar files from the directory <JAXWS_ROOT>/lib to <ECLIPSE_PROJECT>/WebContent/WEB-INF/lib then refresh the eclipse project
Creating the WS configuration files

Now we are going to configure the different JAX-WS configuration files :
  • Create the file <ECLIPSE_PROJECT>/WebContent/WEB-INF/wsdl/HelloWorld.wsdl (WS contract) :
<definitions name="HelloWorld" targetNamespace="http://java-soa.blogspot.com/"
xmlns:tns="http://java-soa.blogspot.com/" xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

<!-- types -->
<types>
<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" targetNamespace="http://java-soa.blogspot.com/">
<element name="name" type="xsd:string" />
<element name="response" type="xsd:string" />
</xsd:schema>
</types>

<!-- messages -->
<message name="name">
<part name="in" element="tns:name" />
</message>
<message name="response">
<part name="out" element="tns:response" />
</message>

<!-- operations -->
<portType name="HelloWorldPortType">
<operation name="hello">
<input message="tns:name" />
<output message="tns:response" />
</operation>
</portType>

<!-- binding -->
<binding name="HelloWorldBinding" type="tns:HelloWorldPortType">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http"
style="document" />
<operation name="hello">
<soap:operation soapAction="" />
<input>
<soap:body use="literal" />
</input>
<output>
<soap:body use="literal" />
</output>
</operation>
</binding>

<!-- services -->
<service name="HelloWorldService">
<port name="HelloWorldPort" binding="tns:HelloWorldBinding">
<soap:address location="REPLACE_WITH_ACTUAL_URL" />
</port>
</service>
</definitions>
  • Create the file <ECLIPSE_PROJECT>/WebContent/WEB-INF/web.xml (Web deployment descriptor) :
<web-app version="2.4" mlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<description>HelloWorld</description>
<display-name>HelloWorld</display-name>
<listener>
<listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class>
</listener>
<servlet>
<description>JAX-WS endpoint - HelloWorld</description>
<display-name>HelloWorld</display-name>
<servlet-name>HelloWorldPort</servlet-name>
<servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>HelloWorldPort</servlet-name>
<url-pattern>/helloWorld</url-pattern>
</servlet-mapping>

</web-app>
  • Create the file <ECLIPSE_PROJECT>/WebContent/WEB-INF/sun-jaxws.xml (JAX-WS RI deployment descriptor) :
<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime' version='2.0'>
<endpoint
name="HelloWorld"
implementation="com.javasoa.ws.impl.HelloWorldPortTypeImpl"
wsdl="WEB-INF/wsdl/HelloWorld.wsdl"
service='{http://java-soa.blogspot.com/}HelloWorldService'
port='{http://java-soa.blogspot.com/}HelloWorldPort'
url-pattern="/helloWorld"/>
</endpoints>
Configuring WsImport

the command wsimport generates the different java classes from the wsdl.
  • Select the menu Run → External Tools → External Tools Configuration
  • Click on Program then on button
  • Specify the following informations :
    • Name : CreateClassJAXWS
    • Location : <JAXWS_ROOT>/bin/wsimport.[bat|sh]
    • Working Directory : ${project_loc}
    • Arguments : -keep -d ${project_loc}/src -p com.javasoa.ws ${resource_loc}
  • Click on Close button
Arguments description :
  • keep : without this argument, sources files are deleted after generation
  • d : source path
  • p : source files target package
Generating Web Service classes
  • Select the wsdl file
  • Select the menu Run → External Tools → CreateClassJAXWS
  • Refresh the eclipse project
If you have followed the instructions, JAX-WS classes have been created :
  • com.javasoa.ws.HelloWorldPortType : this class defines the web service interface. The different annotations (WebService,WebMethod,WebParam...) indicates the Web Service informations (JAX-WS annotation list).
  • com.javasoa.ws.HelloWorldService : this class provides client methods (we will not use this class in this tutorial).
  • com.javasoa.ws.ObjectFactory : this class contains for each XML element a method providing the corresponding Java object.
Implementing the Web Service
  • Create the class com.javasoa.ws.impl with the following contents :
package com.javasoa.ws.impl;

import javax.jws.WebService;

import com.javasoa.ws.HelloWorldPortType;

/**
* HelloWorld WS implementation.
*/
@WebService(endpointInterface = "com.javasoa.ws.HelloWorldPortType")
public class HelloWorldPortTypeImpl implements HelloWorldPortType {

/** suffix : hello. */
private static final String SUFFIX_HELLO = "Hello ";

/////////////////////////////////////////////////////////////////////////

/**
* Say hello to in.
*
* @param in name
*
* @return response
*/
@Override
public String hello(String in) {
return (SUFFIX_HELLO + in);
}

}
The endpointInterface annotation indicates in which class (interface) find the web services description.
Now the web service the ready ! we just need to deploy it on Tomcat.

Configuring Tomcat in Eclipse
  • Select the menu Window → Preferences → Server → Runtime Environments
  • Click on Add button
  • Select Apache Tomcat V6.0 then click on Next button
  • In Tomcat Installation directory, specify the tomcat root path
  • Click on Finish button then on Ok Button
  • Select the menu Window → Show View → Servers
Deploying the Web Service
  • In the Server view, right-click and select the menu New → Server
  • Select Apache Tomcat V6.0 then click on Next button
  • Select the HelloWorld project then click on Add → button
  • Click on Finish button
  • Right-click on the server then select the menu Start
To be sure that your web service is ready, verify, in a web browser, that the URL http://localhost:8080/HelloWorld/helloWorld?wsdl is available. If the wsdl file is displayed, that's right.

Testing the Web Service

For testing our first web service, we will use SoapUI web service client.
In SoapUI :
  • Select the menu File → New WSDL Project
  • Specify the following informations :
    • Project Name : HelloWorld
    • Initial WSDL : http://localhost:8080/HelloWorld/helloWorld?wsdl
  • Click on OK button : a default request is created.

Now you can put your name in the SOAP envelope and call the web service !

5 comments:

Anonymous said...

Hi ,
I am using Java 6 and I think, JAXWS libary files comes with Java6.

So I do not have any JAXWS_ROOT folder/setitng exist.

So could you please tell me, which files shall I need to copy/setup for Java 6/Tomcat6/Eclipise.

Also could you please explain Java to WSDL approach?

Grégory Le Bonniec said...

Hi Srini,

1. If you use Java 6, you will find wsimport in the bin directory. You don't have to copy lib in this case.

2. Concerning Java -> WSDL, the wsgen tool allows you to generate JAXB and WSDL file from a java class. I will try to do a post concerning this point during the next weeks.

Bye

Stells said...

Thank you very much for your concise instruction! It is great!

Gautam said...

Thanks for the post. Helped a lot !

Eran Smith said...

Amazing work. Needed it so badly . Thanks !
.net Obfuscator