test

The WSIT Tutorial

Creating a Web Service From Java

One way to create a web service application is to start by coding the endpoint in Java. If you are developing your Java web service from scratch or have an existing Java class you wish to expose as a web service, this is the most direct approach.

The Java API for XML Web Services (JAX-WS) 2.0 Specification, JSR-224, relies heavily on the use of annotations as specified in A Metadata Facility for the Java Programming Language (JSR-175) and Web Services Metadata for the Java Platform (JSR-181), as well as additional annotations defined by the JAX-WS 2.0 specification.

The web service is written as a normal Java class. Then the class and its exposed methods are annotated with the web service annotations @WebService and @WebMethod. The following code snippet shows an example:

@WebService
public class AddNumbersImpl {
    @WebMethod(action="addNumbers")
    public int addNumbers(int number1, int number2)
            throws AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException(
                    "Negative number can't be added!",
                    "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
    }
}

When developing a web service from scratch or based on an existing Java class, WSIT features are enabled using a configuration file. That file, wsit-package.service.xml, is written in WSDL format. An example configuration file can be found in the accompanying samples:

wsit-enabled-fromjava/etc/wsit-fromjava.server.AddNumbersImpl.xml

The settings in the wsit-package.service.xml file are incorporated dynamically by the WSIT runtime into the WSDL it generates for the web service. So when a client requests the web service’s WSDL, the runtime embeds any publicly visible policy assertions contained in the wsit-package.service.xml file into the WSDL. For the example wsit-fromjava.server.AddNumbersImpl.xml in the sample discussed in this tutorial, the Addressing and Reliable Messaging assertions are part of the WSDL as seen by the client.

Note –

The wsit-package.service.xml file must be in the WEB-INF sub-directory of the application’s WAR file when it is deployed to the web container. Otherwise, the WSIT run-time environment will not find it.

To create a web service from Java, create the following files:

Web Service Implementation Java File

The sample files define a web service that takes two integers, adds them, and returns the result. If one of the integers is negative, an exception is thrown.

The starting point for developing a web service that uses the WSIT technologies is a Java class file annotated with the javax.jws.WebService annotation. The @WebService annotation defines the class as a web service endpoint.

The following file (wsit-enabled-fromjava/src/fromjava/serverAddNumbersImpl.java) implements the web service interface.package fromjava.server; 

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

@WebService
public class AddNumbersImpl {
    @WebMethod(action="addNumbers")
    public int addNumbers(int number1, int number2)
            throws AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException(
                    "Negative number cannot be added!",
                    "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
    }
}
Note –

To ensure interoperability with Windows Communication Foundation (WCF) clients, you must specify the action element of @WebMethod in your endpoint implementation classes. WCF clients will incorrectly generate an empty string for the Action header if you do not specify the action element.

wsit-package.service.xml File

This file is the WSIT configuration file. It defines which WSIT technologies are enabled in the web service. The snippet shown below illustrates how to enable the WSIT reliable messaging technology in a wsit-package.service.xml file.

<wsp:Policy wsu:Id="AddNumbers_policy">
    <wsp:ExactlyOne>
        <wsp:All>
            <wsaw:UsingAddressing/>
            <wsrm:RMAssertion>
                <wsrm:InactivityTimeout Milliseconds="600000"/>
                <wsrm:AcknowledgementInterval Milliseconds="200"/>
            </wsrm:RMAssertion>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

For a complete example of a wsit-package.service.xml file, see the wsit-enabled-fromjava example. You can use the wsit-package.service.xml file provided in the example as a reference for creating your own wsit-package.service.xml file.