Web servisu izstrāde

JAX-WS

Ievads

• JAX-WS = Java API for XML Web Services

• JAX-WS ir fundamentāla Web servisu izstrādes tehnoloģija

• Java EE 5 un Java SE 6 sastāvdaļa

• JAX-WS 2.0 aizvietoja JAX-RPC• Pāreja no RPC-style uz document-style Web servisiem

• Reference Implementation – by GlassFish

Priekšvēsture: JAX-RPC

• JAX-RPC = Java API for XML-based RPC

• Pirmā specifikācijas versija (JAX-RPC 1.0) bija JSR-101 un tā bija izlaista 2002.gada jūnijā

• Fundamentālais mērķis - vienkāršot sazināšanas starp Java un ne-Java platformām

• Dod iespēju no Java programmas izsaukt Java Web servisu ar zināmu aprakstu (saskaņā ar servisa WSDL)

JAX-RPC modelis

JAX-RPC modelim, ir divas puses:

• Server-side programming model• Allows to develop Web service endpoints as Java

objects or Enterprise JavaBeans, which run on the J2EE platform

• Client-side programming model • Allows to access a remote Web service as if it were a

local object, using methods that represent SOAP operations

JAX-WS

• JAX-WS 2.0 replaced the JAX-RPC API in Java Platform, Enterprise Edition 5

• JAX-WS is the move away from RPC-style and toward document-style web services

• Like the other Java EE APIs, JAX-WS uses annotations to simplify the development and deployment of Web service clients and endpoints

Server-Side Programming

There are two server-side programming models for creating Java EE Web service endpoints:

• POJO endpoints

• EJB3 Stateless

Session Bean

endpoints

JAX-WS Annotations

• Annotations play a critical role in JAX-WS 2.01. Annotations are used in mapping Java to WSDL

and schema2. Annotations are used in runtime to control how the

JAX-WS runtime processes and responds to Web service invocations

• Annotations utilized by JAX-WS 2.0 are defined in separate JSRs:

• JSR 181: Web Services Metadata for the JavaTM Platform• JSR 222: JavaTM Architecture for XML Binding (JAXB) 2.0• JSR 224: JavaTM API for XML Web Services (JAX-WS) 2.0• JSR 250: Common Annotations for the JavaTM Platform

Web Service Implementation

1. Write a POJO implementing the service

2. Add @WebService annotation to it

3. Optionally, inject a WebServiceContext• WebServiceContext makes it possible for a Web

service endpoint implementation class to access message context and security information relative to a request

4. Deploy the application

5. Point your clients at the WSDL• e.g. http://myserver/myapp/MyService?WSDL

Example: HelloWebService

@WebService(name = "HelloWebService")@SOAPBinding( style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)

public class HelloWebService {

@WebMethodpublic String hello(@WebParam(name = "name")

String name){ return "Welcome " + name + " !!!"; }}

More Annotations

• Web Services Metadata Annotations• @WebService• @WebMethod• @OneWay• @WebParam• @WebResult

• JAX-WS Annotations• @RequestWrapper• @ResponseWrapper• @WebEndpoint• @WebFault• @WebServiceClient• @WebServiceRef

Annotation @javax.jws.WebService

Is used to specify that the class is a Web service or that the interface defines a Web serviceParameter Name DescriptionendpointInterface The complete name of the service endpoint name The web service's name.portName The web service's port name.serviceName The web service's service name.targetNamespace If the @WebService.targetNamespace

annotation is on an SEI, the targetNamespace is used for the namespace for the wsdl:portType and associated XML elements.wsdlLocation The location of a predefined WSDL file describing the service.

Annotation @javax.jws.WebMethod

Customizes a method that is exposed as a Web service operation

Class or Type Parameter Name DescriptionString action The action for this operation.

boolean exclude

You can set this parameter to true to quickly mark a method as not exposed as a web method. The default value is false.

String operationNameName of the wsdl:operation matching this method.

Web Service Deployment

• To run Web service you’ll need to deploy it into Web server with Java EE compliant web services

• Java service endpoint usually is packaged as a Web application in a WAR file

• We will consider JBoss Application Server with JBoss Web Services (JBossWS)

