JAX RPC Speaker Noted

8/14/2019 JAX RPC Speaker Noted

1/130


2/130


3/130

3

3

Disclaimer & Acknowledgment

? Even though Sang Shin is a full-time employee of SunMicrosystems, the contents here is created as his ownpersonal endeavor and thus does not reflect any officialstance of Sun Microsystems.

? Sun Microsystems is not responsible for any inaccuracies inthe contents

? Acknowledgments

Some contents are borrowed from the presentationslides of Roberto Chinnici, Rahul Sharma, Phil Goodwin(all Sun Microsystems)

Some slides are created from JAX-RPC chapter of JavaWSDP tutorial

06/15/2005


4/130

4

4

Revision History? 10/01/2002: version 1, Created (Sang Shin)? 01/30/2004: version 2, updated (Sang Shin)? 10/07/2004: version 3, updated to reflect J2EE 1.4 sample code (Sang Shin)? Things to do

speaker notes need to be added to some slides

06/15/2005


5/130

5

5

Topics

? Background on remote communication? What is and Why JAX-RPC?? Development steps of a JAX-RPC Service? Type Mapping? Client Programming? Service Endpoint Model? Runtime Services? Packaging & Deployment

06/15/2005


6/130

6

6

Advanced Topics (We will talkabout this in Advanced JAX-RPC Session)

? SOAP message handlers? JAX-RPC runtime services

Security

Session management

? Attachment handling? JAX-RPC 1.1 and J2EE?

Interoperability? Extensible type mapping? Roadmap

06/15/2005


7/130

7

7

Background on

RemoteCommunication

06/15/2005


8/130

8

Remote Procedure Call (RPC)

? RPC, COM, CORBA, RMI:

Synchronous communication: calling processblocks until there is a response

More tightly coupled (than non-RPC model):

client must find recipients and know method andits arguments

Non persistent

Client System Server System

Request

Response

First, lets understand some background.

Remote Procedure Call is not a new technology. We have done

this between networked systems for a long time. Most recently,we have also seen some efforts to standardize the development

using CORBA and COM.

OMG Common Object Request Broker Architecture(CORBA) provided a platform neutral remote procedure callusing Interface Definition Language (IDL) and the Stubs and

Ties

COM on the Microsoft environment.

Java Remote Method Invocation(RMI) also provideddistributed programmingwithin Java environment and later

with IIOP to support other environments

These technologies were not interoperable and now with theexplosion of the web and the standatdisation of the HTTPprotocol, the industry has now decided to come up with one

standard so that we can interoperate between different systems

even though the implementations can be different.

06/15/2005


9/130

9

9

Remote Procedure Calls

Protocol Run TimeRun Time

ServantClient

Stub Tie

Interface Interface

? Common Interface between client and Server? Stub for client, Tie/skeleton for server? On-the-wire protocol needs to be agreed upon

06/15/2005


10/130

10

RPC Example Java RMI

Java Remote

Interface

Java Remote Method Protocol (JRMP) isOn-the-wire protocol

Remote ObjectImplementation

RMI ServerSkeleton

RMI ClientStub

rmic compiler

Client

? Before we look at JAX-RPC, lets try to understand as to how RMI

worked in Java?? BTW How many of you have used RMI?? Here, as a developer, we need to first create an interface file with the

methods and signatures of the remote access methods.?

Then we create the implementation in Java? Then we use the RMIC compiler which will generate the Stubs for

the client side and Skeleton code for the server side to marshall and

unmarshall the Java data types to be transported over the wire using

JRMP thus making it easy to do remote access transparent/easy to the

developer.? JAX-RPC also does similar thing of making it easy to develop and also

be able to interoperate between heterogenerous systems and we will see

as to how it works.

06/15/2005


11/130

11

11

RPC Example - JAX-RPC

06/15/2005


12/130

12

12

Common Interface

? Service is described in IDL (InterfaceDescription Language) IDL of CORBA service

Java RMI interface in RMI (Language specific)

WSDL for Web service

? Used by tools to statically or dynamicallygenerate and/or configure interfaces,

proxies, and ties in a networktechnology specific environment

06/15/2005


13/130

13

13

Concept of XML-Based RPC

? Uses Standards based on XML SOAP is the protocol

WSDL is the IDL

? Any communication protocol can beused as a transport e.g.) HTTP, SMTP, FTP etc.

06/15/2005


14/130

14

14

Why

XML-based RPC?

06/15/2005


15/130

15

15

Does XML-based RPC make

sense?? Text is not an efficient way to encode

data

? XML just makes it worse

verbose in nature

slower

? I thought HTTP was for web pages...

06/15/2005


16/130

16

16

Why XML based RPC on the

Internet?? Everyone is already connected and using

HTTP? XML is an accepted standard

? SOAP will go through firewalls

Can be filtered when it becomes a problem

? RPC is an easy programming model

Messaging (document-driven) model is gaining amomentum, however

? JAX-RPC supports document-driven modelas well

06/15/2005


17/130

17

17

What isJAX-RPC?

06/15/2005


18/130

18

18

What is JAX-RPC?

? Java API for XML-based RPC

Web Services operations are performed byexchanging SOAP 1.1 messages

? Services are described using WSDL WSDL is the contract between service provider

and client (only contract needed)

? Web service endpoints and clients use

JAX-RPC programming model

? Key technology for Web Services in theJ2EE 1.4 platform

T

06/15/2005


19/130

19

19

JAX-RPC Design Goals? Easy to use programming model

For both defining & using a service

? Hides all the plumbing You don't have to create SOAP messages yourself

? SOAP and WSDL-based interoperability Interoperate with any SOAP 1.1 compliant peers

? Extensibility and Modularity Support new versions of XML specification, i.e.

SOAP 1.2 and beyond

Message handler architecture

What are the design goals of JAX-RPC? There are several.

?Simplicity is an important element in making the JAX-RPC model easy to

understand, implement, maintain and evolve. This goal of simplicity applies to

both defining and building JAX-RPC service and using the service. Part of the

simplicity goal is achieved by following the standard Java applicationprogramming model and concepts. For example, a JAX-RPC service is defined

as a Java interface type.

?Another goal is to support interoperability across heterogeneous platforms and

environments. The specification describes the conformance and interoperability

requirements that are testable for an implementation of the JAX-RPC

