Chapter 14. WSIT Example Using a Web Container Without NetBeans IDE

The Java code and configuration files for the examples used in this tutorial assume that the web container is listening on IP port 8080. Port 8080 is the default listener port for both GlassFish (domain1) and Tomcat. If you have changed the port, you must update the port number in the following files before building and running the examples:

Before you build and deploy the web service and its client, set one of the following environment variables:

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 Jakarta XML Web Services Specification relies heavily on the use of annotations as specified in A Metadata Facility for the Java Programming Language (JSR-175) and Jakarta Web Services Metadata, as well as additional annotations defined by the Jakarta XML Web Services 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.

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

import jakarta.jws.WebService;
import jakarta.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;
    }
}

<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>

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 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:

tut-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 Jakarta XML Web Services. 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.

<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>

import jakarta.jws.WebService;
import jakarta.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);
    }
}

To build and deploy the web service, open a terminal window, go to the tut-install/wsit-enabled-fromjava/ directory and type the following:

This command calls the server target in build.xml, which builds and packages the application into a WAR file, wsit-enabled-fromjava.war, and places it in the wsit-enabled-fromjava/build/war directory. The ant server command also deploys the WAR file to the web container.

The ant command calls multiple tools to build and deploy the web service. The wsgen tool processes the annotated source code and invokes the compiler itself, resulting in the class files for each of the Java source files. In the wsit-enabled-fromjava example, the Ant target build-server-java in build.xml handles this portion of the process. Next, the individual class files are bundled together along with the web service’s supporting configuration files into the application’s WAR file. It is this file that is deployed to the web container by the deploy target.

During execution of the server target, you will see a warning message. The message refers to “Annotation types without processors”. The warning is expected and does not indicate an abnormal situation. The text is included here for reference:

build-server-java:
   [apt] warning: Annotation types without processors:
        [jakarta.xml.bind.annotation.XmlRootElement,
        jakarta.xml.bind.annotation.XmlAccessorType,
        jakarta.xml.bind.annotation.XmlType,
         jakarta.xml.bind.annotation.XmlElement]
   [apt] 1 warning

To build and deploy the web service, open a terminal window, go to the tut-install/wsit-enabled-fromwsdl/ directory, and type the following:

ant server

This command calls wsimport, which takes the WSDL description and generates a corresponding Java interface and other supporting classes. Then the Java compiler is called to compile both the user’s code and the generated code. Finally, the class files are bundled together into the WAR file. To see the details of how this is done, see the build-server-wsdl and create-war targets in the wsit-enabled-fromwsdl/build.xml file.

As a convenience, invoking the ant server command builds the web service’s WAR file and immediately deploys it to the web container. However, in some situations, such as after undeploying a web service, it may be useful to deploy the web service without rebuilding it.

For both scenarios, wsit-enabled-fromjava and fromwsdl, the resulting application is deployed in the same manner.

The following sections describe how to deploy on the different web containers:

ant deploy

ant -Duse.tomcat=true deploy

A basic test to verify that the application has deployed properly is to use a web browser to retrieve the application’s WSDL from its hosting web container. The following URLs retrieve the WSDL from each of the two example services. If you are running your web browser and web container on different machines, you need to replace localhost with the name of the machine hosting your web service.

If the browser displays a page of XML tags, the web service has been deployed and is working. If not, check the web container log for any error messages related to the sample WAR you have just deployed. For GlassFish, the log can be found at as-install/domains/domain1/logs/server.log. For Apache Tomcat, the appropriate log file can be found at tomcat-home/logs/catalina.out.

To create a client from Java, you must create the following files:

The build.xml and build.properties files are standard in any Ant build environment. Examples of these files are provided in the wsit-enabled-fromjava sample directory.

package fromjava.client;

import com.sun.xml.ws.Closeable;
import java.rmi.RemoteException;

public class AddNumbersClient {
    public static void main (String[] args) {
        AddNumbersImpl port = null;
        try {
            port = new AddNumbersImplService().getAddNumbersImplPort();
            int number1 = 10;
            int number2 = 20;
            System.out.printf ("Invoking addNumbers(%d, %d)\n",
                    number1, number2);
            int result = port.addNumbers (number1, number2);
            System.out.printf (
                    "The result of adding %d and %d is %d.\n\n",
                     number1, number2, result);

            number1 = -10;
            System.out.printf ("Invoking addNumbers(%d, %d)\n",
                    number1, number2);
            result = port.addNumbers (number1, number2);
            System.out.printf (
                    "The result of adding %d and %d is %d.\n",
                     number1, number2, result);
        } catch (AddNumbersException_Exception ex) {
            System.out.printf (
                    "Caught AddNumbersException_Exception: %s\n",
                     ex.getFaultInfo ().getDetail ());
        } finally {
            ((Closeable)port).close();
        }
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bindings
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    wsdlLocation="http://localhost:8080/wsit-enabled-fromjava/ 
        addnumbers?wsdl"
    xmlns="https://jakarta.ee/xml/ns/jaxws">
    <bindings node="wsdl:definitions">
        <package name="fromjava.client"/>
    </bindings>
</bindings>

To create a client from WSDL, you must create the following files:

The build.xml and build.properties files are standard in any Ant build environment. Examples of these files are provided in the fromwsdl sample directory.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bindings
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    wsdlLocation="http://localhost:8080/wsit-enabled-fromwsdl/
            addnumbers?wsdl"
    xmlns="https://jakarta.ee/xml/ns/jaxws">
    <bindings node="ns1:definitions"
            xmlns:ns1="http://schemas.xmlsoap.org/wsdl/">
            <package name="fromwsdl.client"/>
    </bindings>
    <bindings node="ns1:definitions/ns1:types/xsd:schema
            [@targetNamespace=’http://duke.org’]"
            xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:ns1="http://schemas.xmlsoap.org/wsdl/">
        <jaxb:schemaBindings>
            <jaxb:package name="fromwsdl.client"/>
        </jaxb:schemaBindings>
    </bindings>
</bindings>