JBoss Web Services

• JBossWS is a JAX-WS compliant Web service stack developed to be part of JBoss' Java EE 5 offering

• At deployment time JBossWS will create services endpoints from annotated classes and publish the WSDL

• At runtime SOAP requests are converted to JAVA invocations

JBossWS deploy-time & run-time

Demo

• Ir sagatavots demo projekts:http://java-eim.googlecode.com/svn/trunk/

java-eim-demo-jbossws

• Pašlaik ir izveidoti divi vienkārši Web servisi:• HelloWebService • CalculatorWebService

• Instrukcijas ir atrodamas failā README.txt

JBossWS Console

http://localhost:8080/jbossws/

Client-Side Programming

• JAX-WS client programming models:

• Static Dynamic proxy client API• Dynamic Dispatch client API

• Dynamic proxy client

• Invokes a Web service based on a Service Endpoint Interface (SEI) which must be provided

• Creating web service clients usually starts from the WSDL (“WSDL first” approach)

• Special tools are used to generate client classes

Dispatch client API

• Low level JAX-WS API to work at the XML message level or without any generated artefacts

• Requires clients to construct messages or message payloads as XML

• Requires an intimate knowledge of the desired message or payload structure

Client Side Generation (JBossWS)

• JBossWS provides a tool for client side generation from WSDL

wsconsume

• From <JBOSS_HOME>/bin execute:

wsconsume -k -p <package> <path_to_wsdl>

Generated Files

• HelloWebServiceService.java • Service factory

• HelloWebService.java • Service Endpoint Interface

• Hello.java • Custom data type for request

• HelloResponse.java • Custom data type for response

• ObjectFactory.java • JAXB XML Registry

• package-info.java • Holder for JAXB package annotations

Client Code

import xxx.generated.hello.HelloWebService;import xxx.generated.hello.HelloWebServiceService;

public class HelloWebServiceClient { public static void main(String[] args) {

HelloWebServiceService helloFactory = new HelloWebServiceService();

HelloWebService helloService = helloFactory.getPort(HelloWebService.class);

String response =

helloService.hello("WebServiceClient"); }}

Web Service Invocation

1. A Java program invokes a method on a stub (local object representing the remote service)

2. The stub invokes routines in the JAX-WS runtime system

3. The runtime system converts the remote method invocation into a SOAP message

4. The runtime system transmits the message as an HTTP request

JAX-WS support in Java SE 6

• One of the most exciting new features of the Java SE 6 is support for the JAX-WS 2.0

• Although JAX-WS finds its main home in the Java EE 5, you can reuse much of the functionality without enterprise server

• The first thing you need is a class with one or more methods that you wish to export as a Web service

Web service class

@WebService annotation at the beginning tells the Java interpreter that you intend to publish the methods of this class as a web service

@javax.jws.WebService

public class CircleFunctions { public double getArea(double r) { return java.lang.Math.PI * (r * r); }

public double getCircumference(double r) { return 2 * java.lang.Math.PI * r; }}

Publishing Web service

The static publish() method of the javax.xml.ws.Endpoint class is used to publish the class as a Web service in the specified context root

import javax.xml.ws.Endpoint;

public static void main(String[] args) {

Endpoint.publish("http://localhost:8080/" +"WebServiceExample/circlefunctions",new CircleFunctions());

}

Execute publishing program – error!

If you’ll try to publish Web service endpoint right now (see previous slide), then you’ll get the following exception

Exception in thread "main" com.sun.xml.internal.ws.model.RuntimeModelerException: runtime modeler error: Wrapper class lv.webkursi.javase6.jaxws.jaxws.GetArea is not found. Have you run APT to generate them? at com.sun.xml.internal.ws.model.RuntimeModeler.getClass at com.sun.xml.internal.ws.model.RuntimeModeler.processDocWrappedMethod . . . at com.sun.xml.internal.ws.transport.http.server.EndpointImpl .publish(Unknown Source) at com.sun.xml.internal.ws.spi.ProviderImpl.createAndPublishEndpoint at javax.xml.ws.Endpoint.publish(Unknown Source)

Additional step – Wsgen tool

