Ts-7964

Java™ Web Services Development Using Annotations Brian Zotter Staff Engineer BEA Systems http://www.bea.com TS-7964 2005 JavaOne SM Conference | Session TS-7964

1

Instant Web Services

Learn how to use Java™ technologybased Web Services (“Java Web Services”) Metadata to quickly develop Enterprise Web Services.

2005 JavaOneSM Conference | Session TS-7964 |

2

Current Web Services Development • Why is Java Web Service development so difficult? • Complicated APIs • Manual creation of deployment descriptors • Lack of tool support

2005 JavaOneSM Conference | Session TS-7964 |

3

Agenda • JSR 181 • Development Models • Processor • Runtime

• • • • •

Annotations Reference Implementation Next Steps Summary Q&A 2005 JavaOneSM Conference | Session TS-7964 |

4

Agenda • JSR 181 • Development Models • Processor • Runtime

• • • • •

Annotations Reference Implementation Next Steps Summary Q&A 2005 JavaOneSM Conference | Session TS-7964 |

5

JSR 181 • Defines an annotated Java language syntax for programming Web Service applications • Allows the developer to concentrate on the business logic of the service • Defines a standard for building and deploying Web Services without requiring knowledge and implementation of generalized APIs and deployment descriptors

2005 JavaOneSM Conference | Session TS-7964 |

6

Hello World

Exposes this class as a Web Service

@WebService public class HelloWorld { @WebMethod public String hello(){ return “Hello World!”; }

Exposes this method as a Web Service operation

}

2005 JavaOneSM Conference | Session TS-7964 |

7

Development Modes • Start with Java technology • Exposing a Java technology service • Only required mode

• Start with WSDL • Implementing a public contract

• Start with Java technology and WSDL • Implementation must provide feedback if Java technology source and WSDL are not in sync

2005 JavaOneSM Conference | Session TS-7964 |

8

JSR 181 Processor • Produces a “runnable” Web Service • Performs error checking • Checks not caught by the compiler

• Processing may happen at any time • At build time • In a tool • During deployment

• Left to the implementation

2005 JavaOneSM Conference | Session TS-7964 |

9

Processing Model Java™ 2 Platform, Enterprise Edition (J2EE™) Web Service generation Java Web Service (JWS) Source File

J2SE 1.5 Compiler

.class file containing annotations

Syntax and Type Checking

JSR-181 Processor Semantic Checking Deployment Artifact Generation

WSDL File

J2EE Deployment Descriptors

.class files for service and related types

J2EE 1.4 Deployment Unit (.ear or .war) 2005 JavaOneSM Conference | Session TS-7964 |

10

JSR 181 Runtime • • • •

Handles runtime behavior Exposes a “processed” Web Service at a URL Provides access to the service’s WSDL May be the same component as the processor

2005 JavaOneSM Conference | Session TS-7964 |

11

Agenda • JSR 181 • Development Models • Processor • Runtime

• • • • •

Annotations Reference Implementation Next Steps Summary Q&A 2005 JavaOneSM Conference | Session TS-7964 |

12

Annotations • JSR 175 • Purpose • Java technology to WSDL Mapping • Binding • Processing(Handlers)

• Defines smart defaults (Configuration by exception)

2005 JavaOneSM Conference | Session TS-7964 |

13

Annotations • • • • • • •

WebService OneWay WebParam WebResult SOAPBinding HandlerChain SoapMessageHandler(SoapMessageHandlers)

2005 JavaOneSM Conference | Session TS-7964 |

14

WebService • Marks a Java class as implementing a Web Service, or a Java technology interface as defining a Web Service interface • name • Sets the name of the WSDL <portType> for this service

• serviceName • Sets the name of the WSDL <service> generated for this service

• targetNamespace • Sets the XML namespace used for WSDL and schema elements defined from this service

• wsdlLocation • The location of a pre-defined WSDL 2005 JavaOneSM Conference | Session TS-7964 |

15

WebMethod • Specifies that the given method is exposed as a Web Service operation • operationName • Name of the wsdl:operation matching this method

