Difference between revisions of "IS-Publisher"

Revision as of 23:44, 30 March 2011

In conjunction with the IS-Client and the IS-Notifier, the IS-Publisher represents the mediation layer gCube Services will rely on to interact with the Information Service as a whole.

Design and Goals

The IS-Publisher is a Java library providing a reference implementation for a group of interfaces defined in the gCore Framework. The purpose of these interfaces is to define the behavior of providers of information to the the Information System.

More specifically:

• by implementing the org.gcube.common.core.informationsystem.publisher.ISPublisher interface, the library allows gCube services to publish GCUBEResources and instances' states as of WS-ResourceProperty documents;
• by implementing the org.gcube.common.core.informationsystem.publisher.ISGenericPublisher and org.gcube.common.core.informationsystem.publisher.ISResource interfaces, the library allows to publish XML documents in the IS;
• by implementing the org.gcube.common.core.informationsystem.publisher.ISLocalPublisher interface, it provides a subscription/notification mechanism based on local events.

At runtime, all the above interfaces are dynamically bound by gCore to the implementation provided by the library.

ISPublisher Interface

Managing a GCUBEResource

In order to manage a GCUBEResource profile the IS-Publisher interacts with the IS-Registry service in the publishing scope by invoking its appropriate operations.

Publishing a GCUBEResource

The registerGCUBEResource operation has to be invoked to publish a profile in the IS. The operation takes the following parameters as input:

• the resource to publish, an instance of a sub-class of the GCUBEResource class
• the operational scope, an object representing a scope in the gCube model of VO/VREs
• the security manager, the component keeping track of credentials, and returns a string containing the registered profile if the registration is successful.

Here it is an example of GCUBEGenericResource registration:

try {
	ISPublisher publisher = GHNContext.getImplementation(ISPublisher.class); //dynamically load the reference implementation of the interface
	GCUBEGenericResource resource = GHNContext.getImplementation(GCUBEGenericResource.class);
        //load the resource here
	publisher.registerGCUBEResource(resource, this.scope, ServiceContext.getContext());
} catch (Exception e) {			
	logger.error(e);
	throw new Exception("Unable to register the Resource");
}

Updating a GCUBEResource

The updateGCUBEResource operation has to be invoked to update a profile in the IS. The operation takes the following parameters as input:

• the resource to update, an instance of a sub-class of the GCUBEResource class
• the operational scope, an object representing a scope in the gCube model of VO/VREs
• the security manager, the component keeping track of credentials, and returns a string containing the registered profile if the registration is successful.

Here it is an example of GCUBEGenericResource update:

try {
	ISPublisher publisher = GHNContext.getImplementation(ISPublisher.class); //dynamically load the reference implementation of the interface
	GCUBEGenericResource resource = GHNContext.getImplementation(GCUBEGenericResource.class);
        //load the resource here...
	publisher.updateGCUBEResource(resource, this.scope, ServiceContext.getContext());
} catch (Exception e) {			
	logger.error(e);
	throw new Exception("Unable to register the Resource");
}

Removing a GCUBEResource

The removeGCUBEResource operation has to be invoked to remove a profile from the IS. The operation takes the following parameters as input:

• the resource ID, the unique identifier of the resource to delete
• the resource type, the type of the resource to delete
• the operational scope, an object representing a scope in the gCube model of VO/VREs
• the security manager, the component keeping track of credentials, and returns a string containing the registered profile if the registration is successful.

Here it is an example of GCUBEGenericResource removal:

try {
	ISPublisher publisher = GHNContext.getImplementation(ISPublisher.class); //dynamically load the reference implementation of the interface
	GCUBEGenericResource resource = ....;// the resource could be obtained as a results of a query, loaded from a file/string or passed as input by someone else...
	publisher.removeGCUBEResource(resource.getID(), resource.getType() this.scope, ServiceContext.getContext());
} catch (Exception e) {			
	logger.error(e);
	throw new Exception("Unable to register the Resource");
}

Managing a service's state

Services' states represent a view on the stateful resources data handled by each service. Such a view is then defined in the format of WS-ResourceProperty document.

The IS-Publisher is able to extract the this document from an instance of the GCUBEWSResource state and publish it.

Publishing a service's state

The registerWSResource operation has to be invoked in order to publish the resource's state in the IS. It takes as input the following parameters:

• the stateful resource (each stateful entity different from a gCube Resource)
• the scope
• optionally the registration name

Here it is an example of WSRFREsource registration:

