Web Services with JAX-WS

Introduction

 In my own mind I want to clarify the distinction between, SOAP, ReST and Web Services. Using the following code examples I think that confusion has been dealt with.

A Web Service is a distributed programming style that can use SOAP or ReST as the underlying communications layer.

SOAP is middleware that uses XML to represent the payload but relies on any standard internet protocol such as HTTP, FTP, SMTP etc.

ReST is middleware that uses XML to represent the payload but relies solely on HTTP as the carrier protocol. So, in one way to visualise ReST is a narrower version of SOAP, it limits the SOAP verbs to those within HTTP and restricts the XML payload.

 

SOAP in Code

Consider the following piece of code (generated courtesy of Netbeans)

The process (netbeans)

  1. create the server side SEI
  2. get netbeans to create a client side from the SEI 
    1. New Application
    2. Other/Web Services/Web Services Client
    3. Use Local File - if the you know where the wsdl is, or Project - if the wsdl has been deployed on the appserver
    4. Specify a package for generated files
    5. Do a clean/build of the server and this will generate good bindings

The annotations

WebService

Marks a Java class as implementing a Web Service, or a Java interface as defining a Web Service interface.

WebMethod

Use this to mark a method as being available to the outside world.  You're exposing the method.

According to the JEE 5 spec - The associated method must be public and its parameters return value, and exceptions must follow the rules defined in JAX-RPC 1.1, section 5. The method is not required to throw java.rmi.RemoteException.

Using the operationName overrides the default name used (the method name) as the name attribute of the message element within the wsdl file.  Basically it creates an alias to the method so that if the method name changes the wsdl would be unaffected. 

WebParam

A critical annotation, without it params in the client code do not bind correctly to method params on the servant.  As crazy as it sounds, but the proxy code has the WebParam names in it, if there is a mismatch between the proxy code and the servant code WebParams, no data is passed to the servant code.  They essentially act is named parameters, so the order of them in the method signature is crucial.