Application Overview

The sample application referred in this article is a simple calculator which performs addition of two integers. The client application referred here is not a J2EE application. It is a regular Java client which will call a web service to carry out the application functionality. Web service is exposed as a Servlet in the Geronimo application server.

Service implementation

The Calculator interface defines the Service Endpoint Interface (SEI) for the Web Service.

Calculator.java

package org.apache.geronimo.samples.jws;

import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.WebParam;

@WebService
public interface Calculator {

    @WebMethod
    public int add(@WebParam(name = "value1") int value1,
                   @WebParam(name = "value2") int value2);

}

The CalculatorService class implements the Web Service business logic. It implements all the methods defined in the SEI. The class does not need to implement the Calculator interface but must reference it through the @WebService.endpointInterface annotation. This class will be exposed as a Servlet through web.xml file even though it does not extend the javax.servlet.Servlet class.
The context variable marked with the @Resource annotation will be injected at runtime. The WebServiceContext can be used to obtain the message context and security information relative to the call.

CalculatorService.java

package org.apache.geronimo.samples.jws;

import javax.annotation.Resource;
import javax.jws.WebService;
import javax.xml.ws.WebServiceContext;

@WebService(endpointInterface = "org.apache.geronimo.samples.jws.Calculator")
public class CalculatorService implements Calculator {

    @Resource
    private WebServiceContext context;

    public int add(int value1, int value2) {
        System.out.println("User Principal: " + context.getUserPrincipal());
        return value1 + value2;
    }
}

The web.xml descriptor is used to deploy the Web Service.

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:calc="urn:geronimo-samples-jws" 
                xmlns="http://java.sun.com/xml/ns/javaee"
		version="2.5">
	<servlet>
		<display-name>CalculatorService</display-name>
		<servlet-name>CalculatorService</servlet-name>
		<servlet-class>
			org.apache.geronimo.samples.jws.CalculatorService
		</servlet-class>
	</servlet>
	
	<servlet-mapping>
		<servlet-name>CalculatorService</servlet-name>
		<url-pattern>/calculator</url-pattern>
	</servlet-mapping>
	
</web-app>

Currently, the web.xml deployment descriptor is required to configure the service but it will not be necessary in the future.

The geronimo-web.xml descriptor is optional but it is used in this sample to specify the module name.

geronimo-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <dep:moduleId>
      <dep:groupId>org.apache.geronimo.samples.jws</dep:groupId>
      <dep:artifactId>Calculator</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
</web-app>

The following WSDL file describes the Web Service:

CalculatorService.wsdl

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="Calculator"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://jws.samples.geronimo.apache.org"
    xmlns:tns="http://jws.samples.geronimo.apache.org">

    <wsdl:types>
        <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                    xmlns="http://jws.samples.geronimo.apache.org" 
                    targetNamespace="http://jws.samples.geronimo.apache.org"
                    attributeFormDefault="unqualified" elementFormDefault="qualified">

             <xsd:element name="add">
                <xsd:complexType>
                   <xsd:sequence>
                      <xsd:element name="value1" type="xsd:int"/>
                      <xsd:element name="value2" type="xsd:int"/>
                   </xsd:sequence>
                </xsd:complexType>
             </xsd:element>

             <xsd:element name="addResponse">
                <xsd:complexType>
                   <xsd:sequence>
                      <xsd:element name="return" type="xsd:int"/>
                   </xsd:sequence>
                </xsd:complexType>
             </xsd:element>
        </xsd:schema>
    </wsdl:types>
  
    <wsdl:message name="add">
       <wsdl:part name="add" element="tns:add"/>
    </wsdl:message>

    <wsdl:message name="addResponse">
       <wsdl:part name="addResponse" element="tns:addResponse"/>
    </wsdl:message>

    <wsdl:portType name="CalculatorPortType">
       <wsdl:operation name="add">
         <wsdl:input name="add" message="tns:add"/>
         <wsdl:output name="addResponse" message="tns:addResponse"/>
       </wsdl:operation>
    </wsdl:portType>
        
    <wsdl:binding name="CalculatorSoapBinding" type="tns:CalculatorPortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        
        <wsdl:operation name="add">
            <soap:operation soapAction="add" style="document"/>
            <wsdl:input name="add">
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output name="addResponse">
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
                
    </wsdl:binding>
  
    <wsdl:service name="Calculator">
        <wsdl:port name="CalculatorPort" binding="tns:CalculatorSoapBinding">
            <soap:address location="http://localhost:8080/jaxws-calculator-1.0/calculator"/>
            <wswa:UsingAddressing xmlns:wswa="http://www.w3.org/2005/08/addressing/wsdl"/>
        </wsdl:port>
    </wsdl:service>
      