specification. For example, a JAX-RPC service can be used by service clientsdeployed on any platform. Also JAX-RPC service definition makes no

assumption that the service be used only by a Java based service client. Theconverse also holds. That is, a Java service client is capable of using an XML

based RPC service deployed on a non Java platform.

?Keep the design of JAX-RPC APIs and mechanisms extensible and modular.

This will enable support for future versions of various XML specifications,

including XMLP (SOAP 1.2)

06/15/2005


20/130

20

20

JAX-RPC Architecture

Server-side JAX-RPCRuntime Syste m

Container

JAX-RPCService Endpoint

WSDLJava

WSDLDocument

HTTP

Clien t-side JAX-RPCRuntime Syste m

SOAP

Container

JavaWSDLGenerated Code

JAX-RPCClient

06/15/2005


21/130

21

21

JAX-RPC Runtime System

?

Core of a JAX-RPC implementation: Library that provides runtime services

for JAX-RPC mechanisms

Implements some of the JAX-RPC APIs

? Client side:

Can be implemented over J2SE, J2EE orJ2ME platforms

? Server-side:

J2EE 1.3 or 1.4 Containers: EJB or Servlet

06/15/2005


22/130

22

22

Development Steps of

JAX-RPC Service(HelloService Example)

06/15/2005


23/130

23

23

Developing a Web Service

tool

Interfaces (java.rmi.Remote type)Must follow JAX-RPC conventions

Implementation classesServlet-based endpoint modelOptional handler and serializer classes

Packaged application (war file)

WSDL Service contract

06/15/2005


24/130

24

24

You can start from WSDL as well

(proceed as before)

Contract for the serviceyou want to implement

Generated interfaces andvalue types

Implementation classes

06/15/2005


25/130

25

25

JAX-RPCWeb Service Endpoint

HTTP

Server-SideJAX-RPC

Runtime System

SOAP

Container

JAX-RPCService Endpoint

WSDLJava

WSDLDocument

06/15/2005


26/130

26

26

Steps for Developing a JAX-RPC

Web Service and Client1. Code the Service Endpoint Interface (SEI) and

implementation class and interface configuration file.

2. Compile the SEI and implementation class.

3.Use wscompile utility program to generate the WSDLand other files required to deploy the service.

4. Package the files into a WAR file.

5. Deploy the WAR file.

6. Code the client class and WSDL configuration file.

7.Use wscompile to generate and compile the stub files.

8. Compile the client class.9. Run the client.

These are the basic steps for creating theWeb service and its client.

06/15/2005


27/130

27

27

1.a Code Service Endpoint Interface

? Declares the methods that a remote clientmay invoke on the service

? Rules It extends thejava.rmi.Remote interface

It must not have constant declarations, such aspublic final static

The methods must throw the

java.rmi.RemoteException or one of itssubclasses

Method parameters and return types must besupported JAX-RPC types

A service endpoint interface declares the methods that a remoteclient may invoke on the service. In this example, the interface

declares a single method named sayHello.

A service endpoint interface must conform to a few rules:

* It extends the java.rmi.Remote interface.

* It must not have constant declarations, such as public finalstatic.

* The methods must throw the java.rmi.RemoteException or

one of its subclasses. (The methods may also throw service-

specific exceptions.)

* Method parameters and return types must be supported JAX-RPC types.

06/15/2005


28/130

28

28

Example: Service Definition Interface(HelloIF.java from helloservice)

package helloservice;

import java.rmi.Remote;

import java.rmi.RemoteException;

public interface HelloIF extends Remote {

public String sayHello(String s) throws RemoteException;

}

So this is an example service definition interface. The name of the serviceis HelloIF. Note that it extendsjava.rmi.Remote. And the methods throw

java.rmi.RemoteException.

If you notice a similarity between service definition interface and a remoteinterface of EJB beans, you are correct. They are in fact quite similar.

06/15/2005


29/130


30/130

30

30

Example: Service Implementation(HelloImpl.java from helloservice)

package helloservice;

public class HelloImpl implements HelloIF {

public String message ="Hello";

public String sayHello(String s) {return message + s;

}

}

06/15/2005


31/130

31

31

1.c Interface configuration file.

? Specifies information about the SEI

? Used by wscompile to generate WSDL

The wscompile tool reads an interface configuration file that

specifies information about the SEI.

This configuration file tells wscompile to create a WSDL file

named MyHelloService.wsdl with the following information:

* The service name is MyHelloService.

* The WSDL target and type namespace is urn:Foo. Thechoice for what to use for the namespaces is up to you. The role

of the namespaces is similar to the use of Java package names--to

distinguish names that might otherwise conflict. For example, a

company can decide that all its Java code should be in the

package com.wombat.*. Similarly, it can also decide to use thenamespace http://wombat.com.

* The SEI is helloservice.HelloIF.

The packageName attribute instructs wscompile to put the

service classes into the helloservice package.

06/15/2005


32/130

32

32

2. Compile the SEI andimplementation class

? asant compile-service

? Compile Service definition interfaceand implementation classes HelloIF.java

HelloImpl.java

This asant task compiles HelloIF.java and HelloImpl.java,

writing the class files to the build subdirectory.

06/15/2005


33/130

33

33

3. Use wscompile to generate theWSDL and other files

? asant generate-wsdl wscompile -define -mapping

build/mapping.xml -d build -nd build

-classpath build config-interface.xml

? Generates WSDL document (MyHelloService.wsdl)

Mapping file (mapping.xml)? contains information that correlates the mapping

between the Java interfaces and the WSDLdefinition

? portable

The generate-wsdl task runs wscompile, which creates the WSDL

and mapping files. The WSDL file describes the Web service andis used to generate the client stubs in Static Stub Client. The

mapping file contains information that correlates the mapping

between the Java interfaces and the WSDL definition. It is meantto be portable so that any J2EE-compliant deployment tool canuse this information, along with the WSDL file and the Java

interfaces, to generate stubs and ties for the deployed Web

services.

The files created in this example are MyHelloService.wsdl and

mapping.xml. The generate-wsdl task runs wscompile with the

following arguments:

wscompile -define -mapping build/mapping.xml -d build -nd

build

-classpath build config-interface.xml

The -classpath flag instructs wscompile to read the SEI in the

build directory, and the -define flag instructs wscompile to create

