JAX-WS annotation

Source link: http://java.globinch.com/enterprise-java/web-services/jax-ws/java-jax-ws-tutorial-develop-web-services-clients-consumers


In bottom-up approach we create the service end point interface (SEI) first. You define the methods in SEI that you expose as services. SEI typically is a standard Java interface. This is going to be the “wsdl:portType “ element in your WSDL document. The methods defined in SEI will become the “wsdl:operation” elements in the “wsdl:portType element” in WSDL. You need to annotate the SEI interface with required JAX-WS annotations.

Let us have a closer look at the different annotations provided by the JAX-WS API and how and when we use them.

The @WebService annotations

The “@WebService” should be placed on an interface and a class that is intended to be used as a service. It has the following attributes.

      name: Specifies the name of the service interface and iss mapped to the name attribute of the wsdl:portType element in a WSDL contract document.
      targetNamespace: Specifies the target namespace under which the service is defined.(Default value is package name).
      serviceName: Specifies the name of the published service. This property is mapped to the name attribute of the wsdl:service element in WSDL document. (Default value is name of SEI implementation class. This attribute is used in implementation class).
      wsdlLocation: Specifies the URI at which the service’s WSDL contract is stored. (Default value is the URI at which the service is deployed).
      endpointInterface: Specifies the full name of the SEI that the implementation class implements.(This attribute is used in implementation class).
      portName: The name of the endpoint at which the service is published and is mapped to the name attribute of the wsdl:port element in WSDL contract document.(Default value is the append Port to the name of the service’s implementation class. This is used in implementation class).

The service implementation class is annotated with @webservice and can include additional attributes such as endpointInterface, portName , serviceName etc.

The @SOAPBinding annotation

By default the JAX-WS runtime engine uses the wrapped doc/literal SOAP binding if you don’t specify any. To specify the required SOAP binding you can use the @SOAPBinding annotation. You can add @SOAPBinding annotation to the SEI and its methods. The latter takes precedence if you use both.
You can read more about SOAP Binding styles. The following are the attributes of @SOAPBinding annotation.

    style: The values can be either DOCUMENT or RPC
     use: The values can be LITERAL or ENCODED
     parameterStyle: The value can be BARE or WRAPPED.

The @WebMethod annotation

You need to add the @WebMethod annotation provides the information that is normally represented in the wsdl:operation element in WSDL. This indicates the operation to which the method is associated.

     operationName: Indicates the value of the associated wsdl:operation element’s name. (Default value is the name of the method).
     action: This attribute specifies the value of the soapAction attribute of the soap:operation element for the method in WSDL. (Default value is an empty string).
     exclude: Specifies whether the method should be excluded from the service interface.(Default is false. But it is recommended that the SEI ideally should contain only the required methods which are required to be published).

The @RequestWrapper and @ResponseWrapper annotations

These annotations are placed on the methods in service endpoint interface. The @RequestWrapper specifies the Java class that implements the wrapper bean for the method parameters that are included in the request message sent in a remote invocation and the @ResponseWrapper specifies the Java class that implements the wrapper bean for the method parameters that are included in the response message sent in a remote invocation.
These annotations have localName, targetNamespace and className attributes and only className is mandatory.

The @WebFault annotation

The @WebFault annotation is used to map the Java exception to a wsdl:fault element. @WebFault is placed on exceptions that are thrown by your SEI. This has the the attributes name, targetNamespace and faultName attributes

The @Oneway annotation

The @Oneway annotation is placed on the methods in the SEI that will not require a response from the service. The runtime does not wait for a response and will not reserve any resource to process a response.

The @WebParam annotation

The @WebParam annotation allows you to specify the direction of the parameter, if the parameter will be placed in the SOAP header, and other properties of the generated wsdl:part. This annotation is placed on the parameters on the methods defined in the SEI. This annotation has the following attributes.

     name: Specifies the name of the parameter as it appears in the WSDL. For RPC bindings, this is name of the wsdl:part representing the parameter. For document bindings, this is the local name of the XML element representing the parameter.
     targetNamespace: Indicates the namespace for the parameter(Defaults is to use the service’s namespace).
     mode: Indicates the direction of the web parameter. Values can be Mode.IN (default) ,Mode.OUT or Mode.INOUT
    head: This indicates if the parameter is passed as part of the SOAP header. Values can be Mode.IN (default) ,Mode.OUT or Mode.INOUT
    partName: Indicates the value of the name attribute of the wsdl:part element for the parameter when the binding is document.

The @WebResult annotation

The @WebResult annotation allows you to specify the properties of the generated wsdl:part that is generated for the method’s return value. This annotation is placed on the methods defined in the SEI. This annotations has name, targetNamespace, header and partName attributes in which header specifies if the return value is passed as part of the SOAP header.