JAX-WSFrancesco Ierna

JAX-WSJAX-WS : is a programming model that simplifies application development through support of a standard, annotation-based model to develop Web Service applications and clients.

Replace the remote procedures call programming as defined by JAX-RPC

Both servlet endpoints and EJB endpoints can have an object implementing the WebServiceContext interface injected using the @Resource annotation

Allows developers to write message-oriented as well as RPC-oriented web services

With JAX-WS, the developer does not generate or parse SOAP messages

the platform independence of the Java programming language beacuse jax-ws uses techology definined by the W3C : HTTP, SOAP and WSDL

Overview

FeaturesFeatures :

Better platform indipendent

Annotations : supports the use of annotations.

Sempliies development of web services

Much easier to expose method as web services

Webservices.xml is optional and overrides all the information in a file class java

Called both synchronously and asynchronously

Asynchronously : Future<?> getCreditScoreAsync(Customer customer, AsyncHandler<Score> handler);

Using resource injection : The application server also supports the usage of the @Resource or @WebServiceRef annotation to declare JAX-WS managed clients and to request injection of JAX-WS services and ports

Data Binding : JAX-WS leverages the Java Architecture for XML Binding (JAXB) 2.1 API and tools as the binding technology for mappings between Java objects and XML documents.

Support for MTOM : can send binary attachments such as images or files along with Web services requests

Support for SOAP 1.2 : JAX-WS supports both SOAP 1.1 and SOAP 1.2

Development tools : JAX-WS provides the wsgen and wsimport command-line tools for generating portable artifacts for JAX-WS Web services

Support for WS-Addressing (JAX-WS 2.1) : The new API enables you to create, transmit and use endpoint references to target a specific Web service endpoint

 Support for JAX-WS 2.1 features : JAX-WS 2.1 introduces the concept of features as a way to programmatically control certain functions or behaviors

Development MessageContextUsing a WebServiceContext object, the endpoint have access to basic security 

mechanisms of JavaEE

Both servlet endpoints and EJB endpoints can have an object implementing the WebServiceContext interface injected using the @Resource annotation

DevelopmentJava Class :

@WebServices on java class

No @WebMethod → all method expose to be a web services method

@WebMethod → only the methods annotates with @WebMethod will be exposed to be a web services method

We can exclude some methods by annotating the method with the property exclude setted to true into the @WebMethod annotation

Interface

Is mapped in portType within the WSDL file

Method

Is mapped to a wsdl:operation element  in the corrisponding  wsdl:portType plus one or more wsdl:message elements

Development ExampleJAX-WS HelloWorld SEI:

@WebService(name = "HelloWorld", targetNamespace = "urn:samples.ibm.com/HelloWorld")

public interface HelloWorld {

@WebMethod(action = "urn:samples.ibm.com/HelloWorld/hello")

@WebResult(name = "response", targetNamespace = "")

@RequestWrapper(localName = "hello", targetNamespace = "urn:samples.ibm.com/HelloWorld", className = "com.ibm.samples.helloworld.Hello")

@ResponseWrapper(localName = "helloResponse", targetNamespace = "urn:samples.ibm.com/HelloWorld", className = "com.ibm.samples.helloworld.HelloResponse")

public String hello( @WebParam(name = "name", targetNamespace = "") String name);}

<wsdl:types>

<xsd:schema targetNamespace="urn:helloWorld/sample/ibm/com"...>

<xsd:element name="hello" type="xsd:string"/>

<xsd:element name="helloResponse" type="xsd:string"/>

</xsd:schema>

</wsdl:types>

<wsdl:message name="helloRequestMsg">

<wsdl:part element="tns:hello" name="helloParameters" />

</wsdl:message>

<wsdl:message name="helloResponseMsg">

<wsdl:part element="tns:helloResponse" name="helloResult" />

</wsdl:message>

WSDL Services

JAX-WS

JAX-WS

JAXB Annotations

Common – Web Service Feature

WSDL - WebServicesjavax.jws.WebService : to mark a endpoint implementation as implementing a web service or to

mark that a service endpoint interface as defining a web service interface

Name : wsdl:portType

TargetNameSpace : XML namespace

ServiceName : wsdl:service

EndpointInterface : The qualified name of the service endpoint interface. This annotation allows the separation of interface contract from implementation.

PortName : wsdl:portName

WsdlLocation : Specifies the Web address of the WSDL document defining the Web service. relative or absolute

javax.jws.WebMethod : is to expose a method as a web service operation.

OperationName : The name of the wsdl:operation matching this method

