Difference between revisions of "Common-gcore-stubs"
(→Stubbed Calls) |
(→Collections) |
||
(12 intermediate revisions by 2 users not shown) | |||
Line 22: | Line 22: | ||
The library gives us back dynamically generated implementations of the SEI. The implementations are first synthesised by the underlying JAX-WS runtime and then appropriately configured by the library to issue gCube calls to the target endpoint (i.e. propagate the call scope, target service coordinates, client identity, etc.). | The library gives us back dynamically generated implementations of the SEI. The implementations are first synthesised by the underlying JAX-WS runtime and then appropriately configured by the library to issue gCube calls to the target endpoint (i.e. propagate the call scope, target service coordinates, client identity, etc.). | ||
− | SEI implementations can then serve as local stubs for service endpoints/instances. Typically, we use them to implement higher-level [Integration_and_Interoperability_Facilities_Framework:_Client_Libraries|client libraries]]. | + | SEI implementations can then serve as local stubs for service endpoints/instances. Typically, we use them to implement higher-level [[Integration_and_Interoperability_Facilities_Framework:_Client_Libraries|client libraries]]. |
The SEI and the other required information may be distributed as a stand-alone component, like for JAX-RPC stubs. Alternatively, they may be integral part of our client libraries. The fact that these 'stubs' have a minimal footprint, do not need to be generated through tooling, and are client-only artefacts makes the embedding option natural and in fact appealing. | The SEI and the other required information may be distributed as a stand-alone component, like for JAX-RPC stubs. Alternatively, they may be integral part of our client libraries. The fact that these 'stubs' have a minimal footprint, do not need to be generated through tooling, and are client-only artefacts makes the embedding option natural and in fact appealing. | ||
Line 134: | Line 134: | ||
</source> | </source> | ||
− | We name the SEI so as to reflect that it acts as a local API for remote service endpoints. We annotate it with <code>@WebService</code>, providing the coordinates of the service porttype that defines the remote operations. For this, we use the constants of the <code>AcmeConstants</code> class defined [[# | + | We name the SEI so as to reflect that it acts as a local API for remote service endpoints. We annotate it with <code>@WebService</code>, providing the coordinates of the service porttype that defines the remote operations. For this, we use the constants of the <code>AcmeConstants</code> class defined [[#Acme|above]], which we statically import for improved legibility of the code. We then declare the method <code>foo</code> and annotate it with <code>@SOAPBinding</code> to indicate that its input and output should be put/found in request/response elements directly under the SOAP body. |
We discuss how to write SEIs in more detail [[#Writing SEIs|later on]]. For now, let us concentrate on how we use it with <code>common-gcore-stubs</code>. | We discuss how to write SEIs in more detail [[#Writing SEIs|later on]]. For now, let us concentrate on how we use it with <code>common-gcore-stubs</code>. | ||
Line 140: | Line 140: | ||
===Service Descriptor === | ===Service Descriptor === | ||
− | We now provide <code>common-gcore-stubs</code> with a descriptor for Acme, i.e. the set of information which are required to call its endpoints. We provide the descriptor as an instance of the <code>GCoreService</code> class, which we build in a fluent style with the help of a <code>GCoreServiceBuilder</code>. A convenient place to do this is directly in the <code>AcmeConstants</code> class introduced [[# | + | We now provide <code>common-gcore-stubs</code> with a descriptor for Acme, i.e. the set of information which are required to call its endpoints. We provide the descriptor as an instance of the <code>GCoreService</code> class, which we build in a fluent style with the help of a <code>GCoreServiceBuilder</code>. A convenient place to do this is directly in the <code>AcmeConstants</code> class introduced [[#Acme|above]]. The following example illustrates: |
<source lang="java5"> | <source lang="java5"> | ||
Line 184: | Line 184: | ||
We build our stub using the static method <code>stubFor(GCoreService)</code> of the <code>StubFactory</code> class, which we statically import for convenience. | We build our stub using the static method <code>stubFor(GCoreService)</code> of the <code>StubFactory</code> class, which we statically import for convenience. | ||
− | We provide the factory with the <code>acme</code> descriptor defined [[# | + | We provide the factory with the <code>acme</code> descriptor defined [[#Service Descriptor|earlier]], which we also statically import. |
− | We also provide the address of the endpoint, here modelled as a <code>URI</code> | + | We also provide the address of the endpoint, here modelled as a <code>URI</code>. |
Finally, we use the stub returned by the <code>StubFactory</code> to call the endpoint through the SEI. | Finally, we use the stub returned by the <code>StubFactory</code> to call the endpoint through the SEI. | ||
Line 197: | Line 197: | ||
So far, we've implicitly assumed that Acme is stateless. However, many gCore services are stateful, their endpoints encapsulate data which they use and change upon processing client requests. Such endpoints can be modelled as collections of service instances, where all instances have the API of the service but are bound to different state. A service instance is typically created by an endpoint of a companion factory service which returns references to the instances. Such references are modelled on the wire as the ''endpoint references'' defined by [http://www.w3.org/TR/2005/CR-ws-addr-core-20050817/ WS-Addressing]. In Java, the class [http://docs.oracle.com/javase/6/docs/api/javax/xml/ws/EndpointReference.html EndpointReference] models such references. | So far, we've implicitly assumed that Acme is stateless. However, many gCore services are stateful, their endpoints encapsulate data which they use and change upon processing client requests. Such endpoints can be modelled as collections of service instances, where all instances have the API of the service but are bound to different state. A service instance is typically created by an endpoint of a companion factory service which returns references to the instances. Such references are modelled on the wire as the ''endpoint references'' defined by [http://www.w3.org/TR/2005/CR-ws-addr-core-20050817/ WS-Addressing]. In Java, the class [http://docs.oracle.com/javase/6/docs/api/javax/xml/ws/EndpointReference.html EndpointReference] models such references. | ||
− | We will see [[# | + | We will see [[#Factory_Operations|later]] how to model instance references in the SEIs of factory services. For now, let us assume to have one, either because we've manually built it during testing (cf. Java's own [http://docs.oracle.com/javase/6/docs/api/javax/xml/ws/wsaddressing/W3CEndpointReferenceBuilder.html W3CEndpointReferenceBuilder]), or because we've obtained it from a factory service, or else because we've dynamically discovered by querying the Information Services. We use the reference to call a service instance as follows: |
<source lang="java5"> | <source lang="java5"> | ||
Line 208: | Line 208: | ||
EndpointReference reference = ... | EndpointReference reference = ... | ||
− | AcmeStub stub = stubFor(acme). | + | AcmeStub stub = stubFor(acme).at(reference); |
String response = stub.foo("..."); | String response = stub.foo("..."); | ||
Line 214: | Line 214: | ||
</source> | </source> | ||
− | We thus interact with instances as we interact with endpoints, the only difference being that we pass the reference to the <code> | + | We thus interact with instances as we interact with endpoints, the only difference being that we pass the reference to the <code>at()</code> clause of the build expression. |
+ | |||
+ | '''Note''': we can use <code>EndpointReference</code>s even when we target endpoints of stateless services, instead of <code>URI</code>s. In other words, we can use the API of <code>common-gcore-stubs</code> uniformly, if the code so requires. | ||
== Writing SEIs == | == Writing SEIs == | ||
Line 224: | Line 226: | ||
:: ''how do we define and annotate the methods of the SEI so that the implementation generated by the JAX-WS runtime: a) sends requests which are understood by the service, and b) understands the responses produced by the service?'' | :: ''how do we define and annotate the methods of the SEI so that the implementation generated by the JAX-WS runtime: a) sends requests which are understood by the service, and b) understands the responses produced by the service?'' | ||
− | In what follows we assume that, like for the Acme service of our earlier [[# | + | In what follows we assume that, like for the Acme service of our earlier [[#Acme|example]]: |
* the WSDL follows a document/literal style for its SOAP/HTTP binding, with requests and responses defined by a single element in accordance to [http://www.ws-i.org/profiles/basicprofile-1.1-2004-08-24.html WS-I profile]; | * the WSDL follows a document/literal style for its SOAP/HTTP binding, with requests and responses defined by a single element in accordance to [http://www.ws-i.org/profiles/basicprofile-1.1-2004-08-24.html WS-I profile]; | ||
Line 245: | Line 247: | ||
=== Wrapped or Bare? === | === Wrapped or Bare? === | ||
− | One way in which operations differ within and across services is in the 'pattern' with which request and response elements are defined in the WSDL. As gCore services are document/literal services, the [http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl well-known] patterns are <code>BARE</code> and <code>WRAPPED</code>. Given that the WSDLs of gCore services have the characteristics listed [[# | + | One way in which operations differ within and across services is in the 'pattern' with which request and response elements are defined in the WSDL. As gCore services are document/literal services, the [http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl well-known] patterns are <code>BARE</code> and <code>WRAPPED</code>. Given that the WSDLs of gCore services have the characteristics listed [[#Acme|above]], the difference between the two patterns is no more than the following: |
* in the <code>BARE</code> pattern, request and responses have simple content. | * in the <code>BARE</code> pattern, request and responses have simple content. | ||
Line 252: | Line 254: | ||
Clearly, the difference emerges only when operations take or return simple types, otherwise the pattern is necessarily <code>WRAPPED</code>. | Clearly, the difference emerges only when operations take or return simple types, otherwise the pattern is necessarily <code>WRAPPED</code>. | ||
− | In the example [[# | + | In the example [[#Acme|above]], the service used the <code>BARE</code> pattern: |
<source lang="xml"> | <source lang="xml"> | ||
Line 465: | Line 467: | ||
</source> | </source> | ||
− | Modelling such operations in the SEI is just a special case of working with [[#Record | + | Modelling such operations in the SEI is just a special case of working with [[#Record Structure|record structure]]. If we [[#Wrapped or Bare?|can use]] the <code>WRAPPED</code> parameter style in the SEI, we can model <code>op</code> as simply as follows: |
<source lang="java5"> | <source lang="java5"> | ||
Line 498: | Line 500: | ||
</source> | </source> | ||
− | where we slightly customise the binding for a clearer API. | + | where we slightly customise the binding for a clearer API. |
=== Variable Structures === | === Variable Structures === | ||
Line 800: | Line 802: | ||
where the annotation <code>@XmlAnyElement</code> instructs the runtime to serialise the <code>any</code> as generic XML. | where the annotation <code>@XmlAnyElement</code> instructs the runtime to serialise the <code>any</code> as generic XML. | ||
+ | |||
+ | ==== The enumeration Case ==== | ||
+ | |||
+ | Let's now consider the case of an Enumeration which is a constrain on the values a type should assume. | ||
+ | |||
+ | For example: | ||
+ | |||
+ | <source lang="xml"> | ||
+ | |||
+ | <xsd:simpleType name="type1"> | ||
+ | <xsd:restriction base="xsd:string"> | ||
+ | <xsd:enumeration value="value1"/> | ||
+ | <xsd:enumeration value="value2"/> | ||
+ | <xsd:enumeration value="value3"/> | ||
+ | </xsd:restriction> | ||
+ | </xsd:simpleType> | ||
+ | |||
+ | </source> | ||
+ | |||
+ | In the example above the type ''type1'' is a restriction of the ''string'' type having only 3 possible values : ''value1, value2 and value3''. This is simply translated in JAXB using the <code>@XmlEnum</code> annotation as follows: | ||
+ | |||
+ | <source lang="java5"> | ||
+ | |||
+ | @XmlEnum(String.class) | ||
+ | public enum type1 { value1, value2, value3 } | ||
+ | |||
+ | </source> | ||
=== Faults === | === Faults === | ||
Line 917: | Line 946: | ||
At fault time, the JAX-WS runtime will instantiate <code>OpExceptionInfo</code> from the fault element, and then it will pass it to the constructor/s of <code>OpException</code>. | At fault time, the JAX-WS runtime will instantiate <code>OpExceptionInfo</code> from the fault element, and then it will pass it to the constructor/s of <code>OpException</code>. | ||
− | === | + | === Factory Operations === |
− | + | We've briefly discussed [[#Calling Instances|above]] the case of stateful services and their companion factory services. Let us know see how to model operations of factory services that create instances and return references to them. | |
− | Assume <code>create</code> is | + | Assume <code>create</code> is one such operation. Typically, the WSDL will define its response element as follows: |
<source lang="xml"> | <source lang="xml"> | ||
Line 939: | Line 968: | ||
</source> | </source> | ||
− | Here we're using a <code>BARE</code> pattern | + | Here we're using a <code>BARE</code> pattern. We then model <code>create</code> in the SEI of the factory using Java's [http://docs.oracle.com/javase/6/docs/api/javax/xml/ws/wsaddressing/W3CEndpointReference.html W3CEndpointReference]: |
<source lang="java5"> | <source lang="java5"> | ||
Line 945: | Line 974: | ||
@SOAPBinding(parameterStyle=ParameterStyle.BARE) | @SOAPBinding(parameterStyle=ParameterStyle.BARE) | ||
W3CEndpointReference create(....) ... ; | W3CEndpointReference create(....) ... ; | ||
+ | |||
+ | </source> | ||
+ | |||
+ | Assume now a <code>WRAPPED</code> pattern was followed in the WSDL: | ||
+ | |||
+ | <source lang="xml"> | ||
+ | |||
+ | <element name="createResponse> | ||
+ | <complexType> | ||
+ | <sequence> | ||
+ | <element name="return" type="wsa:EndpointReferenceType"/> | ||
+ | </sequence> | ||
+ | </complexType> | ||
+ | </element> | ||
+ | |||
+ | </source> | ||
+ | |||
+ | We then have the usual two options. If we can use the <code>WRAPPED</code> parameter style, then we can model <code>create</code> in the SEI as follows: | ||
+ | |||
+ | <source lang="java5"> | ||
+ | |||
+ | @SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) | ||
+ | @WebResult(name="return") | ||
+ | W3CEndpointReference create(@WebParam(name="...")..., @WebParam(name="...")...,...); | ||
+ | |||
+ | </source> | ||
+ | |||
+ | If instead we're forced to use a code>BARE</code> parameter style, then we can model then can model <code>create</code> in the SEI as follows: | ||
+ | |||
+ | <source lang="java5"> | ||
+ | |||
+ | @SOAPBinding(parameterStyle=ParameterStyle.BARE) | ||
+ | CreateResponse create(...); | ||
+ | |||
+ | </source> | ||
+ | |||
+ | where <code>CreateResponse</code> is the bean class: | ||
+ | |||
+ | <source lang="java5"> | ||
+ | |||
+ | public class CreateResponse { | ||
+ | @XmlElement | ||
+ | public W3CEndpointReference return; | ||
+ | } | ||
</source> | </source> |
Latest revision as of 13:49, 23 September 2013
common-gcore-stubs is a client-library that interacts with the JAX-WS runtime of the Java platform to generate dynamic JAX-WS proxies of remote gCore services. Architecturally, it operates at the lowest layer of the Featherweight Stack for gCube clients.
common-gcore-stubs
is available through our Maven repositories with the following coordinates:
<artifactId>common-gcore-stubs</artifactId> <groupId>org.gcube.core</groupId>
Contents
Overview
At the time of writing, most gCube services are JSR101 (JAX-RPC) services implemented on the gCore stack and running inside a gCube Hosting Node.
common-gcore-stubs
allows us to invoke such services without dependencies on that stack from arbitrary client environments. It does so by interacting on our behalf with the JSR224 (JAX-WS) runtime, which is part of the Java platform since version 1.6. Effectively, with common-gcore-stubs
we use a modern standard to call legacy services.
We provide the library with:
- a service descriptor, i.e. information about the service such as gCube coordinates (service class, service name) and WSDL coordinates (service name, porttype name);
- a Service Endpoint Interface (SEI), i.e. a local Java interface that models the remote API of the service and provides additional information about its endpoints through JSR-181 annotations.
- the address of target endpoints/instances of the service;
The library gives us back dynamically generated implementations of the SEI. The implementations are first synthesised by the underlying JAX-WS runtime and then appropriately configured by the library to issue gCube calls to the target endpoint (i.e. propagate the call scope, target service coordinates, client identity, etc.).
SEI implementations can then serve as local stubs for service endpoints/instances. Typically, we use them to implement higher-level client libraries.
The SEI and the other required information may be distributed as a stand-alone component, like for JAX-RPC stubs. Alternatively, they may be integral part of our client libraries. The fact that these 'stubs' have a minimal footprint, do not need to be generated through tooling, and are client-only artefacts makes the embedding option natural and in fact appealing.
Quick Tour
We run through a simple example to illustrate the process and relevant APIs.
Acme
For the sake of simplicity, let us illustrate how to use common-gcore-stubs
to call a fictional gCore Acme service.
Let us assume that the remote API of Acme
is defined by the following WSDL:
<definitions name="Acme" targetNamespace="http://acme.org" xmlns:tns="http://acme.org" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <types> <xsd:schema targetNamespace="http://acme.org"> <xsd:element name="foo" type="xsd:string" /> <xsd:element name="fooResponse" type="xsd:string" /> </xsd:schema> </types> <message name="foo"> <part name="request" element="tns:foo"/> </message> <message name="fooResponse"> <part name="response" element="tns:fooResponse"/> </message> <portType name="AcmePortType"> <operation name="foo"> <input message="tns:foo"/> <output message="tns:fooResponse"/> </operation> </portType> <binding name="AcmePortTypeSOAPBinding" type="tns:AcmePortType"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="foo"> <soap:operation soapAction="http://acme.org/AcmePortType/fooRequest"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding> <service name="service:AcmeService" xlmns:service="http://acme.org/service"> <port name="AcmePortTypePort" binding="tns:AcmePortTypeSOAPBinding"> <soap:address location="...some address..."/> </port> </service> </definitions>
Like most gCore services, Acme:
- defines a single porttype,
AcmePortType
. In this case the porttype includes a single operation,foo
, which takes and returns a string; -
foo
can be invoked through SOAP over HTTP in a document/literal style (essentially, messages are made directly of elements defined in the<types>
section)
Note: since the WSDL describes an Acme endpoint, it includes also its address. However, this address is largely irrelevant to our purposes because we use the WSDL to call different endpoints which we locate dynamically through our Information Services.
Note: gCore services are normally developed WSDL-first and use tooling to derive a WSDL complete with binding information (cf. <binding>
, <service>
) from a partial WSDL that includes only logical definitions (cf. <types>
, <message>
s, <portType>
). By design, the tooling spreads the complete WSDL across a number of files that follow a chain of imports. It also defines ad-hoc namespaces for the information it derives (e.g. http://acme.org/service
for the <service>
definitions). Here, we present the WSDL as a whole but keep using a different namespace for the <service>
definition, so as to facilitate mapping the example to the WSDLs of real gCube services.
The WSDL provides the following coordinates about Acme, which we capture in a class of constants to use later with common-gcore-stubs
:
import .... public class AcmeConstants { public static final QName name = new QName("http://acme.org/service","AcmeService"); public static final String porttypeNS = "http://acme.org"; public static final String porttypeLN = "AcmePortType"; }
Service Endpoint Interface
In JAX-WS terminology, the SEI is a local Java interface that mirrors the remote API of service endpoints. The interface includes annotations that provide the JAX-WS runtime with (some of the) information required to generate an implementation on the fly.
One way to obtain a SEI is to derive it from the WSDL with tooling, such as the wsimport utility which ships with the JDK. For this example, however, we produce the SEI manually, which gives us more control and makes for cleaner code.
import .............AcmeConstants.*; ... @WebService(name=porttypeLN,targetNamespace=porttypeNS) public interface AcmeStub { @SOAPBinding(parameterStyle=ParameterStyle.BARE) String foo(String s); }
We name the SEI so as to reflect that it acts as a local API for remote service endpoints. We annotate it with @WebService
, providing the coordinates of the service porttype that defines the remote operations. For this, we use the constants of the AcmeConstants
class defined above, which we statically import for improved legibility of the code. We then declare the method foo
and annotate it with @SOAPBinding
to indicate that its input and output should be put/found in request/response elements directly under the SOAP body.
We discuss how to write SEIs in more detail later on. For now, let us concentrate on how we use it with common-gcore-stubs
.
Service Descriptor
We now provide common-gcore-stubs
with a descriptor for Acme, i.e. the set of information which are required to call its endpoints. We provide the descriptor as an instance of the GCoreService
class, which we build in a fluent style with the help of a GCoreServiceBuilder
. A convenient place to do this is directly in the AcmeConstants
class introduced above. The following example illustrates:
import static org.gcube.common.clients.stubs.jaxws.GCoreServiceBuilder.*; ... public class AcmeConstants { ... public static String gcubeClass=.... public static String gcubeName=...; public static final GCoreService<AcmeStub> acme = service().withName(name) .coordinates(gcubeClass,gcubeName) .andInterface(AcmeStub.class); }
Since we will not need more than one instance of the descriptor, we create it once and for all as a constant named after the service. We invoke the static method GCoreServiceBuilder#service()
to begin with and then follow the methods of the fluent API to provide the remaining information, using the constants already available within the class, plus the gCube coordinates of the service. The static 'star' import is just a convenience to improve further the legibility of the code.
Calling Endpoints
When it's finally time to call a service endpoint, we use the SEI and the GCoreService
descriptor to obtain a SEI implementation configured for the endpoint:
import ......AcmeConstants.*; import static org.gcube.common.clients.stubs.jaxws.StubFactory.*; ... URI address = ... AcmeStub stub = stubFor(acme).at(address); String response = stub.foo("...");
We build our stub using the static method stubFor(GCoreService)
of the StubFactory
class, which we statically import for convenience.
We provide the factory with the acme
descriptor defined earlier, which we also statically import.
We also provide the address of the endpoint, here modelled as a URI
.
Finally, we use the stub returned by the StubFactory
to call the endpoint through the SEI.
Note: as we're calling a gCube service, we need to do so in a given scope or the stub will refuse to go ahead. One way to associate the call with a scope is to set it on the current thread:
ScopeProvider.instance.set('..some scope...");
Calling Instances
So far, we've implicitly assumed that Acme is stateless. However, many gCore services are stateful, their endpoints encapsulate data which they use and change upon processing client requests. Such endpoints can be modelled as collections of service instances, where all instances have the API of the service but are bound to different state. A service instance is typically created by an endpoint of a companion factory service which returns references to the instances. Such references are modelled on the wire as the endpoint references defined by WS-Addressing. In Java, the class EndpointReference models such references.
We will see later how to model instance references in the SEIs of factory services. For now, let us assume to have one, either because we've manually built it during testing (cf. Java's own W3CEndpointReferenceBuilder), or because we've obtained it from a factory service, or else because we've dynamically discovered by querying the Information Services. We use the reference to call a service instance as follows:
import ......AcmeConstants.*; import static org.gcube.common.clients.stubs.jaxws.StubFactory.*; ... EndpointReference reference = ... AcmeStub stub = stubFor(acme).at(reference); String response = stub.foo("...");
We thus interact with instances as we interact with endpoints, the only difference being that we pass the reference to the at()
clause of the build expression.
Note: we can use EndpointReference
s even when we target endpoints of stateless services, instead of URI
s. In other words, we can use the API of common-gcore-stubs
uniformly, if the code so requires.
Writing SEIs
The example above considers the simplest case of remote operation, where inputs and outputs are single atomic values. The range of remote operations we can encounter across gCore services is in fact quite wide. While the ultimate reference to writing and annotating SEIs is provided by the JAX-WS specifications and the specifications (JAXB), we consider some of the common cases below for convenience.
In all the cases, we ask the same question:
- how do we define and annotate the methods of the SEI so that the implementation generated by the JAX-WS runtime: a) sends requests which are understood by the service, and b) understands the responses produced by the service?
In what follows we assume that, like for the Acme service of our earlier example:
- the WSDL follows a document/literal style for its SOAP/HTTP binding, with requests and responses defined by a single element in accordance to WS-I profile;
- the request element is named after the corresponding operation. This convention follows best practices, as it allows SOAP engines to unambiguously dispatch requests. The response element is more freely named, though the convention is to suffix "Response" to the name of the operation.
The definitions of <message>
, <portType>
, <binding>
and <service>
elements become then boilerplate for our discussion, and we can omit it to concentrate solely on the definitions of request and response elements. In fact, we can simplify the presentation further if we agree to omit namespace prefixes altogether. Then we can illustrate each case by instantiating the following template:
<element name="op"> .... </lement> <element name="opResponse"> .... </element>
Wrapped or Bare?
One way in which operations differ within and across services is in the 'pattern' with which request and response elements are defined in the WSDL. As gCore services are document/literal services, the well-known patterns are BARE
and WRAPPED
. Given that the WSDLs of gCore services have the characteristics listed above, the difference between the two patterns is no more than the following:
- in the
BARE
pattern, request and responses have simple content. - In the
WRAPPED
pattern, they have complex context.
Clearly, the difference emerges only when operations take or return simple types, otherwise the pattern is necessarily WRAPPED
.
In the example above, the service used the BARE
pattern:
<element name="op" type="string" /> <element name="opResponse" type="string" />
In the SEI op
was then modelled as follows:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) String op(String s);
In response to the @SOAPBinding
annotation, the JAX-WS runtime generates a request element called after the operation, op
, and includes in it the input string as simple content. Similarly, it expects a response element with simple content.
Had the WSDL used the WRAPPED
pattern, the request and response elements would have looked like this:
<element name="op" > <complexType> <element name="param" type="string"> </complexType> </element> <element name="opResponse"> <complexType> <element name="return" type="string"> </complexType> </element>
The pattern is rather verbose in this case, but services may choose it to make clients more resilient to future changes to the API. If op
evolves to take further inputs, perhaps optional ones, clients that used to send a single string may still interact with the service. Similarly, if op
evolves to return multiple values, clients that expected a single string may still process the response.
Where the WSDL follows the WRAPPED
pattern, we have two ways of modelling op
in the SEI. In the first, we first define JAXB-annotated bean classes that bind to request and response messages. At their simplest, these may look as follows:
public class Op { @XmlElement public param; } public class OpResponse { @XmlElement public return; }
Note: since they act solely ad data transfer objects (DTOs), there is little incentive to make these beans more complex than they are, e.g. add accessors and mutators over private fields.
We then model op
in the SEI as follows:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) OpResponse op(Op s);
Here, the JAX-WS runtime prepares an op
request element and looks into the Op
bean for instructions on how to create its children. The JAXB annotations indicate that request element should have a param
child. Similarly for the response element.
Alternatively, we can signal to the JAX-WS runtime that the WSDL uses the WRAPPED
pattern and let it generate the bean classes for us. We do so by specifying a WRAPPED
parameter style in the @SOAPBinding
annotation:
@SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) @WebResult(name="return") String op(@WebParameter(name="param") String s);
Here, @WebParameter
names the child of the request element which should contains the string that we declare to take. Similarly, @WebResult
names the child of the response element which contains the string that we declare to return. JAX-WS generates the beans for request and elements, populates the request element with the string we declare to take, and extracts from the response element the string that we declare to return.
Note that we cannot use a WRAPPED
parameter style only for the input parameters, or only for the return value. If we tell JAX_WS to wrap the input parameters in a request element, then it will unwrap the response element, and vice-versa. We are thus forced to use the BARE
style when the operation:
- follows one pattern for the input and the other for the output, or vice-versa;
- has a response element with multiple children.
Note: In the latter case, we could still use the WRAPPED
style and Holder
input parameters (cf. Sect. 2.3.2 and Sect. 2.3.3 of the JAX-WS specifications), but we find that doing so is more trouble than worth.
In summary:
- we can use a
WRAPPED
parameter style if the request element has a complex type; - we must use a
BARE
parameters style if the request element or the response element have a simple type, or if the response element has more than one child element.
Since we will most often have to use a BARE
parameter style in the SEI, we can move the @SOAPBinding
annotation on the class declaration itself, and override this default on individual methods when we can and wish to use the WRAPPED
style.
In the following, we avoid showing how to write SEIs for all the possible pattern usage cases: pure BARE
, pure WRAPPED
, and mixed cases. Rather, we show solutions based on BARE
and WRAPPED
parameter style for inputs alone, with the understanding that the former will be required in the mixed case.
The Empty Case
Let us now consider an operation that expects no input:
<element name="op" > <complexType /> </element>
This is of course a corner case of the WRAPPED
pattern. If we can use the corresponding parameter style in the SEI, we can model op
as simply as follows:
@SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) @WebResult(name="...") T op();
If instead we're forced to use a BARE
parameter style, then we need to use an empty bean class as the input. For convenience, an Empty
bean class is included JAXWSUtils
class of common-gcore-clients
:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) void op(Empty empty);
The SEI method may then be invoked as follows:
import static ....JAXWSUtils.*; ... stub.op(empty);
where empty
is a constant of type Empty
provided by JAXWSUtils
.
Record Structure
Let us move on to an operation that expects the following request element:
<element name="op" > <complexType> <sequence> <element name="one" type="string"/> <element name="two" type="integer"/> </sequence> </complexType> </element>
If we can use the WRAPPED
parameter style in the SEI, we can model op
as simply as follows:
@SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) @WebResult(name="...") T op(@WebParam(name="one") String one, @WebParam(name="two") int two);
If instead we're forced to use a BARE
parameter style, then we need to use a bean class for the input.
@SOAPBinding(parameterStyle=ParameterStyle.BARE) T op(Op input);
where Op
is the following bean class:
@XmlRootElement public class Op { @XMLElement public String one; @XMLElement public int two; }
The example of course generalise to nested structure. We are firmly on JAXB ground and can use any of its annotations to deal with complex XML structures.
Collections
Operations often expects collections of values,e.g:
<element name="op" > <complexType> <sequence> <element name="element" maxOccurs="unbounded" type="string"> </sequence> </complexType> </element>
Modelling such operations in the SEI is just a special case of working with record structure. If we can use the WRAPPED
parameter style in the SEI, we can model op
as simply as follows:
@SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) @WebResult(name="...") T op(@WebParam(name="element") List<String> elements);
where we have chosen a List
type for the richness of the interface, though we could have chosen an array or a Set
if the intended usage or knowledge of data semantics had made this choice preferable.
If instead we're forced to use a BARE
parameter style, then we resort to the usual bean class for the input:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) ... op(Op input);
where OpInput
is the bean class defined as:
public class Op { @XmlElement(name="element") public List<String> elements; }
where we slightly customise the binding for a clearer API.
Variable Structures
Some operations take or return heterogenous data with heterogeneous forms. In some cases the variability is controlled, in that the data can take one of a predefined number of shapes. In other cases, variability is open-ended, i.e. the data can be any well-formed XML structure. We discuss some of the most common approach below.
Subtyping
In the following example, the operation expects one of two subtypes of a base type:
<element name="op" type="base" /> <complexType name = "base" abstract="true"> <sequence> <element name="a" type="string"/> </sequence> </complexType> <complexType name="sub1"> <complexContent> <extension base="base"> <sequence> <element name="b" type="string"/> <sequence> </extension> </complexContent> </complexType> <complexType name="sub2"> <complexContent> <extension base="base"> <sequence> <element name="c" type="integer"/> <sequence> </extension> </complexContent> </complexType>
Here, the request element can have the content model defined by either sub1
or sub2
, both of which inherit a property from base
.
Since the pattern followed in the WSDL is of course BARE
, we model op
in the SEI as follows:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) ... op(Op base);
where Op
is the abstract class defined as:
@XmlSeeAlso({Subone.class,Subtwo.class}) public abstract class Op { @XmlElement public String a; }
and Sub1
and Sub2
are subclasses of Op
public class Sub1 extends Op { @XmlElement public String b; } public class Sub2 extends Op { @XmlElement public int c; }
Note the JAXB @XmlSeeAlso
annotation on Op
, which points the JAX-WS runtime to Sub1
and Sub2
whenever it needs to serialise an instance of those two types.
We can now invoke op()
as follows:
Sub1 s1 = ... Sub2 s2 = ... ....stub.poly(s1).... ....stub.poly(s2)...
Let us now consider the case in which op
follows the WRAPPED
pattern in the WSDL, e.g.:
<element name="op"> <complexType> <sequence> <element name ="param" type="base" /> </sequence> </complexType> </element> ....type definitions for Base, Sub1, and Sub2
We distinguish between the usual cases. If we can use the WRAPPED
parameter style, we can model op
in the SEI as follows:
@SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) @WebResult(name="...") ... op(@WenParam(name="param") Base base);
reusing the definitions given above for Base
, Sub1
, and Sub2
.
If we are instead forced to the the BARE
parameter style, we can model op
in the SEI as follows:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) ... op(Op base);
where Op
is defined as:
public class Op { @XmlElement public Base param; }
Choices
In the previous case, the two subtypes inherited a common property from the base type. Often, however, the request element can take two entirely unrelated form. While it is possible (and indeed advantageous) to use an empty base type to model this case as the previous, it is more common to express the variation as an explicit xsd:choice
, as in the following example:
<element name="op"> <complexType> <choice> <element name="one" type="choice1"/> <element name="two" type="choice2"/> </choice> </complexType> </element> <complexType name="choice1"> <sequence> <element name="a" type="string"/> <sequence> </complexType> <complexType name="choice2"> <sequence> <element name="b" type="string"/> <sequence> </complexType>
Notice that this approach follows the WRAPPED
pattern.
We can follow either one of two approaches to model op
in the SEI.
The first approach is based on overloading. Assuming we can only use the BARE
parameter style:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) ... op(Op1 one); @SOAPBinding(parameterStyle=ParameterStyle.BARE) ... op(Op2 two);
where Op1
and Op2
are defined as follows:
public class Op1 { @XmlElement public Choice1 one; } public class Op2 { @XmlElement public Choice2 two; }
and where Choice1
and Choice2
are defined as:
public class Choice1 { @XmlElement public String a; } public class Choice2 { @XmlElement public int b; }
Overloading is more appealing if we can use the WRAPPED
parameter style, as we can then avoid a level of wrapping and model op
in the SEI as follows:
@SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) @WebResult(name="...") ... op(@WebParam(name="one") Choice1 one); @SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) @WebResult(name="...") ... op(@WebParam(name="two") Choice 2 two);
The other, more general approach is to retain a degree of polymorphism in the SEI:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) ... op(Op one);
where:
@XmlSeeAlso({Choice1.class,Choice2.class}) public abstract class Op {} public class Choice1 extends Op {...as above...} public class Choice2 extends Op {...as above...}
Note: we must use an abstract class here, we cannot replace it with an interface.
The any
Case
Let us now consider the case of an operation that does not constrain the data to assume predefined forms. The standard WSDL idiom in gCore service for this relies on the xsd:any
element, which allows any well-formed XML element structures.
For example:
<element name="op"> <complexType> <sequence> <any ..../> </sequence> </complexType> </element>
Even if the pattern is implicitly WRAPPED
here, we are forced to use the BARE
parameter style in the SEI:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) ... op(Op any);
where AnyElement
is the following bean class:
public class Op { @XmlAnyElement public org.w3c.dom.Element any; }
where the annotation @XmlAnyElement
instructs the runtime to serialise the any
as generic XML.
The enumeration Case
Let's now consider the case of an Enumeration which is a constrain on the values a type should assume.
For example:
<xsd:simpleType name="type1"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="value1"/> <xsd:enumeration value="value2"/> <xsd:enumeration value="value3"/> </xsd:restriction> </xsd:simpleType>
In the example above the type type1 is a restriction of the string type having only 3 possible values : value1, value2 and value3. This is simply translated in JAXB using the @XmlEnum
annotation as follows:
@XmlEnum(String.class) public enum type1 { value1, value2, value3 }
Faults
SEI clients may observe a wide range of failures, including: failures that occur in the client runtime, before remote calls to endpoints are issued; failures that occur in the attempt to communicate with endpoints; failures that occur in the runtime of endpoints. We distinguish between the following types of failures:
- errors are violations of the contract defined by the service which can imputed to faulty code or faulty configuration. Illegal SEI definitions are examples of client-side errors, while bugs in the implementation of the service are examples of service-side errors.
- contingencies are predictable violations of contract pre-conditions. There may be no bugs in either client or service code, but the endpoint is put in a state that prevents it to carry out the client’s request. Data that cannot be found or cannot be created are examples of contingencies.
- outages are I/O failures of the external environment and include network failures, database failures and disk failures.
We take the common view that errors ought to emerge as soon as possible, hence should be modelled as unchecked exceptions. Client-side errors emerge from the JAX-WS runtime as WebServiceException
, which are RuntimeException
s. Server-side errors emerge as SoapFaultException
, also unchecked as a subclass of WebServiceException
.
We also take the common view that outages cannot be recovered from, at most contained high up in the client stack. For this reason, we also suggest to model them with unchecked exceptions. Again, the JAX-WS runtime returns them as SoapFaultException
s.
What we're left with is contingencies, which we suggest to model as checked exceptions under the expectations that they may be recoverable and clients should prepare for them.
Services model contingencies explicitly in WSDLs, e.g. :
<element name="OpFault"> <complexType> ..... </complexType> </element> ... <message name="OpFault"> <part name="fault" element="OpFault"/> </message> ... <operation name="op"> <input message="..."/> <output message="..."/> <fault name="fault" message="OpFault"/> </operation>
Note: Contingencies often extend shared fault types: GCUBEUnrecoverableFault
, GCUBERetrySameFault
, GCUBERetryEquivalentFault
, all subclasses of GCUBEFault
. Each class captures a generic aspect of the fault semantics that equally generic clients may react to. Since the approach relies on shared types, however, it is rather coupling. Accordingly, we will not attempt to preserve that general semantics in our SEIs.
To model OpFault
in the SEI, we first define a corresponding exception OpException
:
@WebFault(name="OpFault") public class OpException extends Exception { ...... }
where we use the annotation @WebFault
to point the JAX-WS runtime to the corresponding element of the fault message returned by the service.
We then declare to throw it from the method that models op
:
.. op(...) throws OpException;
In some cases, OpFault
carries descriptive information, e.g.:
<element name="OpFault"> <complexType> <sequence> <element name="detail" type="string"> </sequence> </complexType> </element>
We can model this information as a bean class:
public class OpExceptionInfo { @XmlElement public String details; }
and then expect instances of the bean class in one or both of the following constructors of OpException
:
@WebFault(name="OpFault") public class OpException extends Exception { private final OpExceptionInfo info; public class OpException(String msg, OpExceptionInfo info) { super(msg); this.info=info; } public class OpException(String msg, OpExceptionInfo info, Throwable cause) { super(msg,throwable); this.info=info; } ...... public OpExceptionInfo getFaultInfo() { return info; } }
At fault time, the JAX-WS runtime will instantiate OpExceptionInfo
from the fault element, and then it will pass it to the constructor/s of OpException
.
Factory Operations
We've briefly discussed above the case of stateful services and their companion factory services. Let us know see how to model operations of factory services that create instances and return references to them.
Assume create
is one such operation. Typically, the WSDL will define its response element as follows:
<definitions ... xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing" .... > ... <types> <import namespace="http://schemas.xmlsoap.org/ws/2004/03/addressing" .... /> ... <element name="createResponse type="wsa:EndpointReferenceType"> ... </types> ...
Here we're using a BARE
pattern. We then model create
in the SEI of the factory using Java's W3CEndpointReference:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) W3CEndpointReference create(....) ... ;
Assume now a WRAPPED
pattern was followed in the WSDL:
<element name="createResponse> <complexType> <sequence> <element name="return" type="wsa:EndpointReferenceType"/> </sequence> </complexType> </element>
We then have the usual two options. If we can use the WRAPPED
parameter style, then we can model create
in the SEI as follows:
@SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) @WebResult(name="return") W3CEndpointReference create(@WebParam(name="...")..., @WebParam(name="...")...,...);
If instead we're forced to use a code>BARE</code> parameter style, then we can model then can model create
in the SEI as follows:
@SOAPBinding(parameterStyle=ParameterStyle.BARE) CreateResponse create(...);
where CreateResponse
is the bean class:
public class CreateResponse { @XmlElement public W3CEndpointReference return; }