Migration Guidelines from 0.4.4 to 0.5

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

Changes Related to Configuration and Use of the gHN

• package change in ResultSet components

The inclusion of the ResultSet service and related components in gCore has coincided with a refactorisation of their package structure. In particular, fully qualified names that begun with org.gcube.searchservice begin now with org.gcube.common.searchservice.

• new log files and log file location.

All gCore logs are now located in $GLOBUS_LOCATION/logs, while nohup.out remains in $GLOBUS_LOCATION (now regardless of where the $GLOBUS_LOCATION/bin/gcore-start-container is run from). The gHN's logs remains the same (container.fulllog, container.log), but the local services have dedicated log files (ghnmanager.log,deployer.log, delegation.log, rs.log). Globus logs are now collected in a separate log file globus.log and do not propagate to the contatainer's log files (default log level for globus is WARN). Developers are recommended to configure service-specific logs during development. For this purpose, the configuration for local services in $GLOBUS_LOCATION/container-log4j.properties can be used as templates.

• new lower bound on memory requirement for gHNs.

The gHN now requires the allocation of 1GB of heap space to the JVM in which it runs. This is a production-level requirement and can be disabled or corrected during development by editing the script $GLOBUS_LOCATION/bin/gcore-start-container (START_OPTIONS variable).

• new gHN configuration file for offline use.

gCore ships with a clone of $GLOBUS_LOCATION/config/GHNConfig.xml called $GLOBUS_LOCATION/config/GHNConfig.client.xml. The latter can diverge arbitrarily from the former so as to decouple offline and online use of the gHN.

• (optional) configuration of free port range for the gHN.

Administrators and developers can now specify a portRange environment in $GLOBUS_LOCATION/configs/GHNConfig.xml' (or $GLOBUS_LOCATION/configs/GHNConfig.client.xml if useful). The value of the environment can be specified as in the following example:

<environment  name="portRange" value="60000-61000"  type="java.lang.String" />

Do note the following:

• The configuration does not imply that the ports are actually 'open', only that they can be bound.
• The gHN management interface (see below) depends on the existence of this configuration.
• The first free port in this range can be obtained by invoking the method getFreePort() om the GHNContext. See the Javadoc documentation for details of the signature.

• (optional) use of the JMX management interface.

The gHN now binds a JMX managemenet interface to the port that it finds free in the configured range (see above). The bound port is shown in the gHN logs:

...GHNContext: INITIALISED MANAGEMENT INTERFACE AT service:jmx:rmi:///jndi/rmi://localhost:60000

The interface can then be used with jconsole, a graphical JMX client that ships with the JDK:

jconsole localhost:60000

gHN-specific and RI-specific information and operations can be found in the MBeans tabbed pane under org.gcube. In the same tabbed pane, logger and appender information and operations can be found under log4j.

Changes Related to the Implementation of Services

• org.gcube.common.core.resources.GCUBETransformationProgram and org.gcube.common.core.resources.GCUBEVRE are no longer available.

These types were not in use as the corresponding resources are modelled with org.gcube.common.core.resources.GCUBEGenericResource.

• the methods org.gcube.common.core.state.GCUBEStatefulResource.isRemoved() and org.gcube.common.core.state.GCUBEStatefulResource.remove() are no longer available.

isRemoved() was intended primarily for internal usage and has been made redundant by the new locking mechanism, which should now be used by developers. remove() was thread-unsafe as all removal operations should pass for the method org.gcube.common.core.state.GCUBEResourceHome.remove().

• the method org.gcube.common.core.state.GCUBEStatefulResource.getPersistenceDelegate() is now deprecated and will be removed in the next minor/major release.

Exposing persistence delegates is no longer necessary and in fact dangerous. Resource load must be handled transparently by the home associated with the resource, and resource storage can be triggered by invoking directly the method org.gcube.common.core.state.GCUBEStatefulResource.store().

• the method org.gcube.common.core.utils.events.GCUBEProducer.registerTopics() was already deprecated and is now no longer available.

The registration of topics is now performed implicitly at the notification of the first event in a given topic.

• the method org.gcube.common.core.context.GCUBEServiceContext.getConfigFile() is now deprecated and will be removed in the next minor/major release.

The method is replaced by org.gcube.common.core.context.GCUBEServiceContext.getFile(). See below for furter information.

• the methods registerToISNotification(), unregisterFromISNotification(), registerISNotification(), and unregisterISNotification() of the org.gcube.common.core.informationsystem.notifier.ISNotifier interface have new and non retro-compatible signatures.

The methods have lost the parameter consumerEPR because it proved superfluous and have generalised the type of the manager parameter from a org.gcube.common.core.contexts.GCUBEServiceContext to a org.gcube.common.core.security.GCUBESecurityManager.

• org.gcube.common.core.porttypes.GCUBEStartupPortType is now deprecated and will be removed in the next minor/major release.

Derive now all port-type implementations from org.gcube.common.core.porttypes.GCUBEPortType, regardless of the value set in their deployment descriptors for loadOnStartup. Do note that:

