JBossWS - JAX-WS Tools

Version 3

    The JAX-WS tools provided by JBossWS can be used in a variety of ways. First we will look at server-side development strategies, and then proceed to the client.

    Server side

    When developing a Web Service Endpoint (the server-side) you have the option of starting from Java (bottom-up development), or from the abstact contract (WSDL) that defines your service (top-down development). If this is a new service (no existing contract), the bottom-up approach is the fastest route; you only need to add a few annotations to your classes to get a service up and running. However, if you are developing a service with an already defined contract, it is far simpler to use the top-down approach, since the provided tool will generate the annotated code for you.

    Bottom-up use cases:

    • Exposing an already existing EJB3 bean as a Web Service
    • Providing a new service, and you want the contract to be generated for you

    Top-down use cases:

    • Replacing the implementation of an existing Web Service, and you can't break compatibility with older clients
    • Exposing a service that conforms to a contract specified by a third party (e.g. a vender that calls you back using an already defined protocol).
    • Creating a service that adheres to the XML Schema and WSDL you developed by hand up front

    The following JAX-WS command line tools are included in JBossWS:

    Command Description
    JBossWS - wsprovideGenerates JAX-WS portable artifacts, and provides the abstract contract. Used for bottom-up development.
    JBossWS - wsconsumeConsumes the abstract contract (WSDL and Schema files), and produces artifacts for both a server and client. Used for top-down and client development
    JBossWS - wsrunclientExecutes a Java client (has a main method) using the JBossWS classpath.

    Bottom-Up (Using wsprovide)

    The bottom-up strategy involves developing the Java code for your service, and then annotating it using JAX-WS annotations. These annotations can be used to customize the contract that is generated for your service. For example, you can change the operation name to map to anything you like. However, all of the annotations have sensible defaults, so only the @WebService annotation is required.

    This can be as simple as creating a single class:

    package echo;
    
    @javax.jws.WebService
    public class Echo
    {
       public String echo(String input)
       {
          return input;
       }
    }
    

    A JSE or EJB3 deployment can be built using this class, and it is the only Java code needed to deploy on JBossWS. The WSDL, and all other Java artifacts called "wrapper classes" will be generated for you at deploy time. This actually goes beyond the JAX-WS specification, which requires that wrapper classes be generated using an offline tool. The reason for this requirement is purely a vender implementation problem, and since we do not believe in burdening a developer with a bunch of additional steps, we generate these as well. However, if you want your deployment to be portable to other application servers, you will unfortunately need to use a tool and add the generated classes to your deployment.

    This is the primary purpose of the JBossWS - wsprovidetool, to generate portable JAX-WS artifacts. Additionally, it can be used to "provide" the abstract contract (WSDL file) for your service. This can be obtained by invoking JBossWS - wsprovide using the "-w" option:

    $ javac -d . -classpath jboss-jaxws.jar Echo.java
    $ wsprovide --classpath=. -w echo.Echo
    Generating WSDL:
    EchoService.wsdl
    Writing Classes:
    echo/jaxws/Echo.class
    echo/jaxws/EchoResponse.class

    Inspecting the WSDL reveals a service called EchoService:

    <service name='EchoService'>
     <port binding='tns:EchoBinding' name='EchoPort'>
      <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
     </port>
    </service>
    

    As expected, this service defines one operation, "echo":

    <portType name='Echo'>
     <operation name='echo' parameterOrder='echo'>
      <input message='tns:Echo_echo'/>
      <output message='tns:Echo_echoResponse'/>
     </operation>
    </portType>
    

    Note

    Remember that when deploying on JBossWS you do not need to run this tool. You only need it for generating portable artifacts and/or the abstract contract for your service.

    Let's create a POJO endpoint for deployment on JBoss AS. A simple web.xml needs to be created:

    <web-app xmlns="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"
      version="2.4">
    
      <servlet>
        <servlet-name>Echo</servlet-name>
        <servlet-class>echo.Echo</servlet-class>
      </servlet>
    
      <servlet-mapping>
        <servlet-name>Echo</servlet-name>
        <url-pattern>/Echo</url-pattern>
      </servlet-mapping>
    </web-app>
    

    The web.xml and the single class can now be used to create a war:

    $ mkdir -p WEB-INF/classes
    $ cp -rp echo WEB-INF/classes/
    $ cp web.xml WEB-INF
    $ jar cvf echo.war WEB-INF
    added manifest
    adding: WEB-INF/(in = 0) (out= 0)(stored 0%)
    adding: WEB-INF/classes/(in = 0) (out= 0)(stored 0%)
    adding: WEB-INF/classes/echo/(in = 0) (out= 0)(stored 0%)
    adding: WEB-INF/classes/echo/Echo.class(in = 340) (out= 247)(deflated 27%)
    adding: WEB-INF/web.xml(in = 576) (out= 271)(deflated 52%)
    

    The war can then be deployed:

    cp echo.war /usr/local/jboss-4.2.0.GA-ejb3/server/default/deploy
    

    This will internally invoke JBossWS - wsprovide, which will generate the WSDL. If deployment was successful, and you are using the default settings, it should be available here: http://localhost:8080/echo/Echo?wsdl

    For a portable JAX-WS deployment, the wrapper classes generated earlier could be added to the deployment.

    Top-Down (Using wsconsume)

    The top-down development strategy begins with the abstract contract for the service, which includes the WSDL file and zero or more schema files. The JBossWS - wsconsume tool is then used to consume this contract, and produce annotated Java classes (and optionally sources) that define it.

    Note

    wsconsume seems to have a problem with symlinks on unix systems

    Using the WSDL file from the bottom-up example, a new Java implementation that adheres to this service can be generated. The "-k" option is passed to JBossWS - wsconsume to preserve the Java source files that are generated, instead of providing just classes:

     
    $ wsconsume -k EchoService.wsdl
    echo/Echo.java
    echo/EchoResponse.java
    echo/EchoService.java
    echo/Echo_Type.java
    echo/ObjectFactory.java
    echo/package-info.java
    echo/Echo.java
    echo/EchoResponse.java
    echo/EchoService.java
    echo/Echo_Type.java
    echo/ObjectFactory.java
    echo/package-info.java
    

    The following table shows the purpose of each generated file:

    File Purpose
    Echo.javaService Endpoint Interface
    Echo_Type.javaWrapper bean for request message
    EchoResponse.javaWrapper bean for response message
    ObjectFactory.javaJAXB XML Registry
    package-info.javaHolder for JAXB package annotations
    EchoService.javaUsed only by JAX-WS clients

    Examining the Service Endpoint Interface reveals annotations that are more explicit than in the class written by hand in the bottom-up example, however, these evaluate to the same contract:

    @WebService(name = "Echo", targetNamespace = "http://echo/")
    public interface Echo {
        @WebMethod
        @WebResult(targetNamespace = "")
        @RequestWrapper(localName = "echo", targetNamespace = "http://echo/", className = "echo.Echo_Type")
        @ResponseWrapper(localName = "echoResponse", targetNamespace = "http://echo/", className = "echo.EchoResponse")
        public String echo(
            @WebParam(name = "arg0", targetNamespace = "")
            String arg0);
    
    }
    

    The only missing piece (besides the packaging) is the implementation class, which can now be written, using the above interface.

    package echo;
    
    @javax.jws.WebService(endpointInterface="echo.Echo")
    public class EchoImpl implements Echo
    {
       public String echo(String arg0)
       {
          return arg0;
       }
    }

    Client Side

    Before going to detail on the client-side it is important to understand the decoupling concept that is central to Web Services. Web Services are not the best fit for internal RPC, even though they can be used in this way. There are much better technologies for this (CORBA, and RMI for example). Web Services were designed specifically for interoperable coarse-grained correspondence. There is no expectation or guarantee that any party participating in a Web Service interaction will be at any particular location, running on any particular OS, or written in any particular programming language. So because of this, it is important to clearly separate client and server implementations. The only thing they should have in common is the abstract contract definition. If, for whatever reason, your software does not adhere to this principal, then you should not be using Web Services. For the above reasons, the recommended methodology for developing a client is to follow the top-down approach, even if the client is running on the same server.

    Let's repeat the process of the top-down section, although using the deployed WSDL, instead of the one generated offline by JBossWS - wsprovide. The reason why we do this is just to get the right value for soap:address. This value must be computed at deploy time, since it is based on container configuration specifics. You could of course edit the WSDL file yourself, although you need to ensure that the path is correct.

    Offline version:

    <service name='EchoService'>
      <port binding='tns:EchoBinding' name='EchoPort'>
       <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
      </port>
     </service>
    

    Online version:

    <service name="EchoService">
      <port binding="tns:EchoBinding" name="EchoPort">
        <soap:address location="http://localhost.localdomain:8080/echo/Echo"/>
      </port>
    </service>
    

    Using the online deployed version with JBossWS - wsconsume:

    $ wsconsume -k http://localhost:8080/echo/Echo?wsdl
    echo/Echo.java
    echo/EchoResponse.java
    echo/EchoService.java
    echo/Echo_Type.java
    echo/ObjectFactory.java
    echo/package-info.java
    echo/Echo.java
    echo/EchoResponse.java
    echo/EchoService.java
    echo/Echo_Type.java
    echo/ObjectFactory.java
    echo/package-info.java
    


    The one class that was not examined in the top-down section, was EchoService.java. Notice how it stores the location the WSDL was obtained from.

    @WebServiceClient(name = "EchoService", targetNamespace = "http://echo/", wsdlLocation = "http://localhost:8080/echo/Echo?wsdl")
    public class EchoService extends Service
    {
        private final static URL ECHOSERVICE_WSDL_LOCATION;
    
        static {
            URL url = null;
            try {
                url = new URL("http://localhost:8080/echo/Echo?wsdl");
            } catch (MalformedURLException e) {
                e.printStackTrace();
            }
            ECHOSERVICE_WSDL_LOCATION = url;
        }
    
        public EchoService(URL wsdlLocation, QName serviceName) {
            super(wsdlLocation, serviceName);
        }
    
        public EchoService() {
            super(ECHOSERVICE_WSDL_LOCATION, new QName("http://echo/", "EchoService"));
        }
    
        @WebEndpoint(name = "EchoPort")
        public Echo getEchoPort() {
            return (Echo)super.getPort(new QName("http://echo/", "EchoPort"), Echo.class);
        }
    }
    

    As you can see, this generated class extends the main client entry point in JAX-WS, javax.xml.ws.Service. While you can use Service directly, this is far simpler since it provides the configuration info for you. The only method we really care about is the getEchoPort() method, which returns an instance of our Service Endpoint Interface. Any WS operation can then be called by just invoking a method on the returned interface.

    Note

    It's not recommended to refer to a remote WSDL URL in a production application. This causes network I/O every time you instantiate the Service Object. Instead, use the tool on a saved local copy, or use the URL version of the constructor to provide a new WSDL location.

    All that is left to do, is write and compile the client:

    import echo.*;
    
    public class EchoClient
    {
       public static void main(String args[])
       {
          if (args.length != 1)
          {
             System.err.println("usage: EchoClient <message>");
             System.exit(1);
          }
           
          EchoService service = new EchoService();
          Echo echo = service.getEchoPort();
          System.out.println("Server said: " + echo.echo(args[0]));
       } 
    }
    

    It can then be easily executed using the JBossWS - wsrunclient tool. This is just a convenience tool that invokes java with the needed classpath:

    $ wsrunclient EchoClient 'Hello World!'
    Server said: Hello World!
    

    It is easy to change the endpoint address of your operation at runtime, setting the ENDPOINT_ADDRESS_PROPERTY as shown below:

    ...
          EchoService service = new EchoService();
          Echo echo = service.getEchoPort();
    
          /* Set NEW Endpoint Location */
          String endpointURL = "http://NEW_ENDPOINT_URL";
          BindingProvider bp = (BindingProvider)echo;
          bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL);
    
          System.out.println("Server said: " + echo.echo(args[0]));
    ...

    Command-line, Maven Plugin and Ant Task Reference

    JAX-WS binding customization

    An introduction to binding customizations:

    The schema for the binding customization files can be found here: