备忘录：JAX-RPC 1.1

　

Q. What are the modes of interaction between clients and JAX-RPC services?

A. There are three different modes:

1. Synchronous Request-Response: The client invokes a remote procedure and blocks until it receives a return or an exception.

2. One-Way RPC: The client invokes a remote procedure but it does not block or wait until it receives a return. The runtime system for the JAX-RPC client may throw an exception.

3. Non-Blocking RPC Invocation: The client invokes a remote procedure and continues processing in the same thread without waiting for a return. Later, the client processes the remote method return by blocking for the receive or polling for the return.

4. The JAX-RPC specification does not specify any standard APIs for the design of asynchronous stubs. This feature will be addressed in the future version of the JAX-RPC specification. This will lead to the support for both one-way and non-blocking RPC interaction modes.

Q. Can a remote method call or response carry service context information?

A. Yes. For example, it may carry a unique transaction identifier or digital signature.

　

0, JAX-RPC vs. WSDL

With the JAX-RPC API, developers can implement clients and services described by WSDL.

The JAX-RPC specification uses the WSDL 1.1 specification for the description of JAX-RPC services.

A JAX-RPC implementation is not required to support a round-trip mapping between the Java and WSDL based representations of a JAX-RPC service.

1, JAX-RPC vs. SOAP

The Java API for XML-Based RPC (JAX-RPC) enables Java technology developers to build Web applications and Web services incorporating XML-based RPC functionality according to the SOAP (Simple Object Access Protocol) 1.1 specification. (Although one of its goal is: Define base level protocol bindings and to not limit other protocol bindings that can be supported with the JAX-RPC programming model.)

A JAX-RPC runtime system implementation is required to support the SOAP 1.1 with attachments protocol.

• Note that the required support of SOAP 1.1 with attachments protocol must not preclude or limit use of other protocol bindings and transport in a JAX-RPC runtime system implementation.

• Note that the JAX-RPC specification would consider support for the SOAP 1.2 protocol when the SOAP 1.2 W3C specification reaches the final recommendation stage. This would be addressed in the future versions of the JAX-RPC specification.

2, JAX-RPC vs. HTTP

A JAX-RPC runtime system implementation is required to support HTTP 1.1 as the transport for SOAP messages.

Note that the required support of HTTP 1.1 must not mean that the HTTP transport is the only transport that can be supported by a JAX-RPC runtime system implementation.

3, Security-Neutralism

JAX-RPC specification does not preclude the use of SOAP binding with a transport that supports security mechanisms. However, the specification of SOAP bindings to transports that support security is outside the scope of the JAX-RPC specification. A JAX-RPC runtime system implementation is not required to support HTTP/S as the underlying secure transport. Refer to the chapter 14 for the interoperability requirements.

4, Out of scope:

Proposed out of scope features for the 1.1 version of the JAX-RPC specification include:
• Design of portable stubs and skeletons
• Standard representation of transaction and security context
• Service registration and discovery
• Objects by reference

5. Top-down vs. Bottom-up

In this example, stock quote service endpoint definition starts with a Java interface as shown in the above code example. This interface is called a service endpoint interface. Note that the service developer could have started from the stock quote service description in a WSDL document and mapped it to the corresponding Java service endpoint interface.

6. Dynamic vs. Static

Note that a service client may use dynamic invocation interface (DII) or a dynamic proxy mechanism instead of a generated stub class to invoke a remote method on a service endpoint.

7. Encoded vs. Literal

The JAX-RPC specification requires support for both encoded and literal representations of a SOAP message representing an RPC call or response.

The use of SOAP 1.1 encoding must not preclude use of any other encoding in a JAX-RPC runtime system implementation.

A message part may be either encoded using some encoding rules or may represent a concrete schema definition; the latter is termed literal representation. The JAX-RPC specification requires support for the literal representation of an RPC request or response in the SOAP body.

8. Server Side Runtime System

The JAX-RPC specification identifies the following as the incremental levels of server side implementation of a JAX-RPC runtime system:

• J2SE based JAX-RPC runtime system

• Servlet container based JAX-RPC runtime system

