Creating a Web Service

You can create a web service starting from Java code or starting from a WSDL file. The following sections describe each approach:

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, 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 cant 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.AddNumber-
sImpl.xml

The settings in the wsit-<package>.<service>.xml file are incorporated dynamically by the WSIT run-time into the WSDL it generates for the web service. So when a client requests the web service's WSDL, the run-time 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.

Creating a Web Service From WSDL

Typically, you start from WSDL to build your web service if you want to implement a web service that is already defined either by a standard or an existing instance of the service. In either case, the WSDL already exists. The JAX-WS wsimport tool processes the existing WSDL document, either from a local copy on disk or by retrieving it from a network address or URL. For an example of using a web browser to access a service's WSDL, see Verifying Deployment.

When developing a web service starting from an existing WSDL, the process is actually simpler than starting from Java. This is because the policy assertions needed to enable various WSIT technologies are already embedded in the WSDL file. An example WSDL file is included in the fromwsdl sample provided with this tutorial at: 

<INSTALL>/wsit-enabled-fromwsdl/etc/AddNumbers.wsdl

To Create a web service from WSDL, create the following source files:

The following files are standard files required for JAX-WS. Examples of these files are provided in the fromwsdl sample directory.

The build.xml and build.properties files are standard in any Ant build environment. Examples of these files are provided in the respective samples directories.

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

WSDL File

You can create a WSDL file by hand or retrieve it from an existing web service by simply pointing a web browser at the web service's URL. The snippet shown below illustrates how to enable the WSIT Reliable Messaging technology in a WSDL file. 

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

For a complete example of a WSDL file, see the AddNumbers.wsdl in the fromwsdl example. Another benefit of AddNumbers.wsdl file is that it shows how a WSIT-enabled WSDL is constructed. Therefore, you can use it as a reference when you create a WSDL file or modify an existing one.

Web Service Implementation File

The following file (AddNumbersImpl.java) shows how to implement a web service interface. 

package fromwsdl.server;

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

@WebService (endpointInterface=
    "fromwsdl.server.AddNumbersPortType")
public class AddNumbersImpl{
  @WebMethod(action="addNumbers")
  public int addNumbers (int number1, int number2)
      throws AddNumbersFault_Exception {
    if (number1 < 0 || number2 < 0) {
      String message = "Negative number cannot be added!";
      String detail = "Numbers: " + number1 + ", " + number2;
      AddNumbersFault fault = new AddNumbersFault ();
      fault.setMessage (message);
      fault.setFaultInfo (detail);
      throw new AddNumbersFault_Exception(message, fault);
    }
    return number1 + number2;
  }

  public void oneWayInt(int number) {
    System.out.println("Service received: " + number);
  }
}