Transcript Web-Services-JAX_WS_2009-12-03 - files-ante-lv

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.0
1.
2.
Annotations are used in mapping Java to WSDL
and schema
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 {
@WebMethod
public 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 service
Parameter Name
Description
endpointInterface
The complete name of the service endpoint
The web service's name.
The web service's port name.
The web service's service name.
If the @WebService.targetNamespace
annotation is on an SEI, the
targetNamespace is used for the namespace
for the wsdl:portType and associated XML
elements.
The location of a predefined WSDL file
describing the service.
name
portName
serviceName
targetNamespace
wsdlLocation
Annotation @javax.jws.WebMethod
Customizes a method that is exposed as a Web
service operation
Class or Type
Parameter Name
Description
String
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
operationName
Name 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
•
•
HelloWebService.java
•
•
Custom data type for response
ObjectFactory.java
•
•
Custom data type for request
HelloResponse.java
•
•
Service Endpoint Interface
Hello.java
•
•
Service factory
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
• Execute
wsgen -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.java
package 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 wsimport tool
• 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);
}
}
JAX-WS Handlers
•
Handlers are message interceptors that can be plugged in
to the JAX-WS runtime to do additional processing of the
inbound and outbound messages
•
•
e.g. print SOAP message
Handler creation steps:
•
•
Create the JAX-WS Handler code
Attach the JAX-WS handlers
• programmatic configuration for the client
• XML file configuration for the server
http://www.jroller.com/gmazza/entry/adding_jax_ws_handlers_to
Dynamic client programming
URL wsdlLocation;
try {
wsdlLocation = new URL(
"http://localhost:8080/java-eim-demojbossws/CalculatorWebService?wsdl");
}
catch (MalformedURLException e) {
throw new RuntimeException(e);
}
QName serviceName = new QName(
"http://service.jbossws.webkursi.lv/",
"CalculatorWebServiceService");
Service service = Service.create(wsdlLocation, serviceName);
calcService = service.getPort(CalculatorWebService.class);
int addResult = calcService.add(a, b);
Nobeigums
Tas bija tikai īss ievads..!
Web servisu temats ir daudz
plašāks...
References
• JAX-WS Annotations
https://jax-ws.dev.java.net/jax-wsea3/docs/annotations.html
• JBossWS Home
http://labs.jboss.com/jbossws/
• JBossWS Wiki
http://jbws.dyndns.org/mediawiki/index.php?tit
le=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 1
http://java.sun.com/developer/technicalArticles/J2SE
/jax_ws_2/
•
Articles related to JAX-WS API's handler framework
http://www.javaworld.com/javaworld/jw-02-2007/jw-02-handler.html
http://www.jroller.com/gmazza/entry/adding_jax_ws_handlers_to
https://jax-ws.dev.java.net/articles/handlers_introduction.html