• Standard J2EE container (includes EJB and Web containers) based JAX-RPC runtime system: The JAX-RPC specification identifies a servlet container as a typical implementation of JAX-RPC server side runtime system. Note that the use of the servlet container for the implementation of a JAX-RPC server side runtime system must not preclude any J2SE level implementation of a JAX-RPC runtime system.

9. Client Side Runtime System

The JAX-RPC specification requires a client side JAX-RPC compatible implementation to be based on either J2SE (1.3 version or higher) platform or J2EE (1.3 version or higher) containers. The JAX-RPC specification also supports J2ME (Java 2 platform, Micro Edition) MIDP client as a form of JAX-RPC service client.

10. Endpoint Programming Model

• The JAX-RPC specification specifies the standard programming model for a service endpoint developed and deployed on a servlet container based JAX-RPC runtime system.

• The JAX-RPC specification does not specify a normative J2SE based service endpointmodel.

• The JAX-RPC specification does not specify the service endpoint model for a JAX-RPC service developed using the standard EJB programming model and deployed on an EJB container.

11. XML API

JAX-RPC 1.1 implementations are required to support the SAAJ 1.2 APIs: The JAX-RPC specification specifies APIs for the development of SOAP message handlers for SOAP message processing. These SOAP message handlers are based on the javax.xml.soap package. The JAX-RPC specification also defines SOAP protocol binding specific APIs in the javax.xml.rpc.soap package. This package uses the Java APIs defined in the javax.xml.soap package. JAX-RPC also uses the javax.xml.soap APIs to represent mapping of literal fragments carried in a SOAP message.

12. Service Context vs. SOAP Header

If SOAP is the underlying protocol, service context information is carried in the SOAP header of a SOAP message. Note that neither SOAP 1.1 nor SOAP 1.2 specification defines any standard SOAP header representation for the transaction or security related context.

The SOAP specification does not define any standard formats for the SOAP headers.

The WSDL 1.1 specification includes a soap:header element in the SOAP binding. A soap:header element defines an header entry transmitted in the SOAP Header. Multiple soap:header elements can be defined per operation for both input and output. Note that the WSDL 1.1 specification does not require that SOAP headers be listed exhaustively in the SOAP binding.

An exported WSDL document (for a JAX-RPC service endpoint definition) includes soap:header elements for both input and output of each operation. These soap:header elements may be defined specific to either a service endpoint definition or a JAX-RPC runtime system or a server-side J2EE container.

On the service client side, a WSDL to Java mapping tool maps soap:header elements to either implicit or explicit service context. A client side JAX-RPC runtime system or generated stub class may add service context for a remote method call. This service context information is in addition to that specified in the WSDL defined soap:header elements.

13. Handlers

JAX-RPC specification specifies APIs for only the SOAP message handlers. Future versions of the JAX-RPC specification would add support for other types of handlers.

A few typical examples of handlers are:

• Encryption and decryption handler

• Logging and auditing handler

• Caching handler

A HandlerChain instance is required to share the same MessageContext across Handler instances that are invoked during a single request and response or fault processing on a specific service endpoint.Handler instances in a handler chain should not rely on the thread local state to sharestate between handler instances. Handler instances in a HandlerChain should use the MessageContext to share any SOAP message processing related state.

14. WSDL Service

A wsdl:service groups a set of service endpoints (or ports), with each service endpoint defined with specific port type, binding and endpoint address.

The JAX-RPC specification defines the mapping of a wsdl:service element to a service class. A service class acts as a factory of the following:

• Dynamic proxy for a service endpoint.

• Instance of the type javax.xml.rpc.Call for the dynamic invocation of a remote operation on a service endpoint.

• Instance of a generated stub class

A service class implements one of the following interfaces:

• The base javax.xml.rpc.Service interface directly, or,

• A generated service interface. This service interface is generated during the WSDLto-Java mapping and extends the base javax.xml.rpc.Service interface

A JAX-RPC runtime system is required to provide the implementation class for the base javax.xml.rpc.Service interface. This implementation class is required to support the creation of both dynamic proxies and Call objects. The methods getPort(...) returns a dynamic proxy or instance of a generated stub class for the specified service endpoint.

