Contexts

Within the implementation of gCube services, some functionality needs to be accessed by different components and for different purposes.

The most obvious case is functionality that exposes the configuration of the service, its RI, or the gHN on which the RI is deployed; as shown later in the Guide, there is also dynamically acquired information related to scope and security that may need to be shared within service implementations. And beyond information access, there are general-purpose or service-specific utilities and behaviours that may be called upon from multiple and functionally unrelated components.

In gCF, the approach to shared functionality is to centralise it in distinguished components, called contexts, which are easily accessible from any other implementation component. gCF contexts are singleton classes, in that they are designed to be instantiated only once and to expose the single instance to all their clients.

There are different type of contexts in gCF, each of which centralises functionality that is conceptually associated with the service and its RI, the gHN on which the RI is deployed, the port-types of the service, and even the port-types of remote target services. Some of these contexts are fully defined within gCF (e.g. the context of the gHN). Others are only partially implemented and need to be specialised within individual service implementations. Collectively, the context form a inheritance hierarchy contained in the contexts package:

• GCUBEContext: the base implementation for all contexts in gCF.

• GCUBEGHNContext: a concrete specialisation of GCUBEContext for a gCube Hosting Node.

• GCUBEServiceContext: a concrete specialisation of GCUBEContext for a gCube Service.

• GCUBEPortTypeContext: a concrete specialisation of GCUBEContext for a port-type of gCube Service.

• GCUBEStatefulPortTypeContext: a concrete specialisation of GCUBEPortTypeContext for a stateful port-type of a gCube Service.

• GCUBERemotePortTypeContext: a concrete specialisation of GCUBEContext for a port-type of a target gCube Service.

Common Facilities

All gCF contexts offer basic facilities for configuration and local file management.

The primary form of configuration supported by gC contexts is based on named access to arbitrary objects. The underlying configuration mechanism is based on a dedicated implementation of the JNDI interface; in particular, gCF contexts act as a wrappers of standard JNDI contexts and offer a much simplified interface to named access.

The underlying JNDI implementation remains opaque to both clients and implementers of context classes. Developers are only exposed to the configuration files that are then used to populate the JNDI implementation wrapped by the contexts. As we discuss below, the direct subclasses of GCUBEContext are responsible for establishing conventions on the naming and location of such files, for the definition and documentation of pre-defined configuration properties, and for loading all the configuration properties from the files. As most service developers specialise these subclasses, they need only to author the configuration files. The syntax for authoring JNDI configuration is based on XML, and its definition is lifted from technologies that underlies gCF. Conventions on context-specific configuration authoring are discussed below in relation to each type of context.

As to file management, gCF contexts offers facilities to access:

• files stored in the local file system for reading or writing purposes. Here the main goal is to abstract over the location in which the files are stored and thus to avoid gHN-specific dependencies. While actual location in which files are stored is specific to the type of context, as we discuss below, all contexts offer basic backup facilities: transparently to their clients, they create copies of files that are about to be modified and used backups whenever the original files are corrupted. In the second case, access is read-only

• files packaged along with the context, or more generally on the classpath, for read-only purposes.

In both cases, the gCF contexts are agnostic to the content of the files. This may be service-specific configuration that lives outside the standard JNDI framework, or any form of state that is deemed suitable for file storage.

The basic operations for configuration and file management are following (see the code documentation for signature details):

• getProperty(name,mandatory?): resolves a configuration property from its name. An optional flag indicates whether the presence property is deemed mandatory or else is optional (default). The flag is used for error and log management purposes.
• getResource(path): returns a classpath file resource given its path. A relative path is resolved with respect to the context implementation, while an absolute path is resolved directly against the classpath.
• getFile(path,mode): returns a java.io.File for read or write access. A write access mode induces backups and a read access (default) relies on backups to recover from failures. In write mode, directories that are specified in the path but do not exist are automatically created, while paths that identify directories are disallowed.

The gHN Context

[coming soon]

Service Contexts

[coming soon]

PortType Contexts

[coming soon]