Common-gcore-stubs
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>
Quick Tour
At the time of writing, most gCube services are 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 JAX-WS runtime, which is part of the Java platform since version 1.6.
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, synthesised by the JAX-WS runtime and then appropriately configured to issue gCube calls to the target endpoint (i.e. propagate the call scope, target service coordinates, client identity, etc.).
In the following, we illustrate the process and relevant APIs through a simple example.
A Dummy 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="fooInputMessage"> <part name="request" element="tns:foo"/> </message> <message name="fooOutputMessage"> <part name="response" element="tns:fooResponse"/> </message> <portType name="AcmePortType"> <operation name="foo"> <input message="tns:fooInputMessage"/> <output message="tns:fooOutputMessage"/> </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/StatelessPortType/fooRequest"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding> <service name="AcmeService"> <port name="AcmePortTypePort" binding="tns:StatelessPortTypeSOAPBinding"> <soap:address location="...some address..."/> </port> </service> </definitions>
Like all gCore services, Acme defines a single porttype, AcmePortType, with a single operation, foo() that takes and returns a string. Like for most gCore services, foo() can be invoked via SOAP/HTTP in a document/literal style (essentially request and response types appear in the SOAP <body> as they are defined in <types> section).
Note: While gCore services are WSDL-first, they use tooling to derive a WSDL complete with binding information from a partial WSDL that includes only logical definitions. The derived WSDL spreads over a number of files that follow a chain of imports. In this scheme, the namespaces used in the different files differ from those used before, which is however of no consequence for our example.