The getCalls method returns an array of preconfigured Call objects for invoking operations on the specified port. There is one Call object per operation that can be invoked on the specified port. A pre-configured Call object does not need to be
configured using the setter methods on the Call interface. Each invocation of the getCalls method is required to return a new array of preconfigured Call objects.

15. XML, WSDL 2 Java Mapping

1. Any name collisions in the mapped Java code are resolved by prefixing an underscore to the mapped name.

2. The JAX-RPC specification does not define the standard Java mapping for the xsd:anyType. A JAX-RPC implementation is not required to support the xsd:anyType.

3. The xsd:anyURI type must be mapped to the java.net.URI class in applications that are intended to run on J2SE 1.4 or later. For compatibility with pre-1.4 environments, JAX-RPC implementations are allowed to map this type to java.lang.String.

4. There are a number of cases in which a built-in simple XML data type must be mapped to the corresponding Java wrapper class for the Java primitive type:

• an element declaration with the nillable attribute set to true;

• an element declaration with the minOccurs attribute set to 0 (zero) and the maxOccurs attribute set to 1 (one) or absent;

• an attribute declaration with the use attribute set to optional or absent and carrying neither the default nor the fixed attribute;

5. The SOAP 1.1 specification indicates that all SOAP encoded elements are nillable. So in the SOAP encoded case, a SOAP encoded simple XML type is mapped to the corresponding Java wrapper class for the Java primitive type. An example is mapping of the soapenc:int to the java.lang.Integer.

6. A WSDL to Java mapping tool is required to support the configuration of the application specific package name during the  mapping. JAX-RPC requires that a namespace definition in a WSDL document must be mapped to a unique Java package name.

7. A WSDL port type is mapped to a Java interface (termed a Service Endpoint Interface) that extends the java.rmi.Remote interface. Each method of the mapped Java interface is required to declare java.rmi.RemoteException in its throws clause. A method may also throw service specific exceptions based on the mapping of a WSDL faults

8. JAX-RPC does not support passing of a java.rmi.Remote instance in a remote method invocation. The JAX-RPC specification specifies the following rules for the in, out and inout parameter passing modes and return value:

• An in parameter is passed as copy. The value of the in parameter is copied before a remote method invocation.

• The return value is created as a copy and returned to the caller from a remote method invocation. The caller becomes the owner of the returned object after completion of the remote method invocation.

• The out and inout parameters are passed by copy. Parameter passing mode for out and inout parameters uses Holder classes.

9. A wsdl:fault is mapped to either a java.rmi.RemoteException (or its subclass),service specific Java exception or a javax.xml.rpc.soap.SOAPFaultException.

10. The JAX-RPC specification does not define a standard Java representation of the wsdl:binding element.

The JAX-RPC specification does not require support for the passing or return of a remote reference across a remote method invocation. The reason is that SOAP specifies object-by-reference as out of scope in both the 1.1 and 1.2 versions.

16. Java 2 XML, WSDL Mapping

1. The JAX-RPC specification requires support for Java array of type java.lang.Object. Multidimensional Java arrays are also supported. Examples are int[] and String[][].

2. Other standard Java classes (for example: classes in the Java Collection Framework) are mapped using pluggable serializers and deserializers.

3. Service endpoint interface must not include constant (as public final static) declarations. WSDL 1.1 specification does not define any standard representation for constants in a wsdl:portType definition.

4. There is no standard mapping of indexed properties as reported by the JavaBeans introspection.

5. There is no standard mapping for the case when a JavaBean property has the same name as a public field. A Java to XML mapping implementation is required to flag this case as an error.

6. A JAX-RPC value type that conforms to the above rules is usable across both JAX-RPC (with different protocol bindings) and RMI-IIOP (that uses the standard Java serialization semantics for its value types) with the same Java serialization semantics. A JAX-RPC value type that implements the Serializable interface but does not conform to all above rules, may not have the Java serialization semantics.

