Difference between revisions of "Contexts"
(→The gHN Context) |
(→The gHN Context) |
||
Line 103: | Line 103: | ||
*<code>Status.HALTED</code>: this is the state of a gHN that has terminated its execution within the JVM. | *<code>Status.HALTED</code>: this is the state of a gHN that has terminated its execution within the JVM. | ||
− | :This is a short-lived state in which the <code>GHNContext</code> attempts to terminate the JVM in which it is running. This state is triggered internally to the framework at the point of dynamic deployment. | + | :This is a short-lived state in which the <code>GHNContext</code> attempts to terminate the JVM in which it is running. This state is triggered internally to the framework at the point of dynamic service deployment. |
'''Note''': Only privileged clients and the gHN itself can trigger state transitions (cf. <code>setStatus()</code>). All clients however can inspect the current state of the gHN, either synchronously (cf. <code>getStatus()</code>) or asynchronously, via notification of state transitions. | '''Note''': Only privileged clients and the gHN itself can trigger state transitions (cf. <code>setStatus()</code>). All clients however can inspect the current state of the gHN, either synchronously (cf. <code>getStatus()</code>) or asynchronously, via notification of state transitions. |
Revision as of 13:52, 27 January 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 that 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 that is dynamically acquired and needed by different components. Beyond information access, there are utilities and behaviours - general-purpose or 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.
There are different type of contexts in gCF, each of which centralises functionality that is conceptually associated with the 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.
-
GCUBEGHNContext
: a concrete specialisation ofGCUBEContext
for a gCube Hosting Node.
-
GCUBEServiceContext
: a concrete specialisation ofGCUBEContext
for a gCube Service and its RIs.
-
GCUBEPortTypeContext
: a concrete specialisation ofGCUBEContext
for a port-type of gCube Service.
-
GCUBEStatefulPortTypeContext
: a concrete specialisation ofGCUBEPortTypeContext
for a stateful port-type of a gCube Service.
-
GCUBERemotePortTypeContext
: a concrete specialisation ofGCUBEContext
for a port-type of a target gCube Service.
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
and GCUBERemotePortTypeContext
are fully implemented by the framework and live outside the boundary of specific service implementations. In contrast, service and the 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 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 ajava.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 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 gCube Hosting Nodes.
In particular, the GHNContext
is the gCF component that:
- 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 dynamic discovery of RIs and, while it is generically available to all service developers, it is key for the correct operation of the gHN and distinguished Local Services.
Clients can obtain the single instance of the GHNContext
by invoking its static method getContext()
. The first invocation of the method triggers the initialisation of the instance.
For lifetime management purposes, the GHNContext
models the gHN context as the finite state machine shown below.
The different states of a gHN are represented by the values of the inner enumeration GHNContext.GHNSatus
:
Status.DOWN
: this is the state of a gHN that is not running within the current JVM (or not running at all).
- Detected during the initialisation of the
GHNContext
, this is at once an initial and terminal state for the gHN. When the gHN is in this state, theGHNContext
can only be used to access the gHN configuration and hardware-related information, as described below.
Status.RUNNING
: this is the state of a gHN that is running within the current JVM.
- When the gHN is in this state, the
GHNContext
engages in the following activities:
- it monitors for changes to the state of the gHN and generates its profile at regular intervals.
- During its initialisation, the
GHNContext
synthesises aGCUBEHostingNode
resource that models the local gHN (either from scratch or from traces of previous gHN activity in the local hosting environment ). It then periodically derives the gHN profile from a serialisation of the state of the resource (cf. the resource model). In parallel, theGHNContext
monitor events such as the addition or removal of a scope to the gHN (cf.addScope()
,removeScope()
), a restart of the gHN (cf.restart()
), or the shudown of the gHN (cf.shutdown()
). Upon the occurrence of these events, theGHNContext
triggers a transition toStatus.UPDATED
whenever it finds any.
- it maintains and exposes a record of the RIs of the deployed services.
- RIs register their service context with the
GHNContext
as part of their initialisation process (cf.registerService()
and service contexts). Clients can then access the service context of some or of all registered RIs (cf.getServiceContext()
,getServiceContexts()
). One distinguished client in gCF - thehandlers.GCUBEHandler
- relies on this information to block calls made to RIs that are no longer operative or else are not ready to process them yet. Any RI can rely on this functionality to interact with other RIs without having static dependencies on them.
- it notifies interested clients of the occurrence of events that relate to lifetime of the gHN.
- The
GHNContext
models topics with the values of the inner enumerationGHNContext.GHNTopic
(e.g.GHNTopic.RIREGISTRATION
orGHNTopic.SHUTDOWN
) and events with dedicated inner classes (e.g.GHNContext.RIRegistrationEvent
,GHNContext.GHNLifetimeEvent
). To subscribe to one or more of these topics, clients needs to register a concrete implementation of the inner classGHNContext.GHNConsumer
(cf.subscribeGHNEvents()
). Clients subclassGHNContext.GHNConsumer
by implementing all the callbacks that correspond to the events of interest (e.g.GHNContext.GHNConsumer.onRIRegistration()
).
- it mediates between RIs that require service credentials and the local Delegation service that arranges for the periodic renewal of their credentials with remote Security services (cf. security management).
- This is an ad-hoc form of mediation that involves the local RI of the Delegation service. All RIs that require service credentials to operate within a secure infrastructure request them from the
GHNContext
as part of their staging process (cf.subscribeForCredential()
and service contexts). Similarly, the RI of the local Delegation service registers with theGHNContext
to be notified of all such requests (cf.subscribeForCredentialRequest()
). When credentials for a given RI become available to the Delegation service from the infrastructure, the Delegation service passes them to theGHNContext
that notifies the RI.
Status.UPDATED
: this is the transitional state of a gHN that has changed some of its state.
- This is a short-lived state that is used internally to notify subscribed consumers of state changes and to publish within the infrastructure the gHN profile regularly generated in the
Status.RUNNING
state. Upon completion of these activities, the gHN reverts immediately to theGHNStatus.RUNNING
.
Status.HALTED
: this is the state of a gHN that has terminated its execution within the JVM.
- This is a short-lived state in which the
GHNContext
attempts to terminate the JVM in which it is running. This state is triggered internally to the framework at the point of dynamic service deployment.
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.
The gHN configuration exposed by the GHNContext
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 (cf.
getInfrastructure()
,getStartScopes()
,getMode()
,getType()
,getHostame()
,getPort()
, etc.). Others are available via theGCUBEHostingNode
resource maintained by theGHNContext
(cf. getGHN()). Yet other configuration properties can be accessed with the generic facilities inherited fromGCUBEContext
(cf.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 GHNContext
can expose gHN configuration and hardware-related information even when the status of the gHN is Status.DOWN
.
Note: The facilities for file management that GHNContext
inherits from GCUBEContext
(cf. getFile()
) are for internal use and service developers should not use them. Instead, service developers access the file system using dedicated facilities in their service context.
Service Contexts
[coming soon]
PortType Contexts
[coming soon]