Revision as of 22:41, 21 May 2012

gCube includes client libraries for many of its services and defines a general model for their design. The model requires that, regardless of specific service semantics and client-side technology stacks, all libraries support a common set of capabilities and adopt the same solutions to design issues that recur across their APIs.

However, the model does not specify how libraries are implemented to provide such capabilities and design solutions, nor does it mandate the low-level details of their APIs. The client library framework is a set of components that support the development of client libraries which comply with the model. Through code sharing, the framework reduces development costs and ensures the consistency and correctness of library implementations.

In this document, we assume some familiarity with design model and illustrate how the framework can be used to develop a model-compliant client library for a hypothetical foo service.

Distribution

The framework is layered across as a set of libraries, all of which are available in our Maven [[1]] as artifacts in the org.gcube.core group.

common-clients is the top layer of the framework, i.e. defines its general capabilities irrespective of particular service technologies. In this sense, common-clients is as general as the design model for client library. Lower layers of the framework adapt common-clients to specific service technologies. At the time of writing, gCore is the dominant technology stack for gCube services and their clients. Accordingly, common-gcore-clients is the only available specialisation of common-clients.

We thus assume that foo is a gCore service, i.e. a JAX-RPC Java service that can be deployed in one or more gCore containers on some gCube hosting nodes. We also assume that a client library for foo is developed as a Maven project, in line with the management model for client libraries. In this case, the library specifies a compile-time dependency on the framework in its POM, as follows:

<dependency>
 <groupId>org.gcube.core</groupId>
 <artifactId>common-gcore-clients</artifactId>
 <version>...</version>
 <scope>compile</version>
</dependency>

This dependency will bring common-clients and other required transitive dependencies on the compile-time classpath of the library. The version will vary over time and is 2.0.0 at the time of writing. Even though the library will depend directly on classes and interfaces defined in common-clients, the library can safely omit a direct dependency on it.

The library will also have dependency on the stub library of foo, which we assume is also available as a Maven artifact, e.g.:

<dependency>
 <groupId>org.gcube.samples</groupId>
 <artifactId>foo-stubs</artifactId>
 <version>...</version>
 <scope>compile</version>
</dependency>

Overview

Calls and Delegates

Plugins

Queries