• The requirement that loadOnStartup be set to true for at least one port-type implementation does remain.
• The requirements to derive GCUBEPortType are the same requirements to derive GCUBEStartupPortType (i.e. implement the method getServiceContext()).

Note also that GCUBEStartupPortType is recast as a subclass of GCUBEPortType for this release only. See also the Primer for more information on this requirement.

• New port-type and home callbacks on RI lifetime.

org.gcube.common.core.porttypes.GCUBEPortType defines callbacks for all the states of RI lifetime: onInitialisation(), onInitialisation()onReady()</code, onFailure(), onUpdate(),onStateChange(). The same callbacks are now also defined for org.gcube.common.core.state.GCUBEResourceHome.remove(). See the Developer's Guide for specific information on the lifetime of the RI.

• New file management methods on service contexts.

Service contexts offer two methods to write and read files from the file system: getFile() and getPersistentFile(). The usage model and difference between the two methods are described in detail in the Developer's Guide, first here and then here . Do notice that, changes to persistent files must be explicitly notified to the persistence manager (see below), if one is configured for the service.

• (Optional) configuration of remote backup/recovery.

Services that wish to take advantage of the new facility for remote backup and recovery can do so by adding the a persistenceManagerProfile resource to their deploy-jndi-xml, as follows:

<resource name="persistenceManagerProfile" type="org.gcube.common.core.persistence.GCUBERIPersistenceManagerProfile">
   <resourceParams>	
	<parameter><name>factory</name><value>org.globus.wsrf.jndi.BeanFactory</value></parameter>	
	<parameter><name>className</name><value>org.gcube.common.smspersistence.GCUBESMSPersistenceManager</value>
         </parameter><parameter><name>monitoringInterval</name><value>...value in seconds...</value></parameter>               
    </resourceParams>
</resource>

Do note the following:

• className specifies the class of the only SMS-based persistence manager that ships with gCore
• monitoringInterval measures in seconds how often the persistent manager will backup the RI state, if and only if this has changed since the last backup.
• changes to persisted WS-Resources are automatically detected by the persistence manager. Changes to other files below the storage root of the service must be explicitly flagged by invoking the method org.gcube.common.core.context.GCUBEServiceContext.notifyStateChange().

See also the release notes for an overview of remote persistence.

• New org.gcube.common.core.informationsystem.client.ISClient interface.

The ISClient interface now allows clients to execute query by reference. See the Primer for examples on usage.

• New org.gcube.common.core.informationsystem.notifier.ISNotifier interface.

The ISNotifier interface now allows client to enquire for the successful registration of a topic. See the Primer for examples on usage.

• New persistence modes for org.gcube.common.core.state.GCUBEResourceHome.

Resource homes can now be configured to support additional modes of persistence. See the Primer for an explanation of the available modes and configuration details.

• New locking mechanism for resources.

org.gcube.common.core.state.GCUBEStatefulResource now defines a method getLock() that returns a new org.gcube.common.core.state.GCUBEReadWriteLock that can be used by cooperating threads (including gCF's of course) to synchronise their access to the resource. GCUBEReadWriteLock is an extension of Java's ReadWriteLock which supports pre-emptive write locks (if one thread succeeds the others waiting for the lock are interrupted). This should be of limited interest to the vast majority of developers as the pre-emptive behaviour is used transparently by gCF on removal operations. Do use GCUBEReadWriteLock as a standard read-write lock otherwise.

• New interface for sychronous consumers.

The tagging interface org.gcube.common.core.utils.events.GCUBESynchronousConsumer is now available for consumers that wish producers to block in their delivery of events.

• New high-level call abstractions.

The new package org.gcube.common.core.utils.calls groups partial implementations of high-level call objects. A high-level call encapsulates standard the interaction with the standard stub objects of a target port-type to: a) simplify the interaction (convenient scope and security settings); b) improve its resilience (transparent and easily customisable best-effort strategies), and c) reduce client dependencies (hidden naming and endpoint constants). Depending on the characteristics of the target port-type, developers can extend RICall, StagingCall, and WSCall to provide these facilities to their clients, ideally as a complement to their plain stub distribution. Information on the logic and requirement for specialisation can be found in the Javadoc documentation.

Changes Related to the Resource Profiles

• New version attribute in the root element of all profiles.

Starting from this release, a new version attribute identifies the XML Schema to which a profile is an instance of. This allows the management tools to immediately recognize the profiles produced by different releases of gCore. In gCore 0.5 only the gHN profile reports version="0.5.x", since it is the only one changed.

• New elements in the gHN profile.

The following new optional elements are now published in the gHN profile:

 <xs:element name="ActivationTime" type="xs:dateTime" minOccurs="0"/>
 <xs:element name="Status" type="xs:string" minOccurs="0"/>
 <xs:element name="StatusMessage" type="xs:string" minOccurs="0"/>

Note: As a consequence of the changes, the gHN Profiles produced by gCore 0.5 won't be read by previous versions, while the old ones will be still accepted by gCore 0.5 and validated by the infrastructure.