WSDL and mapping files. The -mapping flag specifies themapping file name. The -d and -nd flags tell the tool to write

class and WSDL files to the build subdirectory.

06/15/2005


34/130

34

34

MyHelloService.wsdl

This is the WSDL document that is generated.

06/15/2005


35/130

35

35

MyHelloService.wsdl (continued)

Continuation of the WSDL document.

06/15/2005


36/130

36

36

mapping.xml (page 1)

helloservice

urn:Foo

helloservice.MyHelloService

serviceNS:MyHelloService

HelloIFPort

HelloIFPort

This is mapping.xml file that is generated.

06/15/2005


37/130

37

37

mapping.xml (continued)

helloservice.HelloIF

portTypeNS:HelloIFbindingNS:HelloIFBinding

sayGoodbye

sayGoodbye

0java.lang.String

wsdlMsgNS:HelloIF_sayGoodbyeString_1IN

java.lang.StringwsdlMsgNS:HelloIF_sayGoodbyeResponsresult

U

06/15/2005


38/130

38

38

mapping.xml

sayHellosayHello

0

java.lang.String

wsdlMsgNS:HelloIF_sayHello

String_1IN

java.lang.String

wsdlMsgNS:HelloIF_sayHelloResponse

result

U

06/15/2005


39/130

39

39

4. Package the files into war file

? asant create-war hello-jaxrpc.war is created

O

06/15/2005


40/130

40

40

5. Deploy the WAR file

? asant deploy-war hello-jaxrpc.war is deployed

? The tie classes (which are used tocommunicate with clients) are generatedby the Application Server duringdeployment.

O

06/15/2005


41/130

41

41

WSDL of the Helloservice Service

? Deploy as a Web application

T

06/15/2005


42/130


43/130

43

43

Why Type Mapping?

? SOAP, WSDL do not define the mappingbetween XML and a particularProgramming language SOAP and WSDL are designed to be

programming language independent

Difference from CORBA world

? Yet, we need a standard way of mapping

between the two Otherwise, we will have interoperability problem

X

06/15/2005


44/130

44

44

Type MappingMapping of XML Data

types to Java Data types

06/15/2005


45/130

45

45

XML Data Types to Java Mapping

? Simple built-in type

xsd:stringtojava.lang.String

? Array

Mapped into a Java array

? Enumeration of simple built-in type

Mapped into an enumeration Java class

?

XML Struct and Complex type Mapped into JavaBeans with getter and

setter methods

XML data types that can be mapped to Java data types include simpletypes such as the ones defined in W3C XML schema. For example, stringtype element will be mapped intojava.lang.String class while dateTime

will be mapped intojava.util.Calendar class.

Other types that JAX-RPC specification describes include array andenumeration and XML structure and complex types.

A structure type will be mapped into a JavaBeans with correspondinggetter and setter methods.

06/15/2005


46/130

46

46

Example: XML Enumeration to Java Mapping

// Java Representationpublic class EyeColor implements java.io.Serializable {

// Constructorprotected EyeColor(String value) { ... }

public static final String _green = green;public static final String _blue = blue;

public static final EyeColor green = new EyeColor(_green);public static final EyeColor blue = new EyeColor(_blue);

public String getValue() { ... }public static EyeColor fromValue(String value)

throws java.lang.IllegalStateException { ... }public boolean equals(Object obj) { ... }

public int hashCode() { ... }}

This is an example of how XML enumeration data typecan be represented in Java class.

06/15/2005


47/130

47

47

Example: XML Struct to Java Mapping

// Javapublic class Book implements java.io.Serializable {

// ...

public String getAuthor() { ... }

public void setAuthor(String author) { ... }

public String getPreface() { ... }

public void setPreface(String preface) { ... }public float getPrice() { ... }public void setPrice(float price) { ... }

}

This is an example of how XML structure data type willbe represented in Java class. As was mentioned before, aXML structure will be represented by a JavaBean withgetter and setter methods for each member of the

structure.

06/15/2005


48/130

48

48

Type MappingMapping of Java Data

types to XML Data types

06/15/2005


49/130

49

49

Java to XML Type Mapping

? Mapping from the Java types to the XMLdata types

? Performed by the JAX-RPC runtimesystem

? Only JAX-RPC supported Java typescan be passed as parameters and returnvalues

Behind the scenes, JAX-RPC maps types of the Java programminglanguage to XML/WSDL definitions. For example, JAX-RPC maps thejava.lang.String class to the xsd:string XML data type. Applicationdevelopers don't need to know the details of these mappings, but theyshould be aware that not every class in the Java 2 Platform, Standard

Edition (J2SE) can be used as a method parameter or return type in JAX-RPC.

06/15/2005


50/130

50

50

Supported Types

? Subset of J2SE classes

? Collections? Primitives? Arrays

? Value types? JavaBeans

06/15/2005


51/130

51

51

Subset of J2SE classes

? java.lang.Boolean, java.lang.Byte,java.lang.Double, java.lang.Float,java.lang.Integer, java.lang.Long, java.lang.Short, java.lang.String

? java.math.BigDecimal,java.math.BigInteger

? java.net.URI? java.util.Calendar, java.util.Date

JAX-RPC supports the J2SE SDK classes mentioned above.

06/15/2005


52/130

52

52

Collections

? List ArrayList, LinkedList, Stack, Vector

? Map HashMap, Hashtable, Properties, TreeMap

? Set HashSet, TreeSet

This release of JAX-RPC also supports several implementation classes ofthe java.util.Collection interface.

06/15/2005


53/130

53

53

Primitives & Wrapper classes

? boolean

? byte? double? float

? int? long

? short

J

06/15/2005


54/130

54

54

Arrays

? Arrays with members of supported JAX-RPC types

? Examples int[]

String[]

BigDecimal[][]

JAX-RPC also supports arrays with members of supported JAX-RPCtypes. Examples of supported arrays are int[] and String[].Multidimensional arrays, such as BigDecimal[][], are also supported.

06/15/2005


55/130

55

55

Value Types

? A value type is a class whose state maybe passed between a client and remoteservice as a method parameter or returnvalue

? Example Book class which contains the fields Title,

Author, and Publisher

A value type is a class whose state may be passed between a client andremote service as a method parameter or return value. For example, inan application for a university library, a client might call a remoteprocedure with a value type parameter named Book, a class thatcontains the fields Title, Author, and Publisher.