Action : The XML namespace of the the WSDL and some of the XML elements generated from this web service.

Exclude : Used to exclude a method from the WebService. Default false

javax.jws.OneWay : to mark a method as a web service one-way operation

WSDL – WebServices 2javax.jws.WebParam : is used to customize the mapping of a single parameter to a message

part or element

Name : Name of the parameter. this is name of the wsdl:part

mode: Represents the direction the parameter flows for this method. Possible values are IN, INOUT and OUT. INOUT and OUT modes

PartName : Used to specify the partName for the parameter with RPC or DOCUMENT/BARE operations

javax.jws.WebResult : is used to customize the mapping of the method return value to a WSDL part or XML element.

name: The name of the return value in the WSDL and on the wire

partName: Used to specify the partName for the result with RPC or DOCUMENT/BARE operations

javax.jws.HandlerChain : is used to specified an externally defined handler chain

File : Location of the file containing the handler chain definition. relative or absolute with in a classpath system

Name : DEPRECATED:

WSDL – WebServices 3javax.jws.soap.SOAPBinding : to specify a SOAPBinding annotation on a endpoint

implementation or service endpoint interface

lets the developer choose between document/literal wrapped, document/literal bare, rpc/literal and rpc/encoded endpoints with the default being document/literal wrapped

document/literal wrapped → is that methods on a document/literal wrapped endpoint can have multiple parameters bound to the body of a SOAP message,

document/literal bare → can only have one such parameter

Style : Defines the style for messages used in a web service. The value can be either DOCUMENT or RPC. Def : DOCUMENT

Use : Defines the encoding used for messages used in web service. Can only be LITERAL for JAX-WS 2.1. Def LITERAL

ParameterStyle : Determines if the method's parameters represent the entire message body or whether the parameters are wrapped in a body element named after the operation

javax.xml.ws.BindingType : is used to specify the binding to use for a web service endpoint implementation class

javax.xml.ws.RequestWrapper : annotates methods in the Service Endpoint Interface with the request wrapper bean to be used at runtime. Only the className is required in this case

javax.xml.ws.ResponseWrapper : annotates methods in the Service Endpoint Interface with the response wrapper bean to be used at runtime. Only the className is required in this case

JAX - WS javax.xml.ws.BindingType : is used to specify the binding to use for a web service endpoint

implementation class

javax.xml.ws.RequestWrapper : annotates methods in the Service Endpoint Interface with the request wrapper bean to be used at runtime. Only the className is required in this case

javax.xml.ws.ResponseWrapper : annotates methods in the Service Endpoint Interface with the response wrapper bean to be used at runtime. Only the className is required in this case

javax.xml.ws.ServiceMode : allows the Provider developer to indicate whether a Provider implementation wishes to work with entire protocol messages or just with protocol message payloads

javax.xml.ws.WebEndpoint : Used to annotate the get PortName() methods of a generated service interface

javax.xml.ws.WebFault : This annotation is generated by the JAX-WS tools into service specific exception classes generated from a WSDL to customize to the local and namespace name of the fault element and the name of the fault bean and to mark the service specific exception as one generated from WSDL

javax.xml.ws.WebServiceClient : specified in this annotation is sufficient to uniquely identify a wsdl:service element inside a WSDL document

javax.xml.ws.WebServiceProvider : Annotation used to annotate a Provider implementation class

JAX - WS javax.xml.ws.WebServiceRef : is used to define a reference to a web service and (optionally) an

injection target for it. Web service references are resources in the Java EE 5 sense.

javax.xml.ws.Feature : The @Feature annotation is used to enable/disable a feature to use for a web service endpoint implementation class. This annotation is used with @BindingType annotation.

javax.xml.ws.Action : allows explicit association of Action message addressing property with input, output, and fault messages of the mapped WSDL operation.

can be specified on each method of a service endpoint interface or implementation

Input

Output

Fault can be specified on each method of a service endpoint interface or implementation

javax.xml.ws.FaultAction : is used inside an @Action annotation to allow an explicit association of Action message addressing property with the fault messages of the WSDL operation mapped from the exception class.

ToolsTools for converting WSDLs and Java source/class files to Web Services

APT : A Java SE tool and framework for processing annotations. APT will invoke a JAX-WS AnnotationProcossor for processing Java source files with javax.jws.* annotations and making them web services

WsGen : Tool to process a compiled javax.jws.WebService annotated class and to generate the necessary classes to make it a Web service

WsImport : Tool to import a WSDL and to generate an SEI (a javax.jws.WebService) interface that can be either implemented on the server to build a webservice, or can be used on the client to invoke the web service

