Difference between revisions of "Contexts"

Revision as of 18:06, 24 April 2009

Within service implementations, some functionality needs to be accessed by different components and for different purposes.

The most obvious case of shared functionality is the functionality required to expose the configuration of the service, or the configuration of its RI, or the configuration of the gHN on which the RI is deployed. There is also information related to scope and security which is dynamically acquired and simultaneously needed by different components. And moving beyond information access, there are utilities and behaviours, both general-purpose and service-specific, which may be called upon from multiple and functionally unrelated components.

The gCF approach to shared functionality is to centralise it in distinguished components, called contexts, which are directly 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 in a thread-safe manner.

There are different type of contexts in gCF, each of which centralises functionality that is conceptually associated with key entities of service implementations: 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 the target services of the RI. Some are fully defined within gCF (e.g. the context of the gHN). Others are only partially implemented and need to be specialised within service implementations. Collectively, the context form a inheritance hierarchy contained in the contexts package:

As shown in the diagram, the entire framework has dependencies on the contexts packages, in line with the definition of contexts as repositories of shared functionality. The high-level roles of the components in the package is summarised below:

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

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

• 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.

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

• GHNClientContext: a concrete specialisation of GCUBEContext for a gCube Hosting Node that is not runnning.

Before discussing each context class in detail, we refine our the service model to introduce key context classes from the perspective of the service developer:

The figure shows that the GHNContext, the GHNClientContext, and GCUBERemotePortTypeContext are fully implemented by the framework and live outside the boundary of specific service implementations. In contrast, service and port-type contexts fall in the scope of service implementations as specialisations of gCF context classes.

Common Facilities

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

The primary form of configuration supported by gCF contexts is name-based lookup of arbitrary objects. The underlying configuration mechanism relies on a dedicated implementation of the JNDI interface.In particular, gCF contexts act as wrappers of standard JNDI contexts to offer a simplified lookup interface.

The underlying JNDI implementation remains opaque to both clients and implementers of context classes. Developers are only exposed to the configuration files used to populate the JNDI implementation wrapped by the contexts. 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 in turn 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 underly gCF. Conventions on context-specific configuration authoring are discussed below in relation to each type of context.

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

• access files stored in the local file system, for reading or writing purposes. File locations are abstracted over to avoid gHN-specific dependencies and all contexts offer basic backup facilities: transparently to their clients, they create copies of files that are about to be modified and used backup copies whenever the original files are corrupted.

• access files packaged with the context as classpath resources, 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 the following (see the code documentation for details of signature):

• getProperty(name,mandatory?): resolves a configuration property from its name. An optional flag indicates whether the configuration of the property is mandatory or else is optional (default). The flag is used for error and log management purposes.