</wsdl:definitions>

The webservices.xml file describes the Web Service. It configures the WSDL file for the service, the name of the WSDL port that the service implements, the SEI, and also contains a link to the Servlet that implements the business logic.

webservices.xml

<?xml version="1.0" encoding="UTF-8"?>
<webservices xmlns="xmlns="http://java.sun.com/xml/ns/javaee" version="1.2">
 <webservice-description>
  <webservice-description-name>CalculatorService</webservice-description-name>
  <wsdl-file>CalculatorService.wsdl</wsdl-file>
  <port-component>
	  <port-component-name>CalculatorServicePort</port-component-name>
	  <wsdl-port>CalculatorPort</wsdl-port>
	  <service-endpoint-interface>
                org.apache.geronimo.samples.jws.Calculator
	  </service-endpoint-interface>
	  <service-impl-bean>
	      <servlet-link>CalculatorService</servlet-link>
	  </service-impl-bean>
  </port-component>
 </webservice-description>
</webservices>

Currently, the webservices.xml deployment descriptor is required to configure the service but it will not be necessary in the future.

Client implementation

The CalculatorClient class is a client for the CalculatorService Web Service. The client automatically generates a dynamic proxy from the service WSDL and the SEI. The dynamic proxy is then be used to invoke the service.

CalculatorClient.java

package org.apache.geronimo.samples.jws.client;

import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;

import org.apache.geronimo.samples.jws.Calculator;

public class CalculatorClient {

    public static void main(String[] args) throws Exception {
        int value1 = Integer.parseInt(args[0]);
        int value2 = Integer.parseInt(args[1]);

        int sum = add(value1, value2);

        System.out.println("Sum of " + value1 + " and " + value2 + " is " + sum);
    }

    public static int add(int value1, int value2) throws Exception {
        URL url = new URL("http://localhost:8080/jaxws-calculator-1.0/CalculatorService.wsdl");
        QName qname = new QName("http://jws.samples.geronimo.apache.org", "Calculator");
        Service service = Service.create(url, qname);
        
        Calculator calc = (Calculator)service.getPort(Calculator.class);
        
        return calc.add(value1, value2);
    }
}

Building and Deploying Sample Application

Download the Calculator application from the following link: calculator.zip

After extracting the zip file, the calculator directory is created.

Required Tools

The tools used for developing and building the Calculator sample application are:

Apache Maven 2.0.x

Apache Maven is used for building the Calculator application.

Apache CXF 2.0

Apache CXF provides JAX-WS support and is integrated with Geronimo.

This service requires the latest CXF code to be installed. Please see the CXF project web site for more information on obtaining and building the latest code.

Building

Compile Source Code

From command prompt execute the following command in the calculator/ folder:

mvn -Dmaven.test.skip=true install

After the code is successfully compiled a jaxws-calculator-1.0.war file will be created in the target subfolder.

Deploying

Deploy the jaxws-calculator-1.0.war using the Geronimo Console (http://localhost:8080/console):

Scroll to Deploy New from the Console Navigation panel.
Load jaxws-calculator-1.0.war from calculator/targer folder in to the Archive input box.
Press Install button to deploy application in the server.

Testing of the Sample Application

To test this sample service we are going to run the CalculatorClient application. From command prompt navigate to calculator/target/jaxws-calculator-1.0/WEB-INF/lib folder and give the following command:

java -jar jaxws-calculator-1.0.jar <num1> <num2>

For example:

~/geronimo/samples/calculator/target/jaxws-calculator-1.0/WEB-INF/lib$ java -jar jaxws-calculator-1.0.jar 12 35
Sum of 12 and 35 is 47