• The problem is that all required artifacts for a JAX-WS web service are not generated yet

• wsgen tool has to be used to accomplish it

• The tool reads a Web service endpoint class and generates all the required artifacts for Web service deployment and invocation

• Before running wsgen make sure that Web service class is compiled• when using Maven, compiled classes are located in

<project_root>\target\classes

Running wsgen tool

• Make sure you have JDK 6 installed and /bin/ directory (which contains wsgen.exe) is added to PATH• E.g. C:\Program Files\Java\jdk1.6.0_10\bin

• Go to the root folder containing .class file for your Web service• when using Maven <project_root>\target\classes

• Executewsgen -cp . -s . <full class name>

wsgen -cp . -s . lv.webkursi.javase6.jaxws.CircleFunctions

Result of running wsgen

• Generated artifacts are located in:\target\classes\lv\webkursi\javase6\jaxws\jaxws

• GetArea.class• GetAreaResponse.class• GetCircumference.class• GetCircumferenceResponse.class

• Source *.java files are located in the same folder

Generated GetArea.javapackage lv.webkursi.javase6.jaxws.jaxws;

import javax.xml.bind.annotation*;

@XmlRootElement(name = "getArea", namespace = "http://jaxws.javase6.webkursi.lv/")

@XmlAccessorType(XmlAccessType.FIELD)@XmlType(name = "getArea", namespace =

"http://jaxws.javase6.webkursi.lv/")public class GetArea {

@XmlElement(name = "arg0", namespace = "") private double arg0;

public double getArg0() { return this.arg0; } public void setArg0(double arg0) { this.arg0 = arg0; }}

Creating Web service client

• We will consider creating a simple Java project, which will contain a Web service client program

• In Eclipse create a usual Java project

• By default• Sources are located in <project_root>/src• Binaries are located in <project_root>/bin

• Further steps• Generate required JAX-WS artifacts using wsimport• Create web service client program

wsimport tool

The wsimport tool generates JAX-WS portable artifacts from WSDL, such as:

• Service Endpoint Interface (SEI)

• Service

• Exception class mapped from wsdl:fault (if any)

• Async Response Bean derived from response wsdl:message (if any)

• JAXB generated value types (mapped Java classes from schema types)

Running wsgen

• Go to your Java project root folder and execute

wsimport -d ./bin -s ./src <path_to_WSDL>

wsimport -d ./bin -s ./src http://localhost:8080/WebServiceExample/circlefunctions?WSDL

• Generated Java sources will appear in <project_root>/src/

• Compiled classes will appear in <project_root>/bin/

Generated artifacts

• CircleFunctions.java

• CircleFunctionsService.java

• GetArea.java

• GetAreaResponse.java

• GetCircumference.java

• GetCircumferenceResponse.java

• ObjectFactory.java

• package-info.java

Web service client program

import lv.webkursi.javase6.jaxws.CircleFunctions;

import lv.webkursi.javase6.jaxws.CircleFunctionsService;

public class WebServiceClient {

public static void main(String[] args)

{

CircleFunctionsService service = new CircleFunctionsService();

CircleFunctions port = service.getCircleFunctionsPort();

double radius = 3.0;

double result = port.getArea(radius);

System.out.println("Result = " + result);

}

}

Nobeigums

Tas bija tikai īss ievads..!

Web servisu temats ir daudz plašāks...

References

• JAX-WS Annotations https://jax-ws.dev.java.net/jax-ws-ea3/docs/annotations.html

• JBossWS Homehttp://labs.jboss.com/jbossws/

• JBossWS Wikihttp://jbws.dyndns.org/mediawiki/index.php?title=JBossWS

References

• JAX-WS Reference Implementation by GlassFish

https://jax-ws.dev.java.net/

• JAX-WS Specification (JSR 224) http://jcp.org/en/jsr/detail?id=224

• Presentation about JAX-WS http://gceclub.sun.com.cn/java_one_online/2006

/TS-1194/TS-1194.pdf

References

• Introducing JAX-WS 2.0 with the Java SE 6 Platform, Part 1http://java.sun.com/developer/technicalArticles/J2SE/jax_ws_2/