06/15/2005


56/130


57/130

57

57

Example: Value Types

public class MeetingInfo {

// private fieldsprivate String id;

// public fields does not need getter// setter methodspublic String address;

// has to have getter and setter for// non-public fieldspublic String getID() { ... }public void setID(String id){ ... }

}

06/15/2005


58/130

58

58

JavaBeans

? Must have a getter and setter method foreach bean property

? The type of the bean property must be asupported JAX-RPC type

JAX-RPC also supports JavaBeans components, which must conform tothe same set of rules as application classes. In addition, a JavaBeanscomponent must have a getter and setter method for each bean property.The type of the bean property must be a supported JAX-RPC type.

06/15/2005


59/130

59

59

Example: JavaBean Typepublic class AddressBean implements java.io.Serializable {

private String street;private String city;private String state;private String zip;

public AddressBean() { }

public AddressBean(String street, String city) {this.street = street;this.city = city;

}

public String getStreet() {return street;

}public void setStreet(String street) {

this.street = street;}

public String getCity() {return city;

}public void setCity(String city) {

this.city = city;}...

}

06/15/2005


60/130

60

60

WSDL to JavaMapping

06/15/2005


61/130

61

61

WSDL & JAX-RPC

? Services are described using WSDL? WSDL is the only contract needed

between service provider and client? JAX-RPC tools in J2EE 1.4 SDK

wscompile tool creates abstract part of WSDLfrom Service definition interface (server side)

wsdeploy tool creates complete WSDLincluding port address and tie classes (serverside)

wscompile tool also creates stubs (client side)

This session is a high-level overview of JAX-RPC, whichstands for Java API for XML-based RPC.

06/15/2005


62/130

62

62

WSDLDocument

WSDL View of a Web Service

Service A" "Binding FooB

SOAP/ HTTP

" "Port Type FooPT

" "Operation Op1

" "Operation Op2Service B

" "Port Bar

" "Port Xyz

Port ...

Http:// .../foo

" "Port Foo

06/15/2005


63/130

63

63

JAX-RPC Relationship to WSDL

JAX-RPC describes a Web Service as acollection of remote interfaces and methods

Tools are used to convert between WSDLdocuments and sets of Java remoteinterfaces (example:wscompile)

WSDL describes a Web Service as acollection of ports and operations

06/15/2005


64/130

64

64

From the JAX-RPC API to WSDLand Back

JAX-RPC

Service interface

- remote interfaces

- methods

value types

exceptions

WSDL

- 's/'s

- 's

complex types (schema)

faults

? The JAX-RPC API specifies all thedetails of the mapping to/from WSDL:

06/15/2005


65/130

65

65

WSDL to Java Mapping Rules

? A WSDL document into a Java Package

? Abstract part of WSDL into Java interfacesand classes wsdl:portType, wsdl:operation, wsdl:message

? Concrete binding part of WSDL into Javarepresentation

wsdl:binding, wsdl:port, wsdl:service

Now let's talk about WSDL to Java mapping.Each WSDL document will be mapped into a separateJava package.

JAX-RPC defines how abstract elements of WSDLdocuments, that is, portType, operation and messageelements ought to be represented as Java interface typeand its methods.

It also defines how concrete binding part of WSDLdocument are to be mapped into Java representation. The

concrete binding part part of WSDL document includebinding element, port element, and service element.So let's take a look at these in a bit detail.

06/15/2005


66/130

66

66

WSDL to Java MappingMapping of Abstract Part

of WSDL

06/15/2005


67/130

67

67

WSDL portType/operation/message

? Awsdl:portTypemaps into a Java Interface(Service Definition Interface) that extends

java.rmi.Remote? A wsdl:operationis mapped into a method of

the Service definition interface? wsdl:message'sare mapped into parameters

of the method? wsdl:type'sof wsdl:message'sare mapped

into the types of the parameters

So this is the set of rules that are defined by JAX-RPCspecification regarding how to represent abstract part ofan WSDL document into corresponding Javarepresentations.

First, portType element, which is a collection ofoperations, maps into a corresponding Java interfacetype. This Java interface type is called ServiceDefinition Interface. And we already saw an example ofService definition interface type. As was said before, theservice definition interface extends java.rmi.Remote.

The operation element is mapped into a method of theservice definition interface while the message elementsare mapped into the parameters of that method.

So let's take a look at an example.

06/15/2005


68/130

68

68

Example: Mapping of WSDL portTypeto Java Service Definition Interface


69/130

69

69

Why Remote interface forPortType?? Remote interface abstractly describes a

remote service in Java world it does not dictate how it is implemented

? The actual backend implementation cantake various forms on a Java platform RMI service

Jini or JavaSpaces service

EJB

Web service

Now let's talk about WSDL to Java mapping.Each WSDL document will be mapped into a separateJava package.

JAX-RPC defines how abstract elements of WSDLdocuments, that is, portType, operation and messageelements ought to be represented as Java interface typeand its methods.

It also defines how concrete binding part of WSDLdocument are to be mapped into Java representation. The

concrete binding part part of WSDL document includebinding element, port element, and service element.So let's take a look at these in a bit detail.

06/15/2005


70/130

70

70

WSDL to Java MappingMapping of Concrete

Binding Part of WSDL

06/15/2005


71/130

71

71

WSDL binding/port/service

? wsdl:serviceis mapped into animplementation ofjavax.xml.rpc.Serviceinterface

? JAX-RPC runtime provides theimplementation

A service element in a WSDL document represents an aggregated set ofports, with each port defined with a specific binding with a specificportType. That is, with binding and port elements, the service elementbinds the abstract definition ofportType element with concrete XML and

transport protocol and their endpoint address, for example, SOAP over HTTPas concrete XML and transport protocol respectively and a particular URL asan end point address.

06/15/2005


72/130

72

72

WSDL binding/port/service

? Ajavax.xml.rpc.Service class acts asa factory of Instance of a generated stub class

Dynamic proxy for a service port

Instance of the typejavax.xml.rpc.Call for thedynamic invocation of a remote operation ona service port

Under JAX-RPC, the service element is mapped intojavax.xml.rpc.Serviceinterface type, which in turn acts as a factory of the following:?Dynamic proxy for a service port.?Instance of the type javax.xml.rpc.Call for the dynamic invocation of aremote operation on a service port.?Instance of a generated stub class.