7. Note that the Java to WSDL mapping specifies mapping of the Java definitions to the abstract WSDL definitions (namely: wsdl:types, wsdl:message, wsdl:operation and wsdl:portType). The following mapping specification does not specify how the SOAP binding (or binding for any other protocol) is defined in a WSDL document.

8. The JAX-RPC specification requires the namespace definitions in the WSDL document to be mapped in an application specific manner. A Java to WSDL mapping tool is required to support the configuration of the namespace definitions in the mapped WSDL document.

9. Overloaded Java methods are mapped to multiple wsdl:operation elements. These mapped wsdl:operation elements are named the same (as the name of the overloaded Java methods) or with unique names depending on the mechanism that is used by the server-side JAX-RPC runtime system to dispatch methods to the target service endpoint. For example, a JAX-RPC runtime system may use unique operation names, SOAPAction or an implementation specific mechanism to dispatch methods to the target service endpoint. Note that the JAX-RPC specification does not require use of the SOAPAction.

10. For Holder classes used as method parameters, a Java to WSDL mapping tool is required to provide a facility for specifying the related mapping metadata. This metadata identifies whether a Holder parameter in the method signature is mapped to either the OUT or INOUT parameter mode.

11. A remote exception (java.rmi.RemoteException or its subclasses) is mapped to a standard SOAP fault.

17. SOAP Binding

0. A JAX-RPC implementation is required to support the above operation modes for the mapping of a WSDL based service description to the corresponding Java representation.

1. The JAX-RPC specification requires that the above requirements based on the operation style should be hidden from the JAX-RPC programming model. A JAX-RPC implementation should take the responsibility for the appropriate representation of a SOAP message based on the operation style.

2. In the encoded use, each message part in the SOAP body references an abstract type using the type attribute. These types are serialized according to the encodings identified in the encodingStyle attribute of the soap:body element. An example of such encoding is the SOAP 1.1 encoding

3. If the use is literal, each message part in the SOAP Body element references a concrete schema definition using either the element or type attribute. If the element attribute is used, the element referenced by the message part appears under the Body element (with or without wrapper depending on the operation style). If the type attribute is used, the type referenced by the part becomes the schema type of the enclosing element (Body element for the document style or part accessor element for the rpc style).

4. The JAX-RPC specification requires support for the element attribute in a message part with literal representation and referenced by a document style operation. It also requires support for the type attribute in a message part with literal representation and referenced by an rpc style operation

5. If there is no standard Java mapping for an XML schema type, a message part with literal representation is considered and mapped as a document fragment. The XML to Java mapping uses the interface javax.xml.soap.SOAPElement to represent a literal message part in the Java mapping of a wsdl:operation element. For example, a parameter or a return type (for a remote operation) represented as a literal message part is mapped to a SOAPElement in the Java method signature.

6. In order to qualify as using the “wrapper” style, an operation must fulfill the following conditions:

• its input and output messages (if present) must contain exactly one part;

• such a part must refer to an element named after the operation;

• such an element (a wrapper) must be of a complex type defined using the xsd:sequence compositor and containing only elements declarations. In this case, implementations must be able to discard the wrapper elements and treat their children as the actual parameters of the operation.

18. Stub

The JAX-RPC specification does not require support for protocol and transport neutral stub classes that are dynamically configurable for different protocols and transports. A stub class should be bound to a specific protocol and transport.

19. Stub Properties

Note that the standard JAX-RPC properties are required to be prefixed by the javax.xml.rpc package name. Any vendor implementation specific properties must be defined prefixed by a vendor specific package name.

Name of Property

Type of Property

Description and Required/Optional support

javax.xml.rpc. security.auth. username

java.lang. String

User name for authentication Required to support HTTP Basic Authentication. Refer to the section 13.1.1 for more details.

javax.xml.rpc. security.auth. password

java.lang. String

Password for authentication Required to support HTTP Basic Authentication. Refer to the section 13.1.1 for more details.

javax.xml.rpc. service.endpoint. address

java.lang. String

Target service endpoint address. The URI scheme for the endpoint address specification must correspond to the protocol/transport binding for this stub class. Required.

javax.xml.rpc. session.maintain

java.lang. Boolean

