scdjws 5. jax-ws
TRANSCRIPT
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