View source for Programmatic Administration Interface


== Introduction ==

{| align="right" style="color:red; border:1px solid #aaa; background-color: #f9f9f9; padding: 5px; font-size: 95%;" cellspacing="0"
|+  <b>Section contents</b>
|- 
|[[Programmatic_Administration_Interface#Managing_a_gCube_Hosting_Node_(gHN) |Managing a gCube Hosting Node (gHN)]]
|- 
|[[Programmatic_Administration_Interface#Managing_a_Running_Instance_(RI) |Managing a Running Instance (RI)]]
|- 
|[[Programmatic_Administration_Interface#Adding_/_Removing_a_Scope_to_a_gCube_Resource_(different_from_gHN_and_RI)|Adding / Removing a Scope to a gCube Resource <br>(different from gHN and RI)]]
|- 
|[[Programmatic_Administration_Interface#Registering_/_Unregistering_a_gCube_Resource_in_a_VO|Registering / Unregistering a gCube Resource in a VO]]
|- 
|[[Programmatic_Administration_Interface#Editing_a_gCube_Resource |Editing a gCube Resource]] 
|- 
|[[Programmatic_Administration_Interface#Banning_a_gCube_Resource|Banning a gCube Resource]] 
|}

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:

{|class="wikitable" style="text-align: rigth; width: 1000px; border-collapse: separate; border-spacing: 0px; border-width: 1px; border-style: solid; border-color: #000;" cellpadding="4" cellspacing="0" 
|-
| style="border-style: solid; border-width: 0 1px 1px 0"| [[Programmatic_Administration_Interface#Managing_a_gCube_Hosting_Node_(gHN) |Managing a gCube Hosting Node (gHN)]] || style="border-style: solid; border-width: 0 0 1px 0"| Describes operations related to manage a node of the infrastructure: how to shut it down or restart it (with and without deleting its state), how to add a new scope and remove an existing scope. 
|-
| style="border-style: solid; border-width: 0 1px 1px 0"| [[Programmatic_Administration_Interface#Managing_a_Running_Instance_(RI) |Managing a Running Instance (RI)]] || style="border-style: solid; border-width: 0 0 1px 0"| Describes operation related to running instance management: how to add a new scope and remove an existing scope, how to deploy and undeploy them
|-
| style="border-style: solid; border-width: 0 1px 1px 0"| [[Programmatic_Administration_Interface#Adding_/_Removing_a_Scope_to_a_gCube_Resource_(different_from_gHN_and_RI)|Adding / Removing a Scope to a gCube Resource <br>(different from gHN and RI)]] ||  style="border-style: solid; border-width: 0 0 1px 0"| Describes how to add and delete scopes to gCube Resources that are not nodes or service's instances. These operations can be performed only from a parent scope to a child scope, e.g. with them it is not possible to add a VO scope if a resource is registered only in another VO (see the next topic for this).
|-
| style="border-style: solid; border-width: 0 1px 1px 0"| [[Programmatic_Administration_Interface#Registering_/_Unregistering_a_gCube_Resource_in_a_VO|Registering / Unregistering a gCube Resource in a VO]] || style="border-style: solid; border-width: 0 0 1px 0" | Describes how to register and unregister gCube Resources in the context of a Virtual Organization. 
|-
| style="border-style: solid; border-width: 0 1px 1px 0"| [[Programmatic_Administration_Interface#Editing_a_gCube_Resource |Editing a gCube Resource]] || style="border-style: solid; border-width: 0 0 1px 0"| Describes how to change the representation of gCube Resources in the Information System. Depending on the resource type, different components have to be contacted for this.
|-
| style="border-style: solid; border-width: 0 1px 0 0"| [[Programmatic_Administration_Interface#Banning_a_gCube_Resource|Banning a gCube Resource]] ||  style="border-style: solid; border-width: 0 0 0 0"| Describes how to instruct the Information System to exclude certain gCube resource from a given scope. This operation is available for VO-Managers and makes sense especially for nodes and running instances, when the decision to join or not a scope is partially under the control of Site Managers.
|}


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

== Managing a gCube Hosting Node (gHN) ==

=== Shut down ===

'''Target''': Shut down the node

'''Component(s) to contact''':

* '''Name''':  [[GHN_Manager|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''': [[GHN_Manager#Requesting_the_gHN_shutdown|shutdown]]

:* '''Parameters''': <code>setClean=false</code>, <code>setRestart=false</code>


=== Restart ===

'''Target''': Restart the node and preserve its state

'''Component(s) to contact''':

* '''Name''':  [[GHN_Manager|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''': [[GHN_Manager#Requesting_the_gHN_restart|shutdown]]

:* '''Parameters''': <code>setClean=false</code>, <code>setRestart=true</code>


=== Restart and Clean ===

'''Target''': Restart the node and clean its actual state

'''Component(s) to contact''':

* '''Name''':  [[GHN_Manager|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''': [[GHN_Manager#Requesting_the_gHN_restart|shutdown]]

:* '''Parameters''': <code>setClean=true</code>, <code>setRestart=true</code>


=== 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|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 <code>/Resource/Profile/Body/Scope/text()=Scope Expression</code>, then extract the service URI from <code>/Resource/Profile/Body/Service/text()</code>

:* '''Operation to invoke''': [[Resource_Manager#Request_to_join_a_resource_to_the_scope|addResources]]

:* '''Parameters''': <code>setID=<GHN ID></code>, <code>setType=GHN</code>, <code>setTargetScope=<new Scope></code>


=== 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''': [[GHN_Manager|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''': [[GHN_Manager#Adding_a_new_GCUBEScope_to_the_gHN|addScope]]

:* '''Parameters''': <code>setScope=<new Scope></code>, <code>setMap=<string serialization of the Map></code>

* '''Name''': [[Resource_Manager|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 <code>/Resource/Profile/Body/Scope/text()=Scope Expression</code>, then extract the service URI from <code>/Resource/Profile/Body/Service/text()</code>

:* '''Operation to invoke''': [[Resource_Manager#Request_to_join_a_resource_to_the_scope|addResources]]

:* '''Parameters''': <code>setID=<GHN ID></code>, <code>setType=GHN</code>, <code>setTargetScope=<new Scope></code>


=== Remove from a Scope ===

'''Target''': Remove a gHN from a scope

'''Component(s) to contact''': 

* '''Name''': [[Resource_Manager|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 <code>/Resource/Profile/Body/Scope/text()=Scope Expression</code>, then extract the service URI from <code>/Resource/Profile/Body/Service/text()</code>

:* '''Operation to invoke''': [[Resource_Manager#Request_to_remove_a_resource_from_the_scope|removeResources]]

:* '''Parameters''': <code>setID=<GHN ID></code>, <code>setType=GHN</code>, <code>setTargetScope=<Scope to remove></code>

== Managing a Running Instance (RI) == 

=== Join a Scope ===

'''Target''': Join a Running Instance to a scope

'''Component(s) to contact''': 

* '''Name''': [[Resource_Manager|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 <code>/Resource/Profile/Body/Scope/text()=Scope Expression</code>, then extract the service URI from <code>/Resource/Profile/Body/Service/text()</code>

:* '''Operation to invoke''': [[Resource_Manager#Request_to_join_a_resource_to_the_scope|addResources]]

:* '''Parameters''': <code>setID=<RI ID></code>, <code>setType=RunningInstance</code>, <code>setTargetScope=<Scope to Join></code>


=== Remove from a Scope ===

'''Target''': Remove a Running Instance from a scope

'''Component(s) to contact''': 

* '''Name''': [[Resource_Manager|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 <code>/Resource/Profile/Body/Scope/text()=Scope Expression</code>, then extract the service URI from <code>/Resource/Profile/Body/Service/text()</code>

:* '''Operation to invoke''': [[Resource_Manager#Request_to_remove_a_resource_from_the_scope|removeResources]]

:* '''Parameters''': <code>setID=<RI ID></code>, <code>setType=RunningInstance</code>, <code>setTargetScope=<Scope to remove></code>

:* ''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|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 <code>/Resource/Profile/Body/Scope/text()=Scope Expression</code>, then extract the service URI from <code>/Resource/Profile/Body/Service/text()</code>

:* '''Operation to invoke''': [[Resource_Manager#Request_to_deploy_a_new_service_in_the_scope|addResources]]

:* '''Parameters''': <code>ServiceItem.setServiceClass=<Service Class></code>, <code>ServiceItem.setServiceName=<Service Name></code>, <code>ServiceItem.setServiceVersion=<Service Version></code>, <code>ServiceItem.setGHN=<GHN ID where to deploy></code> (optional, suggested gHN to use), <code>setTargetScope=<Scope to deploy in></code>, <code>ServiceList.setGHN=new String[] {"GHNID1","GHNID2","GHNID3","GHNID4","GHNID5"}</code> (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 [[ Programmatic_Administration_Interface#Remove_from_a_Scope | here ]]

'''Component(s) to contact''': 

* '''Name''': [[Resource_Manager|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 <code>/Resource/Profile/Body/Scope/text()=Scope Expression</code>, then extract the service URI from <code>/Resource/Profile/Body/Service/text()</code>

:* '''Operation to invoke''': [[Resource_Manager#Request_to_remove_a_Running_Instance_from_the_scope|removeResources]]

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

== 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 [[Programmatic_Administration_Interface#Registering_/_Unregistering_a_gCube_Generic_Resource_in_a_VO|registered in that scope]] before to be added to any scope.

'''Component(s) to contact''': 

* '''Name''': [[Resource_Manager|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 <code>/Resource/Profile/Body/Scope/text()=Scope Expression</code>, then extract the service URI from <code>/Resource/Profile/Body/Service/text()</code>

:* '''Operation to invoke''': [[Resource_Manager#Request_to_join_a_resource_to_the_scope|addResources]]

:* '''Parameters''': <code>setID=<Resouurce ID></code>, <code>setType=<Resource Type></code>, <code>setTargetScope=<Scope to add></code>

=== 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''': [[ExistClient#How_to_query_over_GCUBEResource_profiles|execute]]

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

* '''Name''': [[IS-Publisher]]

:* '''Where''': in the local instance of gCore

:* '''How to find it''': on the classpath

:* '''Operation to invoke''': [[IS-Publisher#Publishing_a_profile|registerGCUBEResource]]. Before to register the resource, the scope must be added to the local <code>GCUBEResource</code> object by invoking the method <code>GCUBEResource.addScope(<new scope>)</code>

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

=== Add 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''': [[IS-Publisher#Publishing_a_profile|registerGCUBEResource]]. Before to register the resource, the scope must be added to the local <code>GCUBEResource</code> object by invoking the method <code>GCUBEResource.addScope(<new scope>)</code>

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

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

=== Remove from a VRE Scope ===

'''Target''': Remove a gCube Resource from a scope

'''Component(s) to contact''': 

* '''Name''': [[Resource_Manager|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 <code>/Resource/Profile/Body/Scope/text()=Scope Expression</code>, then extract the service URI from <code>/Resource/Profile/Body/Service/text()</code>

:* '''Operation to invoke''': [[Resource_Manager#Request_to_remove_a_resource_from_the_scope|removeResources]]

:* '''Parameters''': <code>setID=<Resouurce ID></code>, <code>setType=<Resource Type></code>, <code>setTargetScope=<Scope to remove></code>

=== Remove from a VO Scope ===

'''Target''': Unregister a Resource from a VO. Before to proceed, the resource has to be [[Programmatic_Administration_Interface#Remove from a VRE Scope| removed from all the VRE scopes]]  it belongs to.

'''Component(s) to contact''': 

* '''Name''': [[IS-Publisher]]

:* '''Where''': in the local instance of gCore

:* '''How to find it''': on the classpath

:* '''Operation to invoke''': [[IS-Publisher#Publishing_a_profile|removeGCUBEResource]]

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

'''Note''': after the removal, the resource must be also updated in the other VO scopes it belongs to, otherwise it will wrongly report there the scopes actually removed. In order to do so, the just removed scopes must be removed from the local <code>GCUBEResource</code> object by invoking the method <code>GCUBEResource.removeScope(<scope to remove>)</code> for both the VO and all the children VRE scopes and then the [[IS-Publisher#Publishing_a_profile|updateGCUBEResource]] operation of the IS-Publisher has to be invoked in all the remaining VO and VRE scopes.

=== Remove from the Infrastructure Scope ===

'''Target''': Remove a Resource from the infrastructure scope

'''Component(s) to contact''': 

* '''Name''': [[IS-Publisher]]

:* '''Where''': in the local instance of gCore

:* '''How to find it''': on the classpath

:* '''Operation to invoke''': [[IS-Publisher#Publishing_a_profile|removeGCUBEResource]]

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

'''Note''': after the removal, the resource must be also updated in the other VO scopes it belongs to, otherwise it will wrongly report there the infrastructure scope actually removed. In order to do so, the just removed scope must be removed from the local <code>GCUBEResource</code> object by invoking the method <code>GCUBEResource.removeScope(<infrastructure scope>)</code> and then the [[IS-Publisher#Publishing_a_profile|updateGCUBEResource]] operation of the IS-Publisher has to be invoked in all the remaining VO and VRE scopes.


=== Delete from the Infrastructure ===

'''Target''': Delete a Resource from the infrastructure. 

The resource must be firstly [[Programmatic_Administration_Interface#Remove from a VO Scope|removed from the VOs]] it belongs to and then [[Programmatic_Administration_Interface#Remove from the Infrastructure Scope|removed from the Infrastructure Scope]] if it is also registered there.

== Editing a gCube Resource ==


== Banning a gCube Resource ==