This boolean property is used by a service client to indicate whether or not it wants to participate in a session with a service endpoint. If this property is set to true, the service client indicates that it wants the session to be maintained. If set to false, the session is not maintained. The default value for this property is false. Required to support session management.

20. Dynamic Proxy

The JAX-RPC specification requires support for the dynamic proxy for invoking a service endpoint. A dynamic proxy class supports a service endpoint interface dynamically at runtime without requiring any code generation of a stub class that implements a specific service endpoint interface.  A dynamic proxy is required to also support the javax.xml.rpc.Stub interface. This provides support for the configuration of a dynamic proxy.

21. Call Properties

The javax.xml.rpc.Call interface provides support for the dynamic invocation of an operation on the target service endpoint. The javax.xml.rpc.Service interface acts as a factory for the creation of Call instances.

Name of Property

Type of Property

Description

javax.xml.rpc. security.auth. username

java.lang. String

User name for Authentication Required to support HTTP Basic Authentication. Refer to the section 13.1.1 for more details.

javax.xml.rpc. security.auth. password

java.lang. String

Password for Authentication. Required to support HTTP Basic Authentication. Refer to the section 13.1.1 for more details.

javax.xml.rpc. session.maintain

java.lang. Boolean

This boolean property is used by a service client to indicate whether or not it wants to participate in a session with a service endpoint. If this property is set to true, the service client indicates that it wants the session to be maintained. If set to false, the session is not maintained. The default value for this property is false. Refer to the section 13.2, 揝ession Management?for more details. Required to support session management.

javax.xml.rpc. soap.operation.style

java.lang. String

?/FONT>rpc?if the operation style is rpc; ?/FONT>document?if the operation style is document. Note that a Call implementation may choose to not allow setting of this property. In this case, the setProperty method throws JAXRPCException. Optional

javax.xml.rpc. soap.http.soapaction .use

java.lang. Boolean

This boolean property indicates whether or not SOAPAction is to be used. The default value of this property is false indicating that the SOAPAction is not used.

Optional

javax.xml.rpc. soap.http.soapaction .uri

java.lang. String

Indicates the SOAPAction URI if the javax.xml.rpc.soap.http.soapac tion.use property is set to true. Optional

javax.xml.rpc. encodingstyle. namespace.uri

java.lang. String

Encoding style specified as a namespace URI. The default value is the SOAP 1.1 encoding http:// schemas.xmlsoap.org/soap/ encoding/  Optional

22. Invoke

A J2SE based service client uses one of the following approaches for the invocation of a JAX-RPC service endpoint:

• The service client uses the generated stub classes. A WSDL to Java mapping tool imports a WSDL based service description and maps it to the corresponding client side Java representation. The generated client side artifacts may include serializers, deserializers, holders and utility classes.

• The service client uses the javax.xml.rpc.Service interface to create a dynamic proxy for the target service endpoint.

• The service client uses the javax.xml.rpc.Service interface to create a Callobject. Next, the service client uses the javax.xml.rpc.Call interface to dynamically invoke an operation on the target service endpoint.

Instead, J2EE-based service clients should use JNDI to lookup an instance of a Service class as specified in JSR-109.

23. Servlet

A service endpoint class is associated with a servlet. The associated servlet typically takes the responsibility of handling transport specific processing of an RPC request and for initiating dispatch to the target service endpoint instance.

24. handleRequest Logic

The handleRequest method performs one of the following steps after performing handler specific processing of the request SOAP message:

• Return true to indicate continued processing of the request handler chain.

• Return false to indicate blocking of the request handler chain. In this case, further processing of the request handler chain is blocked and the target service endpoint is not dispatched. The JAX-RPC runtime system takes the responsibility of invoking the response handler chain next with the appropriate SOAPMessageContext. The Handler implementation class has the responsibility of setting the response SOAP message in the handleRequest method and perform additional processing in the handleResponse method. In the default processing model, the response handler chain starts processing from the same Handler instance (that returned false) and goes backward in the execution sequence.