06/15/2005


73/130

73

73

Example: WSDL binding, port, service

My first service

This is a snippet from an example WSDL document. Thissnippet shows the concrete binding part of a WSDLdocument. So in this example, the portType calledStockQuotePortType is bound to SOAP and HTTP as

XML and transport protocol respectively.

This service has one communication endpoint which isrepresented by one port element which specifies theendpoint address for a particular protocol. And in thisexample, the address of the endpoint happened to behttp://example.com/stockquote.

Now let's see how this part of WSDL documents mappedinto a Java representation in the following example.

06/15/2005


74/130

74

74

javax.xml.rpc.Servicepackage javax.xml.rpc;public interface Service {

public java.rmi.Remote getPort(QName portName,Class proxyInterface)

throws JAXRPCException;

public Call createCall(QName portName)throws JAXRPCException;

public Call createCall(QName portName, String operationName)throws JAXRPCException;

public Call createCall() throws JAXRPCException;

public java.net.URLgetWSDLDocumentLocation();public QNamegetServiceName();public java.util.Iterator getPorts();

}

This is thejavax.xml.rpc.Servicejava interface type that is defined by JAX-RPCspecification. A JAX-RPC 1.0 implementation is required to provide the implementationclass for thejavax.xml.rpc.Service interface. That is, it is the platform vendor'sresponsibility to implement this interface. The implementation class is required to supportthe creation of both dynamic proxies and Call objects.

The getPort method returns a dynamic proxy for the specified service port. A service clientuses this dynamic proxy to invoke operations on the target service port. The

proxyInterface parameter specifies the service definition interface that is supported by thecreated dynamic proxy.

The method getPorts returns a list of qualified names (as javax.xml.rpc.namespace.QName) of ports grouped by this service.

The multiple variants of the method createCall create instances of thejavax.xml.rpc.Call.

The javax.xml.rpc.Call interface provides support for the dynamic invocation of anoperation on the target service port. A client side JAX-RPC 1.0 implementation is requiredto implement the Call interface. Thejavax.xml.rpc.Service interface acts as a factory forthe creation of Call instances.

The Service implementation class is required to implement java.io.Serializable andjavax.naming.Referenceable interfaces to support registration in the JNDI namespace.

06/15/2005


75/130

75

75

javax.xml.rpc.Callpackage javax.xml.rpc;public interface Call {

static public final int PARAM_MODE_IN = 1;static public final int PARAM_MODE_OUT = 2;

static public final int PARAM_MODE_INOUT = 3; public void addParameter(String paramName, QName xmlType, int parameterMode);

public void setReturnType(QName xmlType);public void removeAllParameters();

public String getOperationName();public void setOperationName(String operationName);

public QName getPortTypeName();public void setPortTypeName(QName portType);

public String getTargetEndpointAddress();public void setTargetEndpointAddress(String address);

public void setProperty(String name, Object value) throws JAXRPCException;public Object getProperty(String name);

public void removeProperty(String name); // Remote Method Invocation methods

public Object invoke(Object[] params) throws java.rmi.RemoteException;public void invokeOneWay(Object[] params) throws javax.xml.rpc.JAXRPCException;

}

06/15/2005


76/130

76

76

WSDL to Java Mapping

Mapping Tool

06/15/2005


77/130

77

77

Typical WSDL to Java Mapping Tool

? Reads WSDL document and thengenerates Service interface (javax.xml.rpc.Service) and its

implementation

Service definition interface (Extension ofjava.rmi.Remote)

Stub and tie classes

Additional classes? serializers, deserializers

Now because JAX-RPC specification defines the preciserules on how a WSDL document maps intocorresponding Java representation, it is expected that themapping process will be automated by the use of tools.

So a WSDL to Java mapping tool reads a WSDLdocument and then generates service interface and itsimplementation class, service definition interface thatextends thej a v a . r mi . Re mo t e , stub class thatimplements thej a v a x . x ml . r p c . S t u b interface and

any additional classes needed by the service and stubclasses. These additional classes include serializers,

deserializers, holders and utility classes.In fact, many of the tools out there are already doingthese things. Now JAX-RPC standardize the mappingprocess.

06/15/2005


78/130

78

78

SOAP BindingSupport in JAX-RPC

06/15/2005


79/130

79

79

SOAP Binding in WSDL

? JAX-RPC supports SOAP binding specifiedin WSDL 1.1: rpc and document style operations

literal and encoded representations

? Mapping of literal message part (either aparameter or return value):

Using Java data binding API: JAXB API

Mapping to SOAPElement as a document fragment

? Faults are mapped to Java exceptions

06/15/2005


80/130


81/130

81

81

Client ProgrammingModel

06/15/2005


82/130

82

82

JAX-RPC Client Environment

? Independent of how an XML based RPCservice (service endpoint) is implemented onthe server side

? Generates a Java based client siderepresentation for a service from WSDLdocument

? Must not be exposed or tied to a specific XMLbased protocol, transport or any JAX-RPCimplementation specific mechanism

? Can use either J2SE or J2EE programmingmodel

Now let's talk about JAX-RPC client environment.

Service client programming model must be independent of how an XML basedRPC service is implemented on the server side. A service client must invoke a

service using the same client programming model irrespective of whether aservice has been defined on the J2EE platform or even on a non-Java platform,

for example.

Service client environment should be capable of importing a WSDL documentand generating a Java based client side representation for a service described in

the WSDL document. A client side representation includes classes generatedbased on the mapping of the WSDL definitions to the corresponding Java

representation.

Service client programming model must not be exposed or tied to a specific

XML based protocol, transport or any JAX-RPC implementation specificmechanism. For example, a JAX-RPC client should not be exposed to how a

JAX-RPC client side runtime system invokes a remote method using a specificimplementation level interaction mode and connection management.

06/15/2005


83/130

83

83

J2EE based Service ClientProgramming Model