• action • The action for this operation. For SOAP bindings, this determines the value of the SOAPAction header

2005 JavaOneSM Conference | Session TS-7964 |

16

Example 1—Hello World

@WebService public class HelloWorld { @WebMethod public String hello(){ return “Hello World!”; } }

2005 JavaOneSM Conference | Session TS-7964 |

17

Example 1—Hello World @WebService public class HelloWorld { @WebMethod (operationName=“hi”) public String hello(){ return “Hello World!”; } } <wsdl:message name="hello"> name=“hi"> <wsdl:part name="parameters" element="tns:helloRequest"/> element="tns:hiRequest"/> <wsdl:message name="helloResponse"> name=“hiResponse"> <wsdl:part name="return" element="tns:helloResponse"/> element="tns:hiResponse"/> <wsdl:portType name="HelloWorld"> <wsdl:operation name="hello"> name=“hi"> <wsdl:input message="tns:hello"/> message="tns:hi"/> <wsdl:output message="tns:helloResponse"/> message="tns:hiResponse"/> 2005 JavaOneSM Conference | Session TS-7964 |

18

Example 1—Hello World @WebService (serviceName=“myService”) public class HelloWorld { @WebMethod public String hello(){ return “Hello World!”; }

Default is class name + “Service” }

<wsdl:service name="myService"> name="HelloWorldService"> <wsdl:port name="HelloWorldServicePort“ binding="tns:HelloWorldBinding"> <soap:address location="…"/>

2005 JavaOneSM Conference | Session TS-7964 |

19

Oneway • Indicates that the given @WebMethod has only an input message and no output • Typically returns the thread of control to the calling application prior to executing the actual business method • The method must not have a return value or Holder parameters, or declare any checked exceptions

2005 JavaOneSM Conference | Session TS-7964 |

20

SOAPBinding • Indicates that this Web Service’s methods are to be mapped to the SOAP message protocol • Default is DOCUMENT/LITERAL/WRAPPED • style • DOCUMENT or RPC

• use • LITERAL or ENCODED

• parameterStyle • W RAPPED or BARE

2005 JavaOneSM Conference | Session TS-7964 |

21

WebParam • Controls the name and namespace of the return value • name • For RPC style this is the name of the wsdl:part • For DOCUMENT style this is the local name of the element • Default is the parameter name

• targetNamespace • The XML namespace for the element • Only used for DOCUMENT style • Default is the target namespace of the Web Service

• mode • IN, INOUT, or OUT • OUT and INOUT parameters must be Holder Types • OUT and INOUT parameters apply only to RPC style or parameters that map to headers

• header 2005 JavaOneSM Conference | Session TS-7964 |

22

WebResult • Provides fine-grained control over the name and namespace of the return • Binding determines behavior • name • For RPC style this is the name of the wsdl:part • For DOCUMENT style this is the local name of the element • Default is “return” • targetNamespace • The XML namespace for the element • Only used for DOCUMENT style • Default is the target namespace of the W eb Service 2005 JavaOneSM Conference | Session TS-7964 |

23

Example 2—RPC/ENCODED @WebService @SOAPBinding( style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.ENCODED) public class EchoService { @WebMethod(action=“echo”) @WebResult(name=“echoResult") public String echo( @WebParam(name=“echoMsg") String msg){ return msg; } }

2005 JavaOneSM Conference | Session TS-7964 |

24

Example 2—RPC/ENCODED @WebService @SOAPBinding(style=SOAPBinding.Style.RPC,use=SOAPBinding.Use.ENCODED) public class EchoService { @WebMethod(action=“echo”) @WebResult(name=“echoResult") public String echo( @WebParam(name=“echoMsg") String msg){ return msg; } } <message name="echo"> <part name=“echoMsg" type="s0:string"/> <message name="echoResponse"> <part name=“echoResult" type="s0:string"/> <portType name="EchoService">

2005 JavaOneSM Conference | Session TS-7964 |

25

