Advanced Topics
Contents
Interfacing the Information System
The gCore Frameork has been designed to work independently from a IS specific Implementation. In order to let the gCF unbound from a IS implementation both query & publishing interfaces have been designed. The gCF implements than a dynamic class loader that ( reading a implementation file that contains the mapping btw the IS interfaces and their implementations) can abstract over the IS technology.
ISQuery interface
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient. The query contains the textual query expression and specify a time-to-live for their results (that can be exploited by future caching mechianism) The definition is parametric with respect the type of the exptected results. This is not required for the interface, though it may for its implementations; in addition , it allows full typing of the ISClients interface.
public interface ISQuery<RESULT> {
/**
* Returns the time-to-live of the results of the query.
* @return the time-to-live.
*/
public long getTTL();
/**
* Sets the time-to-live of the results of the query.
* @param ttl the time-to-live.
*/
public void setTTL(long ttl);
/**
* Returns the textual expression of the query.
* @return the expression.
*/
public String getQueryExpression();
/**
* Sets the textual expression of the query.
* @param exp the expression.
*/
public void setQueryExpression(String exp);
}
ISClient interface
The IS Client interface defines only two methods:
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws ISMalformedQueryException,ISInvalidQueryException,ISException;
The execute method takes as parameter:
- the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);
- a GCUBEScope object that specifies the query scope;
- The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);
The return type is a List object specified as Type parameter in the related ISquery object.
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:
ISClient client = GHNContext.getImplementation(ISClient.class);
The IS Client Interface predefines a list of abstract queries that model the most common useful queries used by the gCF.
In particular we have general queries over GCUBEResources:
- GCUBEResourceEntriesQuery
- GCUBEResourceFromIDQuery
- GCUBEResourceIDQuery
- GCUBEResourceXPathQuery
- GCUBERIsFromClassAndName
- GCUBERIsOnGHNQuery
- GCUBERISpecificData
- GCUBEAllResourceIDQuery
- GCUBEGHNIDFromHostNameQuery
- GCUBEEntriesFromGHNIDQuery
Queries over GCUBECollection:
- GCUBEAllInternalCollectionEntriesQuery:
- GCUBEAllInternalCollectionIDsQuery
- GCUBECollectionIDFromSchemaQuery
Queries over GCUBEMCollection:
- GCUBEMCollectionFormatsRelatedToCollectionQuery
- GCUBEMCollectionIDsFromMetaFormatLanguageQuery
- GCUBEMCollectionIDsFromMetaFormatNameQuery
- GCUBEMCollectionIDsFromNameQuery
- GCUBEMCollectionIDsFromSchemaQuery
- GCUBEMCollectionIDsRelatedToCollectionAndRoleQuery
- GCUBEMCollectionIDsRelatedToCollectionQuery
Queries over GCUBEWSResources:
- GCUBEWSResourceEPRFromRPNamesAndNamespaceQuery
- GCUBEWSResourceEPRFromRPNamesQuery
- GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery
- GCUBEWSResourceEPRFromRPValuesQuery
- GCUBEWSResourceHeaderQuery
- GCUBEWSResourceRPEntriesFromEPRQuery
- GCUBEWSResourceRPValueFromEPRQuery
- GCUBEWSResourceXPathQuery
- GCUBEAllWSResourcesQuery
And a GenericQuery Object that can be used to query the IS without using predefined queries.
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;
i.e.
GCUBERIsFromClassAndName queryRI = client.getQuery(GCUBERIsFromClassAndName.class);
Sample usage
The ISclient reference implementaiton makes use of Xquery Technology to query over the underneath Exist database. Client/services can prepare a custom xQuery over the DB and use the Generic Query object to exceute it:
GenericQuery query = client.getQuery(GenericQuery.class);
query.setQueryExpression("for $Profile in
collection(\"/db/Profiles\")//Document/Data/child::*[local-name()='Profile']/Resource return $Profile/UniqueID");
List<String> result =client.execute(query, scope);
for (String resultItem :result ) {
System.out.println(resultItem);
}
You can use a predefined ISQuery Object as well:
GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery query = client.getQuery(GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery.class);
GCUBEWSProperty property = new GCUBEWSProperty("IndexTypeName","index_type_string_string");
GCUBEWSProperty property2 = new GCUBEWSProperty("IndexID","999ba610-e9fb-11dc-b51b-84732c1e88f2");
ArrayList <GCUBEWSProperty> properties = new ArrayList();
properties.add(property);
properties.add(property2);
query.setPropertiesValuesAndNamespace(properties, "http://gcube-system.org/namespaces/index/ForwardIndexManagementService");
List<EndpointReferenceType> result = client.execute(query, scope);
for (EndpointReferenceType resultItem :result ) {
System.out.println(resultItem.toString());
}
--Andrea.manzi 17:09, 31 March 2008 (EEST)
ISPublisher interface
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:
- GCUBEResources
- GCUBEWSResources
- Topics
In particular GCUBEResources profiles are modeled as java classes inside the framework:
- GCUBEService
- GCUBERunningInstance
- GCUBEHostingNode
- GCUBECS
- GCUBECSInstance
- GCUBECollection
- GCUBEMCollection
- GCUBEVRE
- GCUBETransformationProgram
- GCUBEExternalRunningInstance
- GCUBEGenericRescource
gCUBE Client/Services can explout the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:
/** * Register a GCUBEResource on the Information System * * @param resource The Gcube Resource to register * @param scope the Gcube scope to use * @return the Registered GCUBEResource profile * @throws ISPublisherException Exception */ public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws GCUBEPublisherException; /** * Remove a GCUBEResource from the Information System * * @param ID the ID related to the Gcube Resource to remove * @param the GCUBEResource type to remove * @param scope the registration scope * @param manager a GCUBESecurityManager * @throws ISPublisherException Exception */ public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException; /** * Update a GCUBEResource in the Information System * @param resource The new Gcube Resource to update * @param manager a GCUBESecurityManager * @throws ISPublisherException Exception */ public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS ( the publication mechanism is completely
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:
/** * Enables WS-resource registration on a Information System * * @param resource The Gcube WSResouce to register * @param scope optional scope (overrides the scope specified by the GCUBEWSResource) * @throws ISPublisherException Exception */ public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException; /** * Enables WS-resource registration on a Information System( named Registration) * * @param resource The Gcube WSResouce to register * @param name the name associated to the registration * @param scope optional scope (overrides the scope specified by the GCUBEWSResource) * @throws ISPublisherException Exception */ public void registerWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException; /** * Removes the registration of a GCube WS-Resource from the InformationSystem * * @param resource The Gcube WSResouce to unregister * @param scope optional scope (overrides the scope specified by the GCUBEWSResource) * @throws ISPublisherException Exception */ public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException; /** * Removes he registration of a GCube WS-Resource from the InformationSystem( named registration) * * @param resource The Gcube WSResouce to unregister * @param name the name associated to the registration * @param scope optional scope (overrides the scope specified by the GCUBEWSResource) * @throws ISPublisherException Exception */ public void removeWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;
Topics publishers can use the IS-Publihser interface, to let their topics being published on the IS and subscribed for notification to.
/** * Register the given topics belonging to the given source EPR as a Notification Producer inside the IS Notification * * @param sourceEpr The notification producer EPR * @param topicsList The list of topic to register * @param scope the Scope of the caller * @param manager GCUBESecurityManager manager * @throws ISPublisherException Exception */ public void registerToISNotification(EndpointReferenceType sourceEpr, ArrayList<QName> topicsList,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException; /** * Unregister the given topics belonging to the given source EPR from the IS Notification * * @param sourceEpr the notification producer EPR * @param topicsList The list of topic to unregister * @param scope the Scope of the caller * @param manager GCUBESecurityManager manager * @throws ISPublisherException Exception */ public void unregisterFromISNotification(EndpointReferenceType sourceEpr, ArrayList<QName> topicsList,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException ;
The ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to prepare the IS Services stubs with the correct Scope and security Settings.
Sample usage
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the getImplementation method:
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:
FileReader fis = new FileReader (args[0]);
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);
resource.load(fis);
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);
managerSec.useCredentials(cred);
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);
Service security
Configuring gContainer with Security
Configuring gCube Service with Credentials
--Manuele.simi 20:11, 28 March 2008 (EET)