• Throw the javax.xml.rpc.soap.SOAPFaultException to indicate a SOAP fault. The Handler implementation class has the responsibility of setting the SOAP fault in the SOAP message in either handleRequest and/or handleFault method. If SOAPFaultException is thrown by a server-side request handler’s handleRequest method, the HandlerChain terminates the further processing of the request handlers in this handler chain and invokes the handleFault method on the HandlerChain with the SOAP message context. Next, the HandlerChain invokes the handleFault method on handlers registered in the handler chain, beginning with the Handler instance that threw the exception and going backward in execution. The client-side request handler’s handleRequest method should not throw the SOAPFault- Exception.

• Throw the JAXRPCException or any other RuntimeException for any handler specific runtime error. If JAXRPCException is thrown by a handleRequest method, the HandlerChain terminates the further processing of this handler chain. On the server side, the HandlerChain generates a SOAP fault that indicates that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to a runtime error during the processing of the message. On the client side, the JAXRPCException or runtime exception is propagated to the client code as a RemoteException or its subtype.

25. handleResponse Logic

The handleResponse method performs the processing of the SOAP response message. It does one of the following steps after performing its handler specific processing of the SOAP message:

• Return true to indicate continued processing of the response handler chain.

• Return false to indicate blocking of the response handler chain. In this case, no other response handlers in the handler chain are invoked. On the service endpoint side, this may be useful if response handler chooses to issue a response directly without requiring other response handlers to be invoked.

• Throw the JAXRPCException or any other RuntimeException for any handler specific runtime error.

26. Handle Exception

Please note that when a JAXRPCException or RuntimeException raised on the server is converted to a SOAP fault for the purpose of being transmitted to the client, there are no guarantees that any of the information it contains will be preserved. A RuntimeException (other than SOAPFaultException) thrown from any method of the Handler results in the destroy method being invoked and transition to the “Does Not Exist” state.

27. Security

• The JAX-RPC specification requires support for HTTP Basic Authentication for protocol bindings over the HTTP transport.

• The JAX-RPC specification does not require support for the certificate based mutual authentication using HTTP/S (HTTP over SSL) mechanism.

• The JAX-RPC specification does not require support for the SOAP Security Extensions for digital signature

The HTTP Basic Authentication uses user name and password for authenticating a service client. The javax.xml.rpc.Stub and javax.xml.rpc.Call interfaces are required to support javax.xml.rpc.security.auth.username and javax.xml.rpc.security.auth.password properties for the HTTP Basic Authentication. For convenience, the properties above can be referenced using resp. the USERNAME_PROPERTY and PASSWORD_PROPERTY constants defined by the Stub and Call interfaces.

28. Session

A service client uses the javax.xml.rpc.session.maintain property (set using the Stub or Call interfaces) to indicate whether or not it wants to participate in a session with a service endpoint. JAX-RPC specification does not require session management as part of the interoperability requirements

29. Interoperability

• The JAX-RPC specification does not specify interoperability requirements for any protocol other than the SOAP 1.1 with attachments.

• A JAX-RPC runtime system implementation is required to support the SOAP 1.1 encoding. Interoperability requirements for any other encodings are outside the scope of the JAX-RPC specification.

• The interoperability requirements for any other transport than HTTP 1.1 are outside the scope of the JAX-RPC specification.

• Import and export WSDL 1.1.

• JAX-RPC specification does not specify requirements for the security interoperability for the JAX-RPC implementations.

• A JAX-RPC implementation is not required to implement support for the transaction context propagation.

• WS-I Basic Profile 1.0

30. Serialization Framework

The SOAP 1.1 encoding allows arbitrary graphs of Java objects to be serialized as XML. The most interesting case is when an object graph contains multiple references to the same object. In this case, the HREF mechanism of the SOAP encoding may be used to preserve object identity, thus making it possible to restore an object graph exactly as it was before serialization. By far, the main complicating factor in serializing and deserializing object graphs using SOAP encoding is ensuring that HREFs are handled correctly. As will become clear, most of the JAX-RPC RI serialization framework is motivated by the need to correctly process HREFs.

31. Multiple-reference vs. Single-reference

Multiple-reference instances have an id attribute, single-reference instances do not.