Example 2—RPC/ENCODED @WebService @SOAPBinding(style=SOAPBinding.Style.RPC,use=SOAPBinding.Use.ENCODED) public class EchoService { … }

<s2:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <s2:operation soapAction=“echo" style="rpc"/> <s2:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://examples/EchoService" use="encoded"/>

<s2:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://examples/EchoService" use="encoded"/>

2005 JavaOneSM Conference | Session TS-7964 |

26

Example 3—DOCUMENT/LITERAL/BARE

@WebService @SOAPBinding(style=SOAPBinding.Style.DOCUMENT, use=SOAPBinding.Use.LITERAL, parameterStyle=SOAPBinding.ParameterStyle.BARE) public class EchoService { @WebMethod(action="echo") @WebResult(targetNamespace=“http://exa.org”, name="echoResult") public String echo( @WebParam(targetNamespace=“http://exa.org”, name="echoMsg") String msg){ return msg; } }

2005 JavaOneSM Conference | Session TS-7964 |

27

Example 3—DOCUMENT/LITERAL/BARE @WebService @SOAPBinding(style=SOAPBinding.Style.DOCUMENT, use=SOAPBinding.Use.LITERAL, parameterStyle=SOAPBinding.ParameterStyle.BARE) public class EchoService { @WebMethod(action="echo") @WebResult(targetNamespace=“http://exa.org”, name="echoResult") public String echo( @WebParam(targetNamespace=“http://exa.org”, name="echoMsg") String msg){ return msg; } } <wsdl:message name="echo"> <wsdl:part name="parameters" element="ns0:echoMsg"/> <wsdl:types> <xs:schema targetNamespace=“http://exa.org” <wsdl:message name="echoResponse"> xmlns:xs="http://www.w3.org/2001/XMLSchema"> <wsdl:part name="echoResult" element="ns0:echoResult"/> <xs:element name="echoResult" type="xs:string"/> <xs:element name="EchoService"> name="echoMsg" type="xs:string"/> <wsdl:portType <wsdl:operation name="echo"> <wsdl:input message="tns:echo"/> <wsdl:output message="tns:echoResponse"/> 2005 JavaOne

SM

Conference | Session TS-7964 |

28

Example 3—DOCUMENT/LITERAL/BARE @WebService @SOAPBinding(style=SOAPBinding.Style.DOCUMENT, use=SOAPBinding.Use.LITERAL, parameterStyle=SOAPBinding.ParameterStyle.BARE) public class EchoService { @WebMethod(action="echo") @WebResult(targetNamespace=“http://exa.org”, name="echoResult") public String echo( @WebParam(targetNamespace=“http://exa.org”, name="echoMsg") String msg){ return msg; } } <wsdl:binding name="EchoServiceBinding" type="tns:EchoService"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation <wsdl:types> name="echo"> <soap:operation soapAction="echo" style="document"/> <xs:schema targetNamespace=“http://exa.org” <wsdl:input name="echoInput"> xmlns:xs="http://www.w3.org/2001/XMLSchema"> <soap:body parts="parameters" use="literal" namespace="examples"/> <xs:element name="echoResult" type="xs:string"/> <xs:element name="echoMsg" type="xs:string"/> <wsdl:output name="echoOutput"> <soap:body parts="echoResult" use="literal" namespace="examples"/> 2005 JavaOneSM Conference | Session TS-7964 |

29

Example 4—Headers and Mode @WebService @SOAPBinding(style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.LITERAL) public class EchoHeaderService { @WebMethod public String echo( @WebParam(name="myHeader", header=true, mode=WebParam.Mode.INOUT) StringHolder header, String msg){ String ret = header.value + + ", " + msg; header.value = "got it"; return ret; } }

2005 JavaOneSM Conference | Session TS-7964 |

30

Example 4—Headers and Mode @WebMethod public String echo( @WebParam(name="myHeader", header=true, mode=WebParam.Mode.INOUT) StringHolder header, String msg){ String ret = header.value + ", " + msg; header.value = "got it"; return ret; } <wsdl:binding name="EchoHeaderServiceBinding" type="tns:EchoHeaderService"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="echo"> <soap:operation soapAction="" style="rpc"/> <wsdl:types> <wsdl:input name="echoInput"> <xs:schema <soap:bodytargetNamespace=“http://exa.org” parts="msg" use="literal" namespace="examples"/> xmlns:xs="http://www.w3.org/2001/XMLSchema"> <soap:header message="tns:echo" part="myHeader" use="literal"/> <xs:element name="echoResult" type="xs:string"/> <xs:element name="echoMsg" type="xs:string"/> <wsdl:output name="echoOutput"> <soap:body parts="return" use="literal" namespace="examples"/> <soap:header message="tns:echo" part="myHeader" use="literal"/> 2005 JavaOne Conference | Session TS-7964 SM

|

31

Example 4—Headers and Mode @WebMethod public String echo( @WebParam(name="myHeader", header=true, mode=WebParam.Mode.INOUT) StringHolder header, String msg){ String ret = header.value + ", " + msg; header.value = "got it"; return ret; } Request <soap:Envelope xmlns:ns0="examples“ xmlns:soap="…"> <soap:Header> <ns0:myHeader>Hello <soap:Body> <ns0:echo> <msg>How are you?

Response <soap:Envelope xmlns:soap="…"> <soap:Header> <exam:myHeader xmlns:exam="examples"> got it <soap:Body> <exam:echoResponse xmlns:exam="examples"> Hello, How are you? 2005 JavaOneSM Conference | Session TS-7964 |

32

HandlerChain • Associates the Web Service with an externally defined handler chain • XML—types are from the http://java.sun.com/xml/ns/j2ee namespace defined by JSR 109 • file • Location of the handler chain file • name • Name of the handler chain in the file

2005 JavaOneSM Conference | Session TS-7964 |

33

Example Handler Chain File MyHandlerChain <j2ee:handler-name>myHandler <j2ee:handler-class>foo.MyHandler <j2ee:init-param> <j2ee:param-name>offset <j2ee:param-value>1

2005 JavaOneSM Conference | Session TS-7964 |

34

SOAPMessageHandler • Specifies a list of javax.xml.rpc.handler.Handlers to run before and after the Web Service’s business method invocation • name • Name of the handler • className • Fully Qualified name of the handler class • InitParams • Array of name/value pairs passed to the handler during initialization • roles • List of SOAP roles implemented by the handler • headers • List of SOAP headers processed by the handler

2005 JavaOneSM Conference | Session TS-7964 |

35

SOAPMessageHandlers Example @WebService @SOAPMessageHandlers({ @SOAPMessageHandler( name = "myHandler", className = "foo.myHandler", initParams = {@InitParam(name="offset", value="1")}) }) public class MyWebService { }

2005 JavaOneSM Conference | Session TS-7964 |

36

SOAPMessageHandlers -> HandlerChain File @WebService @SOAPMessageHandlers({ @SOAPMessageHandler( name = "myHandler", className = "foo.myHandler", initParams = {@InitParam(name="offset", value="1")}) }) public class MyWebService{…} MyHandlerChain <j2ee:handler-name>myHandler <j2ee:handler-class>foo.MyHandler <j2ee:init-param> <j2ee:param-name>offset <j2ee:param-value>1

2005 JavaOneSM Conference | Session TS-7964 |

37

Agenda • JSR 181 • Development Models • Processor • Runtime

• • • • •

Annotations Reference Implementation Next Steps Summary Q&A 2005 JavaOneSM Conference | Session TS-7964 |

38

Reference Implementation • Demonstrates how 181 annotations affect the Java technology to WSDL mapping • Start with Java technology development mode only • Command line build processor • Rudimentary Runtime • Supports http transport via a Servlet

2005 JavaOneSM Conference | Session TS-7964 |

39

Reference Implementation

compil e Java Technology Source

produces JWSC Java WSC

deploy WAR File

Web Container

2005 JavaOneSM Conference | Session TS-7964 |

40

Java WSC—The RI compiler • • • • •

Command line tool Delegates to apt for annotation processing Javac for compiling Accepts javac and apt arguments Produces container agnostic war file

2005 JavaOneSM Conference | Session TS-7964 |

41

Java WSC Usage Usage: jwsc <jwsc and javac options> <source files> where jwsc options include: -classpath <path> Specify where to find user class files -cp <path> Specify where to find user class files -d <path> Specify where to place processor and javac generated class files -s <path> Specify where to place processor generated source files -source Provide source compatibility with specified release -version Version information -help Print a synopsis of standard options; use javac -help for more… -X Print a synopsis of nonstandard options -J Pass directly to the runtime system -A[key[=value]] Options to pass to jwsc, [debug] -nocompile Do not compile source files to class files -print Print out textual representation of specified types See javac -help for information on javac options.

2005 JavaOneSM Conference | Session TS-7964 |

42

Java WS—Testing

@WebService @SOAPBinding(style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.LITERAL) public class EchoHeaderService { @WebMethod public String echo( @WebParam(name="myHeader", header=true, mode=WebParam.Mode.INOUT) StringHolder header, String msg){ String ret = header.value + + ", " + msg; header.value = "got it"; return ret; } }

2005 JavaOneSM Conference | Session TS-7964 |

43

Java WS—Testing

2005 JavaOneSM Conference | Session TS-7964 |

44

Agenda • JSR 181 • Development Models • Processor • Runtime

• • • • •

Annotations Reference Implementation Next Steps Summary Q&A 2005 JavaOneSM Conference | Session TS-7964 |

45

Maintenance Release • Align with Java APIs for XML Web Services (JAX-WS) 2.0 • Clarify annotation inheritance scenarios • Annotation for setting name for of element wrappers for DOCUMENT/LITERAL/WRAPPED • Allow SOAPBinding annotation per method

2005 JavaOneSM Conference | Session TS-7964 |

46

JSR 181 2.0 • • • •

WSDL 2.0 SOAP 1.2 Support of JSR 250 Common Annotations Improving the quality of service • • • • • • •

Buffering Transactional support Reliability Callbacks Conversations Policy Beyond J2EE platform security 2005 JavaOneSM Conference | Session TS-7964 |

47

Summary • Rapid Web Service development • Reduced maintainability (one source of truth) • Accelerates SOA Implementation

2005 JavaOneSM Conference | Session TS-7964 |

48

For More Information •

JSR 181—Java Web Services Metadata •

•

Java Web Services Metadata Home—RI download •

•

http://www.jcp.org/en/jsr/detail?id=181 http://dev2dev.bea.com/webservices/jwsm.csp

Java Web Services Metadata in Beehive •

http://incubator.apache.org/beehive

Related Specs

•

JSR 101 Java API for XML-based RPC (JAXRPC •

•

JSR 109 J2EE™ Platform Web Services •

•

http://jcp.org/en/jsr/detail?id=109

JSR 175 Java Language Metadata •

•

http://jcp.org/en/jsr/detail?id=101

http://jcp.org/en/jsr/detail?id=175

JSR 224 JAX-WS 2.0 •

http://www.jcp.org/en/jsr/detail?id=224 2005 JavaOneSM Conference | Session TS-7964 |

49

Submit Session Evaluations for Prizes! Your opinions are important to Sun • You can win a $75.00 gift certificate to the on-site Retail Store by telling Sun what you think! • Turn in completed forms to enter the daily drawing • Each evaluation must be turned in the same day as the session presentation • Five winners will be chosen each day (Sun will send the winners email) • Drop-off locations: give to the room monitors or use any of the three drop-off stations in the Northand South Halls Note: Winners on Thursday, 6/30, will receive and can redeem certificates via email. 2005 JavaOneSM Conference | Session TS-7964 |

50

Q&A

2005 JavaOneSM Conference | Session TS-7964 |

51

Q&A

2005 JavaOneSM Conference | Session TS-7964 |

52

Java™ Web Services Development Using Annotations Brian Zotter Staff Engineer BEA Systems http://www.bea.com TS-7964 2005 JavaOne SM Conference | Session TS-7964

53