? JAX-RPC specification suggests howJ2EE components (servlet, EJB's) actas JAX-RPC clients

To be aligned with EJB 2.1, JSR 109, J2EE1.4 JSR efforts

? Follows J2EE programming anddeployment model Use JNDI to find JAX-RPC service instance

Then use JAX-RPC client invocation model

If JAX-PRC clients are developed and deployed as J2EE components such as

servlets or EJB's, then they have to follow corresponding J2EE programmingand deployment models. By the way, the client model of JAX-RPC will be

used as client model of JSR 109, which is in the process of defining a Webservices framework for J2EE platforms.

The component provider which implements a JAX-RPC client references anexternal service using a logical name called service reference. The componentprovider must use the service reference to get access to the service ports as

follows: The component provider assigns an entry in the components environment tothe service reference. The component provider uses the deployment descriptor

to declare a service reference. Then the component provider looks up aninstance of a service class using the JNDI namespace.

The component provider uses an appropriate method on the looked upservice instance to get one or more proxy objects for the target service port. A

proxy for a service port can be either a dynamic proxy or an instance of agenerated stub class. The latter implements the service definition interface.

The looked up service instance and proxy for the service port are returnedproperly configured for invocations of operations on the target service. The

deployer and container specific implementation take the responsibility ofmanaging the configuration of the service instance and proxy. These details

are not exposed to the J2EE based client programming model.

06/15/2005


84/130

84

84

Client Service Invocation

Programming Models

? Stub-based Both Interface and implementation are

created at compile time

? Dynamic proxy Interface is created at compile time while

implementation created at runtime

? Dynamic invocation interface (DII) Both interface and implementation are created at

runtime

06/15/2005


85/130


86/130

86

86

Stub-based Invocation Model

? Stub class gets generated from WSDL atcompile time

? All needed value classes are also generated? Instantiated using the Service class? Stub class is bound to a specific XML protocol

(i.e. SOAP) and transport (i.e. HTTP)

? Static compilation gives maximum performance

? Stub class implementsjavax.xml.rpc.Stubinterface

Service Definition Interface

06/15/2005


87/130

87

87

Stub Class Hierarchy

javax.xml.rpc.Stub

com.example.stockQuoteProvider

com.example.StockServiceSoapBinding_Stub

06/15/2005


88/130

88

88

Steps of Coding Static Stub Client

? Creates a Stub object (Stub)(new MyHelloService_Impl().getHelloIFPort())

? Sets the endpoint address that the stub usesto access the service stub._setProperty

(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, args[0]);

? Casts stub to the service endpoint interface,

HelloIF HelloIF hello = (HelloIF)stub;

Before it can invoke the remote methods on the stub the client performs thesesteps:

1. Creates a Stub object:

(Stub)(new MyHelloService_Impl().getHelloIFPort())

The code in this method is implementation-specific because it relies on aMyHelloService_Impl object, which is not defined in the specifications. TheMyHelloService_Impl class will be generated by wscompile in the followingsection.

2. Sets the endpoint address that the stub uses to access the service:

stub._setProperty(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, args[0]);

At runtime, the endpoint address is passed to HelloClient in args[0] as acommand-line parameter, which ant gets from the endpoint.address property inthe build.properties file.

3. Casts stub to the service endpoint interface, HelloIF:

HelloIF hello = (HelloIF)stub;

06/15/2005


89/130

89

89

Stub Configuration

? Stub instance must be configured XML protocol binding (compile time configuration)

endpoint address (can be set at runtime)

? Can be configured in two ways Static configuration (Compile time) based on

the WSDL description of a target serviceendpoint

? wsdl:binding, soap:binding, wsdl:port

Runtime configuration using thejavax.xml.rpc.StubAPI

06/15/2005


90/130

90

90

Standard Properties for Stub

Configuration? Username for authentication (required)? Password for authentication (required)

? Target service endpoint address(optional)

? Flag for "session enabled" (required)

06/15/2005


91/130

91

91

Static stub based clientpackage staticstub;import javax.xml.rpc.Stub;

public class HelloClient {

private String endpointAddress;public static void main(String[] args) {

System.out.println("Endpoint address = " + args[0]);try {

Stub stub = createProxy();stub._setProperty(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,args[0]);

HelloIF hello = (HelloIF)stub;System.out.println(hello.sayHello("Duke!"));

} catch (Exception ex) {ex.printStackTrace();

}}private static Stub createProxy() {

// Note: MyHelloService_Impl is implementation-specific.return (Stub) (new MyHelloService_Impl().getHelloIFPort());

}

J

06/15/2005


92/130

92

92

Client Programming Model

Dynamic Proxy based

06/15/2005


93/130

93

93

Dynamic Proxy-based Invocation

Model? Stubs are generated on the fly by JAX-

RPC client runtime? Application provides the service

definition interface the dynamic proxyconforms to

? Does not depend on implementationspecific class

? Portable client code

The client in the preceding section used a static stub for the proxy. In contrast,

the client example in this section calls a remote procedure through a dynamicproxy, a class that is created during runtime. Although the source code for the

static stub client relied on an implementation-specific class, the code for thedynamic proxy client does not have this limitation.

06/15/2005


94/130

94

94

Steps of Coding Dynamic Proxy

Client

1.Creates a Service object

2.Create a proxy with a type of the serviceendpoint interface










06/15/2005


95/130

95

95

Step1: Create a Service objectService helloService =

serviceFactory.createService(helloWsdlUrl,

new QName(nameSpaceUri, serviceName));

? Service object is a factory for proxies? Service object itself is created fromServiceFactory object

? Parameters of createService()? URL of the WSDL file

? QName object

A Service object is a factory for proxies. To create the Service object(helloService), the program calls the createService method on another type offactory, a ServiceFactory object.

The createService method has two parameters, the URL of the WSDL file and a

QName object. At runtime, the client gets information about the service bylooking up its WSDL. In this example, the URL of the WSDL file points to theWSDL that was deployed with MyHelloService:

http://localhost:8080/hello-jaxrpc/hello?WSDL

A QName object is a tuple that represents an XML qualified name. The tuple iscomposed of a namespace URI and the local part of the qualified name. In theQName parameter of the createService invocation, the local part is the servicename, MyHelloService.

06/15/2005


96/130

96

96

Step2: Create a Dynamic Proxy objectdynamicproxy.HelloIF myProxy =

(dynamicproxy.HelloIF)helloService.getPort(

new QName(nameSpaceUri, portName),

dynamicproxy.HelloIF.class);

? HelloIF.class is generated by wscompile (atcompile time)

?

The port name (HelloIFPort) is specified bythe WSDL file

A Service object is a factory for proxies. To create the Service object(helloService), the program calls the createService method on another type offactory, a ServiceFactory object.

The createService method has two parameters, the URL of the WSDL file and a

QName object. At runtime, the client gets information about the service bylooking up its WSDL. In this example, the URL of the WSDL file points to theWSDL that was deployed with MyHelloService:

http://localhost:8080/hello-jaxrpc/hello?WSDL

A QName object is a tuple that represents an XML qualified name. The tuple iscomposed of a namespace URI and the local part of the qualified name. In theQName parameter of the createService invocation, the local part is the servicename, MyHelloService.

06/15/2005


97/130

97

97

Example: Dynamic Proxy Client (1)package dynamicproxy;

import java.net.URL;import javax.xml.rpc.Service;import javax.xml.rpc.JAXRPCException;import javax.xml.namespace.QName;import javax.xml.rpc.ServiceFactory;import dynamicproxy.HelloIF;

public class HelloClient {

public static void main(String[] args) {try {

String UrlString = args[0] + "?WSDL";String nameSpaceUri = "urn:Foo";String serviceName = "MyHelloService";String portName = "HelloIFPort";

System.out.println("UrlString = " + UrlString);URL helloWsdlUrl = new URL(UrlString)

This is an example of looking up, creating a dynamic proxy.

06/15/2005


98/130

98

98

Example: Dynamic Proxy Client (2)ServiceFactory serviceFactory =

ServiceFactory.newInstance();

Service helloService =serviceFactory.createService(helloWsdlUrl,new QName(nameSpaceUri, serviceName));

dynamicproxy.HelloIF myProxy =

(dynamicproxy.HelloIF)helloService.getPort(new QName(nameSpaceUri, portName),dynamicproxy.HelloIF.class);

System.out.println(myProxy.sayHello("Buzz"));


}}

}

This is an example of looking up, creating a dynamic proxy.

06/15/2005


99/130

99

99

Steps of Building Dynamic Proxy

Client? Ant build targets

generate-interface? runs wscompile with the -import option

? reads the MyHelloService.wsdl file and generates theservice endpoint interface class (HelloIF.class)

compile-client? compiles the src/HelloClient.java file

package-dynamic? creates the dist/client.jar file, which contains HelloIF.class

and HelloClient.class

To build and package the client, go to the/jwstutorial13/examples/jaxrpc/dynamicproxy/ directory and typethe following:

ant build

The preceding command runs these tasks:

* generate-interface* compile-client* package-dynamic

The generate-interface task runs wscompile with the -import option. Thewscompile command reads the MyHelloService.wsdl file and generates theservice endpoint interface class (HelloIF.class). Although this wscompileinvocation also creates stubs, the dynamic proxy client does not use these stubs,which are required only by static stub clients.

The compile-client task compiles the src/HelloClient.java file.

The package-dynamic task creates the dist/client.jar file, which containsHelloIF.class and HelloClient.class.

06/15/2005


100/130

100

100

Client Programming Model

DII

06/15/2005


101/130

101

101

DII Invocation Model

? Gives complete control to client programmer

? A client can call a remote procedure even ifthe signature of the remote procedure or thename of the service are unknown until runtime

? Does not require wscompile to create runtimeclasses

? Most complex programming among the three

This example resides in the /jwstutorial13/examples/jaxrpc/dii/

directory.

With the dynamic invocation interface (DII), a client can call a remoteprocedure even if the signature of the remote procedure or the name of the

service are unknown until runtime. In contrast to a static stub or dynamic proxyclient, a DII client does not require runtime classes generated by wscompile.

However, as you'll see in the following section, the source code for a DII clientis more complicated than the code of the other two types of clients.

06/15/2005


102/130

102

102

DII Invocation Model

? Enables broker model Client finds (through some search criteria) and

invokes a service during runtime through a broker

Used when service definition interface is notknown until runtime

You set operation and parameters during runtime

06/15/2005


103/130

103

103

Steps of Coding DII Client1.Create a Service object

2.From the Service object, create a Call object

3.Set the service endpoint address on the Callobject

4.Set properties on the Call object

5.Specify the method's return type, name, andparameter

6.Invoke the remote method on the Call object










06/15/2005


104/130

104

104

Step1: Create a Service object? Invoke createService() method of a

ServiceFactory object

Service service =

factory.createService(new QName(qnameService));

? qnameService parameter is the name of theservice specified in WSDL

Service service =factory.createService(new QName(qnameService));

To get a Service object, the program invokes the createService method of aServiceFactory object. The parameter of the createService method is a QName

object that represents the name of the service, MyHelloService. The WSDL filespecifies this name as follows:

06/15/2005


105/130

105

105

Step2: From the Service object,

create a Call object? A Call object supports the dynamic

invocation of the remote procedures of aserviceQName port = new QName(qnamePort);

Call call = service.createCall(port);

? The parameter of createCall is a QNameobject that represents the service endpoint

interface, which is specified in WSDL

QName port = new QName(qnamePort);Call call = service.createCall(port);

A Call object supports the dynamic invocation of the remote procedures of aservice. To get a Call object, the program invokes the Service object's createCall

method. The parameter of createCall is a QName object that represents theservice endpoint interface, MyHelloServiceRPC. In the WSDL file, the name ofthis interface is designated by the portType element:

06/15/2005


106/130

106

106

Step3: Set the service endpoint

address on the Call object? In the WSDL file, this address is specified by

the element

call.setTargetEndpointAddress(endpoint);

call.setTargetEndpointAddress(endpoint);

In the WSDL file, this address is specified by the element.

06/15/2005


107/130

107

107

Step4: Specify the method's return

type, name, and parameter? Properties to set

SOAPACTION_USE_PROPERTY

SOAPACTION_URI_PROPERTY

ENCODING_STYLE_PROPERTY

A

06/15/2005


108/130

108

108

Step5: Specify the method's return

type, name, and parameter? Return type, method name, parameter

QName QNAME_TYPE_STRING = new QName(NS_XSD, "string");call.setReturnType(QNAME_TYPE_STRING);

call.setOperationName(new QName(BODY_NAMESPACE_VALUE,"sayHello"));

call.addParameter("String_1", QNAME_TYPE_STRING,ParameterMode.IN);

To specify the return type, the program invokes the setReturnType method on theCall object. The parameter of setReturnType is a QName object that represents anXML string type.

The program designates the method name by invoking the setOperationName

method with a QName object that represents sayHello.

To indicate the method parameter, the program invokes the addParameter methodon the Call object. The addParameter method has three arguments: a String forthe parameter name (String_1), a QName object for the XML type, and aParameterMode object to indicate the passing mode of the parameter (IN).

06/15/2005


109/130

109

109

Step6: Invoke the remote method on

the Call object? Assign the parameter value (Murphy) to a

String array (params) and then executes theinvoke method with the String array as anargument

String[] params = { "Murphy" };

String result = (String)call.invoke(params);

A

06/15/2005


110/130


111/130

111

111

Example: DII Client (2)public static void main(String[] args) {

System.out.println("Endpoint address = " + args[0]);

try {ServiceFactory factory = ServiceFactory.newInstance();Service service =

factory.createService(new QName(qnameService));

QName port = new QName(qnamePort);

Call call = service.createCall(port);call.setTargetEndpointAddress(args[0]);

call.setProperty(Call.SOAPACTION_USE_PROPERTY,

new Boolean(true));call.setProperty(Call.SOAPACTION_URI_PROPERTY

"");call.setProperty(ENCODING_STYLE_PROPERTY,

URI_ENCODING);QName QNAME_TYPE_STRING =

new QName(NS_XSD, "string");call.setReturnT e QNAME TYPE STRING

06/15/2005


112/130

112

112

Example: DII Client (3)call.setOperationName(

new QName(BODY_NAMESPACE_VALUE,"sayHello"));call.addParameter("String_1", QNAME_TYPE_STRING,

ParameterMode.IN);String[] params = { "Murph!" };

String result = (String)call.invoke(params);System.out.println(result);


}}

}

06/15/2005


113/130

113

113

Service EndpointModel

06/15/2005


114/130

114

114

Service Endpoint Model

?

Service endpoint can be either Servlet based endpoint or

Stateless session bean

? JAX-RPC 1.0 specifies Servlet basedendpoint model

? EJBTM 2.1 specifies Stateless sessionbean based endpoint model

06/15/2005


115/130

115

115

Web Services for the J2EE 1.4 Platform

? Client View

JAX-RPC

? Server View

Servlet based endpoint

JAX-RPC

Runtime is provided by Web container

Stateless Session Bean based endpoint EJB 2.1

Runtime is provided by EJB container

So in summary, over J2EE platform, the client view is defined in JAX-RPC specification.And the server view can be in two different forms, one in servlet-based, and the other isstateless session bean based. The servlet based endpoint model is defined in JAX-RPC

specification while stateless session bean based endpoint model is defined in EJB 2.1specification. Servlet endpoint runtime is provided by web container while stateless session

bean runtime is provided by EJB container.

06/15/2005


116/130

116

116

Service Developer

? Generates service definition interface? Implements service definition interface

(service endpoint class)? Service endpoint class

May implement ServiceLifecycleinterface

Can access servlet context viajavax.servlet.ServletContext interface

?

Creates *.warpackage

JAX-RPC specification talks about the roles of service developer and

deployer as part of service endpoint model.Service developer generates service definition interface from WSDL

document or it can creates service definition interface directly

Then he implements the service definition interface and let's call it

service endpoint class.The service end point class may optionally implement ServiceLifeCycle

interface in which init() and destroy() methods are defined. By calling

init() and destroy() methods, the container can creates a pool of service

endpoint class instances.The init() method also can pass ServletContext object as a parameter so

service endpoint class have an access to ServletContext object.

And the service developer then creates deployment descriptor andjaxrpc.war file

06/15/2005


117/130

117

117

Service Deployer

? Handles

Protocol binding

Port assignment

? Multiple protocol binds for a single serviceendpoint definition

? Creates web.xml? Creates complete WSDL document which

contains concrete binding information

This WSDL document can be published

? Creates and deploy assembled *.war file

06/15/2005


118/130

118

118

Protocol andTransport Binding

06/15/2005


119/130

119

119

Protocol Bindings and Transport

? JAX-RPC APIs are independent of any

specific protocol binding or transport? JAX-RPC 1.1 enables support for multiple

XML based protocol bindings:

SOAP 1.1 and SOAP 1.2

Binary protocol bindings based on XML infoset

? Multiple transports can be plugged under theXML based protocol

? JAX-RPC requires SOAP 1.1 and HTTP 1.1required for interoperability

06/15/2005


120/130

120

120

JAX-RPC RuntimeSystem

06/15/2005


121/130


122/130

122

122

ProgrammingModel

06/15/2005


123/130

123

123

JAX-RPC Programming Model

? Service definition interfaces must followRMI conventions

? JAX-RPC requirements No Remote references allowed

All objects are passed by copy

public interface MeetingManagerextends java.rmi.Remote {

public MeetingInfo scheduleMeeting(String requestor,String[] participants)

throws java.rmi.RemoteException,CannotScheduleException;

}

06/15/2005


124/130

124

124

Servlet-Based Endpoint Model

? Service implementation class is anordinary Java class

? Invocation done inside the servletcontainer

? Optional ServiceLifecycleinterface forinitialization and destruction callbacks

?

Access all resources in the webapplication

06/15/2005


125/130

125

125

Sample Service Implementationpublic class MeetingManagerImpl

implements MeetingManager, ServiceLifecycle {

public MeetingManagerImpl() { ... }

public void init(Object ctx) {ServletContext context = (ServletContext) ctx;// obtain a connection to a database// ...

}

public void destroy() { ... }

public MeetingInfo scheduleMeeting(String requestor,

String[] participants)throws java.rmi.RemoteException,

CannotScheduleException { ... }}

06/15/2005


126/130


127/130

127

127

Package Relationship

javax.xml.rpc javax.xml.messaging

javax.xml.soap

06/15/2005


128/130

128

128

Resources

06/15/2005


129/130

129

129

Resources

? JAX-RPC Home

http://java.sun.com/xml/jax-rpc/index.html

? Java Web Services Developer Pack Download

http://java.sun.com/webservices/downloads/webservicespack.html

? Java Web Services Developer Pack Tutorial

http://java.sun.com/webservices/downloads/webservicetutorial.html

?

J2EE 1.4 SDK http://java.sun.com/j2ee/1.4/download-dr.html

06/15/2005


130/130

130

Passion!

06/15/2005

Documents

JAX RPC Speaker Noted