Difference between revisions of "Common-gcore-stubs"
(→The Service Descriptor) |
(→Writing SEIs) |
||
Line 192: | Line 192: | ||
== Writing SEIs == | == Writing SEIs == | ||
− | The example [[#Quick Tour|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 [http://jcp.org/aboutJava/communityprocess/final/jsr224 specifications] and the | + | The example [[#Quick Tour|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 [http://jcp.org/aboutJava/communityprocess/final/jsr224 specifications] and the [http://jcp.org/aboutJava/communityprocess/mrel/jsr222 specifications] (JAXB), we consider some of the common cases below for convenience. |
In all the cases, we ask the same question: | In all the cases, we ask the same question: | ||
Line 335: | Line 335: | ||
</source> | </source> | ||
− | + | This is of course a corner case of the <code>WRAPPED</code> pattern. If we [[#Wrapped or Bare?|can use]] the corresponding parameter style in the SEI, we can model <code>op</code> as simply as follows: | |
<source lang="java5"> | <source lang="java5"> | ||
− | @ | + | @SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) |
− | + | T op(); | |
</source> | </source> | ||
− | + | If instead we're forced to use a <code>BARE</code> parameter style, then we need to use an empty bean class as the input. For convenience, an <code>Empty</code> bean class is included <code>JAXWSUtils</code> class of <code>common-gcore-clients</code>: | |
− | + | ||
− | If instead | + | |
<source lang="java5"> | <source lang="java5"> | ||
Line 368: | Line 366: | ||
where <code>empty</code> is a constant of type <code>Empty</code> provided by <code>JAXWSUtils</code>. | where <code>empty</code> is a constant of type <code>Empty</code> provided by <code>JAXWSUtils</code>. | ||
− | === | + | === Record Structure === |
− | + | Let us move on to an operation that expects the following request element: | |
<source lang="xml"> | <source lang="xml"> | ||
Line 376: | Line 374: | ||
<element name="op" > | <element name="op" > | ||
<complexType> | <complexType> | ||
− | + | <sequence> | |
− | + | <element name="one" type="string"/> | |
− | + | <element name="two" type="integer"/> | |
+ | </sequence> | ||
</complexType> | </complexType> | ||
</element> | </element> | ||
Line 384: | Line 383: | ||
</source> | </source> | ||
− | If <code> | + | 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"> | ||
− | @ | + | @SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) |
− | + | T op(@WebParam(name="one") String one, @WebParam(name="two") int two); | |
</source> | </source> | ||
− | + | If instead we're forced to use a <code>BARE</code> parameter style, then we need to use a bean class for the input. | |
− | + | ||
− | + | ||
<source lang="java5"> | <source lang="java5"> | ||
@SOAPBinding(parameterStyle=ParameterStyle.BARE) | @SOAPBinding(parameterStyle=ParameterStyle.BARE) | ||
− | + | T op(Op input); | |
</source> | </source> | ||
− | where <code> | + | where <code>Op</code> is the following bean class: |
<source lang="java5"> | <source lang="java5"> | ||
− | public class | + | @XmlRootElement |
+ | public class Op { | ||
+ | |||
+ | @XMLElement | ||
+ | public String one; | ||
+ | |||
+ | @XMLElement | ||
+ | public int two; | ||
− | |||
− | |||
} | } | ||
</source> | </source> | ||
− | + | 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: | ||
<source lang="xml"> | <source lang="xml"> | ||
− | + | <element name="op" > | |
− | + | <complexType> | |
− | + | <sequence> | |
− | < | + | <element name="element" maxOccurs="unbounded" type="string"> |
− | + | </sequence> | |
− | + | </complexType> | |
− | + | </element> | |
− | + | ||
− | </ | + | |
− | </ | + | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
</source> | </source> | ||
− | + | Modelling such operations in the SEI is just a special case of working with [[#Record Structures|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"> | ||
− | @SOAPBinding(parameterStyle=ParameterStyle. | + | @SOAPBinding(parameterStyle=ParameterStyle.WRAPPED) |
− | + | T op(@WebParam(name="element") List<String> elements); | |
</source> | </source> | ||
− | where <code> | + | where we have chosen a <code>List</code> type for the richness of the interface, though we could have chosen an array or a <code>Set</code> if the intended usage or knowledge of data semantics had made this choice preferable. |
+ | |||
+ | If instead we're forced to use a <code>BARE</code> parameter style, then we resort to the usual bean class for the input: | ||
<source lang="java5"> | <source lang="java5"> | ||
− | @ | + | @SOAPBinding(parameterStyle=ParameterStyle.BARE) |
− | + | ... op(Op input); | |
− | + | </source> | |
− | + | ||
− | + | where <code>OpInput</code> is the bean class defined as: | |
− | + | ||
− | + | <source lang="java5"> | |
− | + | public class Op { | |
− | + | ||
− | + | ||
− | public class | + | |
− | + | ||
− | + | ||
− | + | ||
+ | @XmlElement(name="element") | ||
+ | public List<String> elements; | ||
} | } | ||
+ | |||
</source> | </source> | ||
+ | where we slightly customise the binding for a clearer API. | ||
− | + | === The Any Case === | |
− | + | Some operations take or return freeform XML structures, e.g.: | |
− | + | <source lang="xml"> | |
− | + | ||
− | + | ||
− | </ | + | <element name="op" > |
+ | <complexType> | ||
+ | <-- TODO --> | ||
+ | </complexType> | ||
+ | </element> | ||
− | + | </source> |
Revision as of 11:37, 29 November 2012
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
Quick Tour
At the time of writing, most gCube services are JSR101 (JAX-RPC) services implemented and running on the gCore stack inside a gCube Hosting Node. common-gcore-stubs
allows us to invoke such services without dependencies on that stack, hence from within 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 as the standard for SOAP-based Web Services and Web Service clients. With common-gcore-stubs
, we use a modern standard to call services that align with a legacy standard.
We provide the library with:
- information about the target service, such as its gCube coordinates (service class, service name) and its WSDL coordinates (namespace, porttype name);
- the address of a target endpoint of the services;
- the Service Endpoint Interface (SEI) of the service, i.e. the local Java interface that models the remote API of the service and provides additional information about its endpoint through JSR-181 annotations.
The library gives us back a dynamically generated proxy implementation of the SEI, which is first synthesised by the 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 generated proxy can serve as a local stub for Acme endpoints. Typically, we use this stub in the context of higher-level proxying facilities, such as gCube 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 the higher-level Client Library which uses them with common-gcore-stubs
. The minimal footprint of these 'stubs', the fact that they do not need to be manually generated (though they can), and the fact that they serve a client-only role (as opposed to JAX-RPC stubs, which we use also service-side) makes the embedding option natural and appealing.
In the following, we run through a simple example to illustrate the process and relevant APIs.
A Sample Service
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="binding:AcmePortTypeSOAPBinding" type="tns:AcmePortType" xlmns:binding=""http://acme.org/bindings""> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="foo"> <soap:operation soapAction="http://acme.org/StatelessPortType/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="binding:StatelessPortTypeSOAPBinding"> <soap:address location="...some address..."/> </port> </service> </definitions>
Like most gCore services, Acme:
- defines a single porttype,
AcmePortType
. For Acme, the porttype includes a single operation,foo
that 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, whose addresses we discover only at call time.
Note: gCore services are normally developed WSDL-first and use tooling to derive a WSDL complete with binding information from a partial WSDL that includes only logical definitions (types, port-types, operations). By design, the tooling spreads the derived 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, or http://acme.org/bindings
for <binding>
definitions). Here, we present the WSDL as a whole but keep using different namespaces for port-types, bindings, and service definitions 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 String serviceNS = "http://acme.org/service"; public static final String serviceLocalName = "AcmeService"; public static final QName serviceName = new QName(serviceNS,serviceLocalName); public static final String porttypeNS = "http://acme.org"; static final String porttypeLocalName = "AcmePortType"; }
The Service Endpoint Interface
In JAX-WS terminology, the SEI is a local Java interface that mirrors the remote API of the remote service. Its declaration includes annotations that provide the JAX-WS runtime with (some of the) information required to generate an implementation of the interface which can correctly call a service endpoint.
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=porttypeLocalName,targetNamespace=porttypeNS) public interface AcmeStub { @SOAPBinding(parameterStyle=ParameterStyle.BARE) String foo(String s); }
We name the SEI to reflect that it acts as a stub of the Acme service. As required by JAX-WS, we annotate the SEI with @WebService
, providing the coordinates of the porttype that includes the operations to be proxied through the SEI. 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
with the expected signature. We also annotate the method with @SOAPBinding
, to indicate that the input and output strings should be put/found in elements directly under the SOAP body.
We discuss how to write SEIs in more details later on. For now, let us concentrate on how we use it with common-gcore-stubs
.
The Service Descriptor
We now provide common-gcore-stubs
with a descriptor for the Acme service, i.e. the set of information which allow common-gcore-stubs
to call it. 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 the AcmeConstants
class first introduced above.
The following example illustrates:
import static org.gcube.common.clients.stubs.jaxws.GCoreServiceBuilder.*; ... public class AcmeConstants { ... public static String service_class="...."; public static String service_name="..."; public static final GCoreService<AcmeStub> acme = service().withName(serviceName) .coordinates(service_class,service_name) .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 use the static method GCoreServiceBuilder#service()
to kick off the process and the follow the type system to provide the remaining information, using the constants already available within the class, pus the gCube coordinates of the service. The static 'star' import is just a convenience to improve further the legibility of the code.
Stubbed Calls
When it's finally time to call an Acme endpoint, we use the SEI and the GCoreService
descriptor to obtain a an implementation of the SEI configured for the target endpoint:
import ......AcmeConstants.*; import static org.gcube.common.clients.stubs.jaxws.StubFactory.*; ... String address = AcmeStub stub = stubFor(acme).at(address); String response = stub.foo("...");
We build our AcmeStub
using the static method stubFor(GCoreService)
of the StubFactory
class, which as usual we statically import for convenience.
We provide the factory with the acme
descriptor that we've defined earlier in the AcmeConstants</code?> class, which we also statically import.
We also provide the address of the target endpoint, here modelled as a string in the assumption that the service is stateless. We shall see later how to model reference instances of stateful services.
Finally, we use the stub returned by the <code>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. The classic way to associate the call with a scope is to set it on the current thread:
ScopeProvider.instance.set('..some scope...");
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) String op(@WebParameter(name="param") String s);
Here, WebParameter
names the child of the op
request element which should contains the string that we declare to take. 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) 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) 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) 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.
The Any Case
Some operations take or return freeform XML structures, e.g.:
<element name="op" > <complexType> <-- TODO --> </complexType> </element>