Migration Guidelines from 0.5.1 to 0.6

gCore 0.6 requires or supports the following changes to practices and service implementations that are compliant with gCore 0.5.1 (non retro-compatible changes are typeset in bold):

Changes Related to Configuration and Use of the gHN

• debugging and profiling launch scripts.

The are two new scripts in $GLOBUS_LOCATION/bin, gcore-start-container-debug and gcore-start-container-profile, to start the gHN in debugging and profiling mode, respectively. See the Primer for detailed usage instructions.

Changes Related to the Implementation of Services

• New interfaces for resource publication.

The interface ISPublisher in org.gcube.common.core.informationsystem.publisher is now extended by ISSyncPublisher and ISASyncPublisher interfaces, in the same package. These are tagging interfaces that implicitly impose synchronous and asynchronous behaviour on their implementations, respectively. The default implementation of ISPublisher is the default implementation of ISAsyncPublisher. This means that existing code retains its current semantics. Interface implementations are obtained though standard means:

ISSyncPublisher sp = GHNContext.getImplementation(ISSyncPublisher.class); //obtains a publisher for synchronous publication
ISASyncPublisher ap = GHNContext.getImplementation(ISASyncPublisher.class); //obtains a publisher for asynchronous publication
ISPublisher p = GHNContext.getImplementation(ISPublisher.class); //also obtains a publisher for asynchronous publication

• org.gcube.common.core.state.GCUBEWSResource has a new method getPublisher() that returns the implementation of ISPublisher used for the publication of WS-Resources. The method returns the default implementation of ISPublisher, which is an asynchronous publisher (see above). Developers can override it to return the implementations of specific publishers, as shown below:

/**{@inheritDoc}*/
 protected ISPublisher getPublisher() throws Exception {
    return GHNContext.getImplementation(ISSyncPublisher.class); //forces a synchronous publisher
}

• New plugin management facilities.

org.gcube.common.core.plugins includes programming abstractions for the design of pluggable services, most noticeably:

• GCUBEPluginManager, a partial implementation of service components dedicated to the overall management of service plugins. GCUBEPluginManager predefines behaviour to register and unregister plugins, to validate their contents against general and service-specific requirements, to notify other components of registration and unregistration events, to persist plugin profiles so as to automatically re-register them after container restarts, and to store and expose registered plugins within service implementations. Developers specialise GCUBEPluginManager to link its facilities to their services and to add validation checks that reflect specific service expectations. See the API documentation for further details.

• GCUBEPluginContext, a partial implementation of plugin components that act as entry points to the functionality and information in the plugin. GCUBEPluginContext predefines behaviour to expose the profile of the plugin, its descriptive properties, and the type mappings required by the plugin, if any. Service developers specialise GCUBEPluginContext to link its facilities to their service plugins, to pre-define descriptive properties common to all their plugins, and to add any other property or method that they require from the plugins (typically to identify implementations of service interfaces upon which the service needs to act). Plugin developers then further derive this classes to comply with service requirements and include them in the plugins. See the API documentation for further details.

Plugin managers are identified in the JNDI configuration of the service as exemplified below:

<resource name="pluginManagerProfile" type="org.gcube.common.core.plugins.GCUBEPluginManagerProfile">
   <resourceParams>	
             <parameter><name>factory</name><value>org.globus.wsrf.jndi.BeanFactory</value></parameter>	
            <parameter>
                   <name>className</name>
                   <value>org.acme.myservice.MyPluginManager</value>
             </parameter>                   
   </resourceParams>
</resource>

based on this configuration, gCF will instantiate the plugin manager at service startup. Thereafter, the Deployer will interface them transparently to register service plugins that are available within the infrastructure. The registered plugins are also published in a distinguished section of the profile of the Running Instance (cf. runninginstance.xsd in $GLOBUS_LOCATION/share/schema/gcube/common/core/profiles).

• New handler facilities.

The package org.gcube.commo.core.utils.handlers has undergone a number of retro-compatible changes, inlcuding:

• GCUBEIHandler is a new interface that characterises the behaviour of all handlers. This allows clients to extend the interface to enforce stronger expectations on handler implementations. GCUBEHandler implements the interface and remains the base implementation of all pre-defined handlers.

• org.gcube.commo.core.utils.handlers.lifetime includes classes and interfaces for handlers that wish to perform state management. See the developer's guide for details. All pre-defined handlers now perform state management.

• org.gcube.commo.core.utils.handlers.events includes classes and interfaces for handlers that wish to perform event management. See the developer's guide for details. All pre-defined handlers now perform event management.

• the method org.gcube.common.core.contexts.GHNContext.getHostName() no longer throws a java.utils.IOException.

• the class GCUBEScheduledHandler in org.gcube.common.core.utils.handlers has changed its parametrisation.

The old parametrisation was:

public GCUBEScheduledHandler extends GCUBEHandler<GCUBEHandler<?>>

it is now:

public class GCUBEScheduledHandler<HANDLED> extends GCUBEHandler<HANDLED> ...

Accordingly, a GCUBEScheduledHandlerhandles arbitrary objects rather than the handlers it schedules. The change allows clients to process scheduled handlers as any other handler. The implication is that the methods setHandled() and getHandled() no longer set and return the scheduled handler. The new methods setScheduled() and getScheduled() can be instead used for this purpose. See the API documentation for further details.

• The classes GCUBESimpleServiceSecurityManager and GCUBEServiceSecurityManagerImpl are no longer part of gCF in package org.gcube.common.core.security.

The interfaces that they implement remain there, but the classes themselves have been moved to a local library and can be found in package org.gcube.common.vomanagement.security. Services that explicitly configured a security manager must update their JNDI configuration files. Those who relied implicitly on a SimpleServiceSecurityManager need no change.

Changes Related to the Resource Profiles

• New schema for service profiles.

Service profiles can now describe plugins, though the changes require no change to existing profiles. Developers that use schema validators will find an updated service.xsd schema in $GLOBUS_LOCATION/share/schema/gcube/common/core/profiles.

• New schema for running instance profiles.

Running instance profiles now include a section that reports on the plugins registered on the instance. Developers can find schema documentation for the new section in runninginstance.xsd under $GLOBUS_LOCATION/share/schema/gcube/common/core/profiles.