Difference between revisions of "Programmatic Administration Interface"

Revision as of 04:32, 21 July 2010

Introduction

This section describes the programming interfaces that allow to configure, manage and control nodes, services, applications and resources in a gCube infrastructure. As the gCube technology is deployed as a distributed system, there exist several APIs to manage the different areas of the system. This section is a single point of reference for all these APIs by grouping them for their logical purpose.

This section includes the following topics:

For each of them, a detailed explanation is provided about which component(s) must be contacted for doing what and which are the scope constraints (if any).

Managing a gCube Hosting Node (gHN)

Shut down

Target: Shut down the node

Component(s) to contact:

• Name: gHNManager

• Where: the Running Instance on the gHN

• How to find it: query on the IS that looks for a RI of the gHNManager running on the gHN

• Operation to invoke: shutdown

• Parameters: setClean=false, setRestart=false

Restart

Target: Restart the node and preserve its state

Component(s) to contact:

• Name: gHNManager

• Where: the Running Instance on the gHN

• How to find it: query on the IS that looks for a RI of the gHNManager running on the gHN

• Operation to invoke: shutdown

• Parameters: setClean=false, setRestart=true

Restart and Clean

Target: Restart the node and clean its actual state

Component(s) to contact:

• Name: gHNManager

• Where: the Running Instance on the gHN

• How to find it: query on the IS that looks for a RI of the gHNManager running on the gHN

• Operation to invoke: shutdown

• Parameters: setClean=true, setRestart=true

Add an existing Scope

Target: Add a scope to a gHN and the related Service Map is already available on the gHN

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope to add

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: addResources

• Parameters: setID=<GHN ID>, setType=GHN, setTargetScope=<new Scope>

Add a new Scope

Target: Add a scope to a gHN and the related Service Map is not available on the gHN

Component(s) to contact:

• Name: gHNManager (in case of VO scope)

• Where: the Running Instance on the gHN

• How to find it: query on the IS that looks for a RI of the gHNManager running on the gHN

• Operation to invoke: addScope

• Parameters: setScope=<new Scope>, setMap=<string serialization of the Map>

• Name: Resource Manager

• Where: the Running Instance managing the Scope to add

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: addResources

• Parameters: setID=<GHN ID>, setType=GHN, setTargetScope=<new Scope>

Remove from a Scope

Target: Remove a gHN from a scope

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope to remove

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: removeResources

• Parameters: setID=<GHN ID>, setType=GHN, setTargetScope=<Scope to remove>

Managing a Running Instance (RI)

Join a Scope

Target: Join a Running Instance to a scope

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope to join

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: addResources

• Parameters: setID=<RI ID>, setType=RunningInstance, setTargetScope=<Scope to Join>

Remove from a Scope

Target: Remove a Running Instance from a scope

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope to remove

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: removeResources

• Parameters: setID=<RI ID>, setType=RunningInstance, setTargetScope=<Scope to remove>

• Note: if the Running Instance is joined only to this scope, it is also undeployed

Deploy

Target: Deploy a new Running Instance in a Scope

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: addResources

• Parameters: ServiceItem.setServiceClass=<Service Class>, ServiceItem.setServiceName=<Service Name>, ServiceItem.setServiceVersion=<Service Version>, ServiceItem.setGHN=<GHN ID where to deploy> (optional, suggested gHN to use), setTargetScope=<Scope to deploy in>, ServiceList.setGHN=new String[] {"GHNID1","GHNID2","GHNID3","GHNID4","GHNID5"} (optional, suggested gHNs to use)

Undeploy

Target: Force the undeployment of a Running Instance from all the scopes it is joined; for a gentler undeploy, see here

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope to remove or (if this not work) try all the other scopes to which the RI is joined

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: removeResources

• Parameters: ServiceItem.setServiceClass=<Service Class of the RI>, ServiceItem.setServiceName=<Service Name of the RI>, ServiceItem.setServiceVersion=<Service Version of the RI>, setTargetScope=<Scope to undeploy from>

Adding a gCube Resource (different from gHN and RI) to a Scope

Add a gCube Resource to a Scope from the Parent Scope

Target: Add a gCube Resource to (i) a VRE scope from the parent VO or (ii) a VO scope from the infrastructure scope. If the resource is not in the parent scope, it must be registered in that scope before to be added to any scope.

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope to add

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: addResources

• Parameters: setID=<Resouurce ID>, setType=<Resource Type>, setTargetScope=<Scope to add>

Add a gCube Resource from a VO to another VO

Target: Copy a gCube Resource from a VO to another VO

Component(s) to contact:

• Name: IS-Client

• Where: in the local instance of gCore

• How to find it: on the classpath

• Operation to invoke: execute

• Parameters: query=GCUBEResourceQuery(with an appropriate QueryParameter condition on the resource ID), GCUBEScope=<original VO>,

• Name: IS-Publisher

• Where: in the local instance of gCore

• How to find it: on the classpath

• Operation to invoke: registerGCUBEResource. Before to register the resource, the scope must be added to the local GCUBEResource object by invoking the method GCUBEResource.addScope(<new scope>)

• Parameters: GCUBEResource=<resource object obtained from the IS-Client>, GCUBEScope=<destination VO>, GCUBESecurityManager=ServiceContext.getContext()||<dummy manager>

Create a new gCube Resource

Target: Register a gCube Resource to (i) the infrastructure scope or (ii) a VO scope from scratch (e.g. the resource does not exist in any other scopes).

Component(s) to contact:

• Name: IS-Publisher

• Where: in the local instance of gCore

• How to find it: on the classpath

• Operation to invoke: registerGCUBEResource. Before to register the resource, the scope must be added to the local GCUBEResource object by invoking the method GCUBEResource.addScope(<new scope>)

• Parameters: GCUBEResource=<resource profile>, GCUBEScope=<new Scope>, GCUBESecurityManager=ServiceContext.getContext()||<dummy manager>

Removing a gCube Resource (different from gHN and RI) from a Scope

Remove from a Scope

Target: Remove a gCube Resource from a scope

Scope constraint: if the resource joins only the current scope, after the removal it has also to be deleted

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope to remove

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: removeResources

• Parameters: setID=<Resouurce ID>, setType=<Resource Type>, setTargetScope=<Scope to remove>

Note: after the removal, the resource must be also updated in the other scopes it belongs to, otherwise it will wrongly report there a scope where actually it is not registered anymore. In order to do so, the just removed scope must be removed from the local GCUBEResource object by invoking the method GCUBEResource.removeScope(<scope to remove>) and then the resource must be updated in all the remaining scopes.

Deleting a gCube Resource

Delete a Resource from a Scope

Target: delete a resource from a scope

Scope constraint: a resource can be deleted if and only if it joins only the current scope. If the resource joins other scopes, it has to be only removed from the the current scope, but not deleted.

Component(s) to contact:

• Name: IS-Publisher

• Where: in the local instance of gCore

• How to find it: on the classpath

• Operation to invoke: removeGCUBEResource. However, before to invoke this method, the resource must be removed from the the scope.

• Parameters: GCUBEResource=<resource ID>, Type=<resource type>, GCUBEScope=<Scope to remove from>, GCUBESecurityManager=ServiceContext.getContext()||<dummy manager>

Delete from the Infrastructure

Target: Delete a Resource from the infrastructure.

The resource must be

• firstly removed from the VOs it belongs to
• then removed from the Infrastructure Scope if it is also registered there.
• finally, it can be deleted from all its scopes

Exceptions

There exist exceptions to the standard way for deleting gCube Resources (in addition to Running Instances and gHNs).

Deleting a Scope Resource

Target: delete a Generic Resource modeling a Scope on the Information System. The only way is to dispose the modelled Scope.

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: disposeScope

• Parameters: DisposeScopeParameters.name=<Scope to dispose>

Deleting a Collection

To be completed

Deleting a Metadata Collection

To be completed

Editing a gCube Generic Resource

Standard Way

Target: edit a Generic Resource on the Information System.

Component(s) to contact:

• Name: IS-Publisher

• Where: in the local instance of gCore

• How to find it: on the classpath

• Operation to invoke: updateGCUBEResource

• Parameters: GCUBEResource=<resource>, GCUBEScope=<Scope>, GCUBESecurityManager=ServiceContext.getContext()||<dummy manager>

Exceptions

There exist exceptions to the standard way for editing Generic Resources. These are mostly related to resources automatically generated by gCube Services that must be in turn contacted for the editing operation.

Scope Resources

Target: edit a Generic Resource modeling a Scope on the Information System.

Component(s) to contact:

• Name: Resource Manager

• Where: the Running Instance managing the Scope

• How to find it: query on the IS that looks for a RI of the Resource Manager in the new scope or query on the IS that looks for the Generic Resource modeling the scope (the condition is /Resource/Profile/Body/Scope/text()=Scope Expression, then extract the service URI from /Resource/Profile/Body/Service/text()

• Operation to invoke: changeScopeOptions

• Parameters: ScopeOption.name=<option name>, ScopeOption.value=<option value>

Banning a gCube Resource

To be completed