• getResource(path): returns a classpath resource from 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 File for read or write access. A write mode induces backups and a read mode (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 following refinement of the service model emphasises the configuration and file management role of contexts:

The gHN Context

The GHNContext specialises GCUBEContext to serve as the gCF context for the local gHN. In particular, the GHNContext:

• manages the lifetime of the gHN, from its initialisation to its shutdown and failure.

This functionality supports the internal operation of the gHN and remains transparent to most service developers.

• exposes the configuration of the gHN and its hosting environment.

This functionality allows service developers to inspect at runtime the environment in which their code is deployed.

• mediates between RIs of deployed services.

This functionality supports mutual discovery of RIs at runtime and, while it is generically available to all service developers, it is key for the correct operation of the gHN and distinguished Local Services.

Note: Clients can obtain the single instance of the GHNContext by invoking its static method getContext(). The singleton is initialised when the GHNContext class is loaded.

Lifetime Management

For lifetime management purposes, the gHN context models the gHN as the following finite state machine:

Some gHN states are operational, in that the gHN can dispatch client calls to their target services and can accept the deployment of new service and the undeployment of currently deployed services. Others are instead non-operational. The gHN states can be described as follows:

• DEPLOYED: this is the state of a gHN that is locally installed but not necessarily running within the current process (or not running at all).

This is a start and non-operational state in which the gHN context determines whether the gHN is running in the current process. If the gHN is not running, this state is also terminal and the gHN context can only be used for configuration management purposes. This mode of operation of the context is called client mode.

Note: In client mode, the gHN context singleton is an instance of GHNClientContext, a subclass of GHNContext.

• STARTED: this is the state of a running gHN that is in the process of initialisation.

This is a non-operational state in which the gHN context initialises the gHN. This involves loading its configuration; synthesising a GCUBEHostingNode resource that models it, either from scratch or from past serialisations of its profile; scheduling periodic updates to the state of the gHN which depends on the local hosting environment; opening local interfaces for management and monitoring (if appropriately configured). The successful completion of these activities triggers a brief transition of the gHN to the UPDATED.

• READY: this is the state of a gHN in which not all the RIs of the deployed services are operative.

This is an operational state in which some of the deployed RIs may still be in the process of initialisation or may have failed. The gHN enters this state after having triggered the initialisation of all the RIs. It may then transition back to it from after certification, if one of the RIs fails.

• CERTIFIED: this is the state of a gHN in which all the deployed RIs are operative.

This is an operational state that marks the absence of problems on the gHN.

• UPDATE: this is the state of a gHN that has changed some its properties.

This is a temporary state in which the gHN context notifies all interested clients of the change before returning to its previous state. The gHN can transition to this state from all other states, either to mark the imminent transition (after successful initialisation, before normal or abnormal termination, to flag readiness or certification), or in response to key lifetime event (addition and removal of scopes), or simply because of the periodic regeneration of the gHN profile.

• DOWN: this is the state of a gHN that is about to terminate execution without having experienced a failure.

This is a non-operational state in which the gHN is about to terminate the current process, often to restart immediately after the deployment of new services.

• FAILED: this is the state of a gHN that is about to terminate execution because it has experienced a failure.

This is a non-operational state in which the gHN is about to terminate the current process.

Key state transitions are regulated by the exchange of events between the gHN context and the service contexts of its RIs:

• Service contexts register RIs with the gHN context, as part of their own initialisation and as early as during the initialisation of the gHN itself (registerService()). In response, the gHN context subscribes with the service contexts of the registered RIs as a consumer their lifetime events. It can then be notified of the current state of the RIs and act accordingly, e.g. move to the CERTIFIED state when all of them become operational, or return to the READY state when one of them fails.

Note Any client of the gHN context can then access the service context of some or all the RIs that have registered (cf. getServiceContext(), getServiceContexts()). Any service, in particular, can rely on this functionality to interact with other, co-deployed services without having static dependencies on them. One distinguished client in gCF, the GCUBEHandler, relies on it to block calls made to RIs that are no longer or not yet operative, but also to propagate the scope of the call to their service contexts.

• Service contexts also subscribe with the gHN to request the renewal of the credentials that their RIs may need to operate in a secure infrastructure (subscribeForCredential()). The gHN context acts as a mediator between the RIs and the RI of distinguished Local Service, the Delegation service, which is responsible for arranging the periodic renewal of credentials with remote Security Services (cf. security management), In particular, the RI of the Delegation also subscribes with the gHN context to be notified of credential renewal request (subscribeForCredentialRequest()) and, when credentials are delivered by the infrastructure, it asks the gHN to pass them on to the RI which originally requested them ((delegateCredentials())). The mediation of the gHN context is based on dedicated topics (CREDENTIAL_REQUEST,CREDENTIAL_DELEGATION) and events (CredentialRequestEvent,CredentialDelegationEvent). The gHN context defines also partial implementations for prospective consumers of security-related events (CredentialConsumer,CredentialRequestConsumer).

• The lifetime of the gHN can be monitored too. The gHN context defines topics (RIREGISTRATION, SHUTDOWN, READY, UPDATE) and events (GHNRIRegistrationEvent,GHNLifetTimeEvent) for which clients can subscribe and unsubscribe (subscribeGHNEvents(), unsubscribeGHNEvents()). The gHN defines also a partial implementation for prospective consumer of lifetime events (<code>GHNConsumer).

Note: Only privileged clients and the gHN itself can trigger state transitions (cf. setStatus()). All clients however can inspect the current state of the gHN, either synchronously (cf. getStatus()) or asynchronously, via notification of state transitions.

Configuration Management

The gHN configuration exposed by the gHN context includes:

• configuration related to the infrastructure in which the gHN operates (cf. the Administrator's Guide).

Some configuration properties - most noticeably those properties that benefit from some form of post-processing - are exposed by dedicated methods (e.g getInfrastructure(), getStartScopes(), getMode(), getType(), getHostame(), getPort(), etc.). Others are available via the GCUBEHostingNode resource maintained by the GHNContext (getGHN()). Yet other configuration properties can be accessed with the generic facilities that the gHN context inherits from GCUBEContext (getProperty()).

• configuration related to the implementations of core gCF interfaces, e.g. discovery, publishing, and remote notification interfaces (cf. getImplementation()).

• statistics and other information related to the underlying hardware (getFreeSpace), getUptime(), getMemoryUsage(), getCPUInfo(), getLoadStatistics(), etc.).

Note: The facilities for file management that the gHN context inherits from GCUBEContext (getFile()) are for internal use and service developers should not use them. Service developers can access the file system using dedicated facilities in their service context.

Service Contexts

The GCUBEServiceContext specialises the GCUBEContext to serve as the gCF context for the services deployed on the local gHN as well as for their RIs. A concrete specialisation of GCUBEServiceContext in the context of a service implementation yields a component that:

• manages the lifetime of the RI, from its initialisation and staging to its updates and failure.

This functionality supports the correct operation of the RI within the infrastructure and can be refined and extended by service developers.

• exposes the configuration of the RI and its service.

This functionality allows service developers to inspect the at runtime the properties of the RI and its service.

• acts as a centralised manager of scope and security information for the entire service implementation.

This functionality supports the loosely-coupled propagation of scope and security information across arbitrary components of the service implementation.

Note: Service developers that specialise GCUBEContext are responsible for its behaviour as a singleton class. To do this in a thread-safe manner, see the guidelines and examples included in the javadoc documentation and in the primer. According to the guidelines, the single instance of a service context is initialised at the point of first use.

Lifetime Management

For lifetime management purposes, the GCUBEServiceContext models the RIs as the finite state machine shown below.

File:RIStatesjpg

The different states of the RI are represented by the values of the inner enumeration GCUBEServiceContext.Satus:

• Status.DEPLOYED: this is the start state of an uninitialised RI.

While the RI is in this state, the service context performs the initialisation of the RI from service configuration. The performed activities include:

• load the service profile into a GCUBEService resource and the RI profile into a GCUBERunningInstance resource (either from scratch or from traces of previous RI activity in the local gHN). The service context will then use these resource when transitioning to Status.UPDATED in order to derive updated RI profiles from serialisations of their state (cf. the resource model).
• configure the scope manager and security manager of the RI (cf. Scope Managers, Security Managers). Thereafter, the service context can impersonate such managers and delegate calls to them.
• configure the remote persistence manager of the RI (cf. Remote Persistence).
• register the RI with the GHNContext (cf. the gHN Context).

• Status.INITIALISED: this is the state of a RI that is fully initialised but not yet ready to process client requests.

While the RI is in this state, the service context performs the following activities in parallel:

• place a request for service credentials with the GHNContext, if any are needed by the RI when it operates in a secure infrastructure (cf. Security Managers). The request involves registering an internal listener with the GHNContext for the periodic arrival of valid service credentials. No state transition will take place before the arrival of the fist set of valid credentials.
• recover any state that the RI might have previously stored in the infrastructure, either from the current gHN or, in case the RI has been dynamically redeployed on the current gHN, from another gHN (cf. Remote Persistence). No state transition will take place until the recovery is complete.

• Status.READIED: this is the state of a RI that is fully operative within the infrastructure.

While in this state, the RI services incoming requests. Upon entering this state, the service context performs the following activities:

• it subscribes with the GHNContext to be informed of the shutdown of the gHN (cf. Contexts#The gHN Context). When this happens, the service context moves the RI to Status.FAILED.
• it subscribes with the GCUBEHostingNode resource managed by the GHNContext to be notified when the gHN is removed from one of its scopes (cf. Scope Management). When this happens, the service context removes the RI from the same scope, if it was operating in it in the first place.

• Status.UPDATED: this is the transitional state of a RI that has changed some of its state.

• This is a short-lived stage of the RI in which the service context notified subscribed consumers of state changes and generates a profile within the infrastructure. Upon completion of these activities, the service context reverts the RI to its previous state.

• Status.FAILED: this is the terminal state of a RI that is no longer operative within the infrastructure, typically because of a fatal failure of the RI or the local gHN.

• As the RI enters this state, the service context informs subscribed consumers, including the GHNContext. As a result, future calls to the RI are blocked.

Note: The service context accepts subscriptions from clients that wish to be notified of state transitions of the RI. Subscribers are typically distinguished components of the service implementations, although any they may also be components of co-deployed services that have dynamically discovered the service context through the GHNContext. The subscription topics correspond to states the RI transitions to and the service context models them with the values of the inner enumeration GCUBEServiceContext.RILifetimeTopic (e.g. RILifetimeTopic.INITIALISATION and RILifetimeTopic.READY). It then models events with the inner classe GCUBEServiceContext.RILifetimeEvent. To subscribe to one or more lifetime topics, clients needs to register a concrete implementation of the inner class GCUBEServiceContext.RIConsumer (cf. subscribeLifetTime()). Clients subclass GCUBEServiceContext.RIConsumer by implementing the callbacks that correspond to the events of interest (e.g. GCUBEServiceContext.RIConsumer.onRIReady()).

Note: The facilities and activities described above are entirely implemented in GCUBEServiceContext and remain transparent to its subclasses. However, subclasses can tailor them to the semantics of specific services by overriding a set of callbacks that are invoked by GCUBEServiceContext immediately before RI transitions to key stages (cf. onInitialisation(), onReady(), onUpdate(), onStatesChange(), onFailure()).

Note: A failure in any of the activities described above - including callbacks - causes a transition of the RI to Status.FAILED.

Configuration Management

[coming soon]

PortType Contexts

[coming soon]