Create WebService using JAX-WSThese are the basic steps for creating the web service and client

1. Code the implementation class.

2. Compile the implementation class.

3. Use wsgen to generate the artifacts required to deploy the service.

4. Package the files into a WAR file.

5. Deploy the WAR file. The web service artifacts (which are used to communicate with clients) are generated by the Application Server during deployment.

6. Code the client class.

7. Use wsimport to generate and compile the web service artifacts needed to connect to the service.

8. Compile the client class.

9. Run the client.

Requirements of a JAX-WS EndpointJAX-WS endpoints must follow these requirements

The implementing class must be annotated with either the javax.jws.WebService or javax.jws.WebServiceProvider annotation.

The implementing class may explicitly reference an SEI through the endpointInterface element of the @WebService annotation, but is not required to do so. If no endpointInterface is specified in @WebService, an SEI is implicitly defined for the implementing class.

The business methods of the implementing class must be public, and must NOT be declared static or final.

Business methods that are exposed to web service clients must be annotated with javax.jws.WebMethod.

Business methods that are exposed to web service clients must have JAXB-compatible parameters and return types.

The implementing class must NOT be declared final and must NOT be abstract.

The implementing class must have a default public constructor.

The implementing class must NOT define the finalize() method.

The implementing class may use the javax.annotation.PostConstruct or javax.annotation.PreDestroy annotations on its methods for life cycle eventcallbacks.

Examplepackage helloservice.endpoint;import javax.jws.WebService; @WebService public class Hello { private String message = new String("Hello, "); public void Hello() {} @WebMethod public String sayHello(String name) { return message + name + "."; } }

Simple JAX-WS ClientA JAX-WS web service client can be either a dynamic client, for which no artifacts have been

generated, or a static client for which a set of artifacts have been generated

Dynamic : Dynamic clients can choose to work either with protocol-specific message structures, e.g. SOAP messages for the SOAP protocol binding, or with message payloads, which in the case of SOAP would be the contents of the SOAP body in a message

Static : @WebServiceRef(wsdlLocation = "http://localhost:8080/JAX-WS_Server_wsgen/CalculatorService?wsdl")

JHelloClient is a stand-alone Java program that accesses the sayHello method of HelloService. It makes this call through a port, a local object that acts as aproxy for the remote service. The port is created at development time by the wsimport tool, which generates JAX-WS portable artifacts based on a WSDL file

1. Uses the javax.xml.ws.WebServiceRef annotation to declare a reference to a web service.

@WebServiceRef(wsdlLocation="http://localhost:8080/helloservice/hello?wsdl")

static HelloService service;

2. Retrieves a proxy to the service, also known as a port, by invoking getHelloPort on the service

Hello port = service.getHelloPort();

3. The port implements the SEI defined by the service.

String response = port.sayHello(name);

Examplepublic class HelloClient {@WebServiceRef(wsdlLocation="http://localhost:8080/helloservice/hello?wsdl")static HelloService service;public static void main(String[] args) {try {HelloClient client = new HelloClient();client.doTest(args);} catch(Exception e) {e.printStackTrace();}}

public void doTest(String[] args) {try {System.out.println("Retrieving the port fromthe following service: " + service);Hello port = service.getHelloPort();System.out.println("Invoking the sayHello operationon the port.");String name;if (args.length > 0) {name = args[0];} else {name = "No Name";}String response = port.sayHello(name);System.out.println(response);} catch(Exception e) {e.printStackTrace();}}}

JAX-WS Client Communications ModelsDispatch client : javax.xml.ws.Dispatch

Use this client when you want to work at the XML message level or when you want to work without any generated artifacts at the JAXWS level

use XML messages for communications between Web services and Web services clients

invoking services at the XML message level is provided by the Dispatch client API

The Dispatch client can send data in either MESSAGE or PAYLOAD mode

The Dispatch client supports the following types of objects :

javax.xml.transform.Source : can use Source objects with SOAP or HTTP bindings

JAXB objects : JAXB objects can only be used with SOAP or HTTP bindings

javax.xml.soap.SOAPMessage : You can only use SOAPMessage objects with SOAP

javax.activation.DataSource : Use DataSource only with HTTP bindings.

Dispatch client is invoked in one of three ways :

Synchronous : requests and responses using the invoke method

Asynchronous : requests and responses using the invokeAsync method with a callback or polling object

One-way invocation using the invokeOneWay methods

Dynamic Proxy client

Use this client when you want to invoke a Web service based on a service endpoint interface

extend the java.lang.reflect.Proxy