try {
	ISPublisher publisher=GHNContext.getImplementation(ISPublisher.class);
	publisher.registerWSResource(<instance extends GCUBEWSResource>,scope);
} catch(Exception e) {
	logger.error(e);
	logger.warn("could not publish RPS for "+GCUBEWSResource.this.getClass().getSimpleName()+"("+getID()+") in "+scope,e);}		
}

Un-Publishing a service's state

To delete a resource's state from the IS, the removeWSResource has to be invoked. It takes the following paramenters:

• the stateful resource (each stateful entity different from a gCube Resource)
• the scope
• optionally the registration name

The update of the state is automatically performed by the underlying framework as explained in the implementation section.

ISLocalPublisher Interface

The interface provides a subscription/notification mechanism based on local events allowing consumers to be notified about changes in any GCUBEResource published by others within the same GHN. This mechanism is widely exploited by the IS services whenever they are themselves hosted on the local GHN.

Subscribing for local events

The operation subscribeLocalProfileEvents(LocalProfileConsumer consumer) subscribes a new consumer as listener of local event. A consumer is an instance of a class extending the LocalProfileConsumer class also defined in the interface. The following methods of the class can be overridden to receive the appropriate callbacks after a modification on any of the local profiles occurred:

• • onProfileRemoved(String resourceID, String type, GCUBEScope scope) - removed profile event callback
  • onProfileUpdated(GCUBEResource resource, GCUBEScope scope) - updated profile event callback.
  • onProfileRegistered(GCUBEResource resource, GCUBEScope scope) - new registered profile event callback.

• isEnabled(GCUBEScope scope) - it checks if in the given scope, the notification mechanism based on local events is enabled or not.

The following example shows how to register a consumer and be notified for local events occurring in the hosting node:

import org.gcube.common.core.informationsystem.publisher.ISLocalPublisher.LocalProfileConsumer;
 
 
private void subscribeToLocalRegistrationEvents() throws Exception{
	ISLocalPublisher pub = GHNContext.getImplementation(ISLocalPublisher.class);
	LocalProfileConsumer cons = new LocalProfileConsumer() {
 
	        /* (non-Javadoc)
	         * @see org.gcube.common.core.informationsystem.publisher.ISLocalPublisher.LocalProfileConsumer#onProfileRegistered(org.gcube.common.core.resources.GCUBEResource)
	         */
	        @Override
	        protected void onProfileRegistered(GCUBEResource resource, GCUBEScope scope) {
	            logger.debug("onProfileRegistered event received" );                                   
	            //manage the event...
 
	        }
 
	        /* (non-Javadoc)
	         * @see org.gcube.common.core.informationsystem.publisher.ISLocalPublisher.LocalProfileConsumer#onProfileRemoved(java.lang.String, java.lang.String)
	         */
	        @Override
	        protected void onProfileRemoved(String resourceID, String type, GCUBEScope scope) {
	            logger.trace("onProfileRemoved event received");
	            //manage the event...	        		                               
	        }
 
	        /* (non-Javadoc)
	         * @see org.gcube.common.core.informationsystem.publisher.ISLocalPublisher.LocalProfileConsumer#onProfileUpdated(org.gcube.common.core.resources.GCUBEResource)
	         */
	        @Override
	        protected void onProfileUpdated(GCUBEResource resource, GCUBEScope scope) {
	            logger.trace("onProfileUpdated event received");
	            //manage the event...	        		                               
	        }
 
 
	    };
 
    pub.subscribeLocalProfileEvents(cons);
}

On GCUBEResources loading

There are several ways to obtain an object representing a GCUBEResource. However, none of them includes the direct instantiation of a sub-class of GCUBEResource. The examples below refer to the GCUBERunningInstance resource but they can be applied to any other GCUBEResource.

• The resource is serialized in the IS, then returned as a result from a query:

ISClient client = GHNContext.getImplementation(ISClient.class);
GCUBERIQuery query = client.getQuery(GCUBERIQuery.class);
List<GCUBERunningInstance> results = client.execute(query, GCUBEScope.getScope("AScope"));

• The resource is serialized in file:

File fileserialization = new File("..");
GCUBERunningInstance resource = GHNContext.getImplementation(GCUBERunningInstance.class);
resource.load(new FileReader(fileserialization));

• The resource is serialized in a String:

String xmlserialization = "...";
GCUBERunningInstance resource = GHNContext.getImplementation(GCUBERunningInstance.class);
resource.load(new StringReader(xmlserialization));

• The resource is created from scratch:

GCUBERunningInstance resource = GHNContext.getImplementation(GCUBERunningInstance.class);
//invoke setters on the resource here...