Difference between revisions of "Information System Resource Registry"

From Gcube Wiki
Jump to: navigation, search
(Resource Registry)
(Resource Registry Query Template Client)
 
(107 intermediate revisions by the same user not shown)
Line 4: Line 4:
 
||__TOC__
 
||__TOC__
 
|}
 
|}
Resource Registry is part of gCube [[Information System]].
+
 
 +
The [[Information_System_Resource_Registry | Resource Registry]] is the core component of the gCube [[Information System]] designed to support the operation of a hybrid cloud-based infrastructure:
 +
* To capture, transmit, store, retrieve and manipulate data from any software system enabled on the infrastructure
 +
** Location and properties
 +
** Status, load, exploitation usage, and accounting data
 +
 
 +
* To provide access to information, organized to enable
 +
** Monitoring, validation, and reporting
 +
** Elasticity and pooling of resources
 +
 
 +
* To support any software system to
 +
** Discover services and infrastructure resources
 +
 
 +
The Resource Registry - core of a SOA within the complexities of a hybrid cloud-based infrastructure – must enable
 +
 
 +
* '''a set of resource management functions'''
 +
** enabling functions
 +
*** publication, discovery
 +
*** monitoring, deployment
 +
*** contextualization, security, execution
 +
** data management functions
 +
*** access, store
 +
*** index, search
 +
*** transfer, transform
 +
 
 +
* '''plus, a set of applications'''
 +
** built against those functions
 +
 
 +
* '''Resource types: abstract view over functions'''
 +
** defined by specifications
 +
** multiple implementations, over time / concurrently
 +
 
 +
* different implementations, different information
 +
** system cannot globally define them
 +
** implementations produce/consume different facets, independently
 +
 
 +
* resource semantics dynamic
 +
** no longer predefined in class hierarchies
 +
** implicitly captured by current facets
 +
** changes over time / across “similar” resources
  
 
== Architecture ==
 
== Architecture ==
Line 10: Line 49:
 
The constituent components are:
 
The constituent components are:
  
* [[Information System Resource Registry#Resource_Registry | Resource Registry ]]
+
* [[Information System Resource Registry#Resource_Registry Service | Resource Registry Service ]]
 
* [[Information System Resource Registry#Resource_Registry_Context_Client | Resource Registry Context Client]]
 
* [[Information System Resource Registry#Resource_Registry_Context_Client | Resource Registry Context Client]]
 
* [[Information System Resource Registry#Resource_Registry_Schema_Client | Resource Registry Schema Client]]
 
* [[Information System Resource Registry#Resource_Registry_Schema_Client | Resource Registry Schema Client]]
Line 16: Line 55:
 
* [[Information System Resource Registry#Resource_Registry_Client | Resource Registry Client]]
 
* [[Information System Resource Registry#Resource_Registry_Client | Resource Registry Client]]
  
=== Resource Registry ===
+
=== Resource Registry Service ===
  
Resource Registry is the key component.  
+
'''Resource Registry Service''' is the key component of the Information System.  
It is a WebService running on [[Smartgears]]. The Resource Registry is responsible to store information regarding the Infrastructure the global and partial view of:
+
It is a web service running on [[SmartGears]] responsible for storing information regarding the Infrastructure, in particular, the global and partial view of:
 
* the resources (e.g. computing, storage, services, software, datasets);  
 
* the resources (e.g. computing, storage, services, software, datasets);  
 
* their current status (e.g. up and running, available);  
 
* their current status (e.g. up and running, available);  
Line 25: Line 64:
 
* the policies governing their exploitation.
 
* the policies governing their exploitation.
  
Furthermore the Resource Registry is responsible of keeping track of the  
+
Resource Registry is developed only by using the concepts defined in the [[Facet_Based_Resource_Model#IS_Model|IS Model]] and it provides the capabilities to enrich its knowledge by creating new types of [[Facet_Based_Resource_Model#Entity|entities]] and [[Facet_Based_Resource_Model#Relation|relations]] and their schemas.
* schema of the entities and relations is storing;
+
* their belonging to one or more application domain (i.e. Context) that make up the Infrastructure. In other words, the Resource Registry have to manage the Contexts (allowing to create hierarchy beetween them) and associate the entities and relations to one or more of the Contexts as requested by the different clients.
+
  
The Resource registry is also responsible to notify any update or creation of any entity or relation to [[Information System Subscription Notification Service]].
+
Resource Registry is capable of serving different applications domains (i.e. Context). To achieve this goal, the Resource Registry provides capabilities to manage Contexts (the contexts are hierarchical) and associate the entities and relations to one or more of the Contexts as requested by the different clients.
  
=== Resource Registry Context Client ===
+
The Resource registry is also responsible for notifying any update or creation of any entity or relation to [[Information System Subscription Notification Service]].
  
=== Resource Registry Schema Client ===
+
Maven coordinates are:
  
=== Resource Registry Publisher ===
+
<source lang="xml">
 +
<dependency>
 +
<groupId>org.gcube.information-system</groupId>
 +
<artifactId>resource-registry</artifactId>
 +
<version>[4.0.0,5.0.0-SNAPSHOT)</version>
 +
<dependency>
 +
</source>
  
  
=== Resource Registry Client ===
+
To reach its goals Resource Registry offers 5 port types:
 
+
* [[Resource Registry_Service - Context Management|Context Management]] : it manages hierarchical contexts;
Resource Registry Client is a java library providing RPC facilities to interact with [[#Query_&_Access|Query & Access]] port type.
+
* [[Resource Registry Service - Type Management|Type Management]] : it manages the definition of entities and relations types and their schema;
The library hide all the complexity of marshalling and unmarshalling of requests and result.
+
* [[Resource Registry Service - Instances Management|Instances Management]] : it manages entities and relations instances;
By using this library any client is able to manage java classes instead of json object
+
* [[Resource Registry Service - Instances Sharing Management|Instances Sharing Management]] : it manages instances sharing across different contexts;
 
+
* [[Resource Registry Service - Query Templates Management|Query Templates Management]] : it manages query templates;
== Interact with Resource Registry ==
+
* [[Resource Registry Service - Query & Access|Query & Access]] : it supports the discovery of instances through access patterns and queries.
 
+
To reach its goals Resource Registry offers 4 port types:
+
* [[#Context_Management|Context Management]] : manage hierarchical Context.
+
* [[#Schema_Management|Schema Management]] : register and define Entities and Relations schema
+
* [[#ER_Management|ER Management]] : manage instances of registered Entity and Relation type
+
* [[#Query_&_Access|Query & Access]] : query instances and get the schema definition of registered types
+
  
 
Every Port type is exposed as [https://en.wikipedia.org/wiki/Representational_state_transfer REST] API.
 
Every Port type is exposed as [https://en.wikipedia.org/wiki/Representational_state_transfer REST] API.
  
Every REST api is [https://en.wikipedia.org/wiki/JSON JSON] based. This means that any content present in an HTTP request is formatted by using JSON standard.
+
Every REST API is [https://en.wikipedia.org/wiki/JSON JSON] based. In other words, any content of an HTTP request is represented in JSON.
  
=== Context Management ===
+
=== Resource Registry Context Client ===
  
It is responsible for managing [[Facet_Based_Resource_Model#Context| Context]] belonging to the same Application Domain.
+
Resource Registry Schema is a java library providing RPC facilities to interact with [[Resource Registry Service - Context Management|Context Management]].
 +
The library hides all the complexity of marshalling and unmarshalling of requests and results.
 +
By using this library any client is able to manage java classes instead of JSON objects.
  
Security configuration based on [[Authorization Framework]] make this port type accessible only from [[Information System Resource Manager|Resource Manager]]. In other words no others client is allowed to manage [[Facet_Based_Resource_Model#Context| Context]] rather than [[Information System Resource Manager|Resource Manager]].
+
To use the Java library to interact with Context Collection declare the following dependency in your pom.xml file.
  
[[Facet_Based_Resource_Model#Context|Context]] requirements:
+
<source lang="xml">
* No predefined number of levels.
+
<dependency>
* Possibility to change the name of the Context with no impact for any component.
+
<groupId>org.gcube.information-system</groupId>
* Possibility to move a [[Facet_Based_Resource_Model#Context| Context]] from a parent [[Facet_Based_Resource_Model#Context| Context]] to another.
+
<artifactId>resource-registry-context-client</artifactId>
 +
<version>[4.0.0,5.0.0-SNAPSHOT)</version>
 +
<dependency>
 +
</source>
  
Available Methods:
+
=== Resource Registry Schema Client ===
  
* [[#Create|Create]]
+
Resource Registry Schema is a java library providing RPC facilities to interact with [[Resource Registry Service - Type Management|Type Management]].
* [[#Rename|Rename]]
+
The library hides all the complexity of marshalling and unmarshalling of requests and results.
* [[#Move|Move]]
+
By using this library any client is able to manage java classes instead of JSON objects.
* [[#Delete|Delete]]
+
  
Any action made to Contexts succeed if the following requirements are guaranteed:
+
To use the Java library to interact with Context Collection declare the following dependency in your pom.xml file.
* Two Context with same name can exist but only if they have different parents. The operation which will try to obtain a Context with the same name to the same parent will fails with no effect.
+
* Any operation made in any Context has effect only to the Context. In other words, there will be no effect on the associated Entity and Relations.
+
  
 +
<source lang="xml">
 +
<dependency>
 +
<groupId>org.gcube.information-system</groupId>
 +
<artifactId>resource-registry-schema-client</artifactId>
 +
<version>[4.0.0,5.0.0-SNAPSHOT)</version>
 +
<dependency>
 +
</source>
  
==== Create ====
+
=== Resource Registry Publisher ===
 
+
<pre>PUT /resource-registry/context</pre>
+
 
+
===== Description =====
+
 
+
Create new Context as child of another Context (if any).
+
 
+
===== Parameters =====
+
 
+
{|class="wikitable"
+
! Name
+
! Type
+
! Required
+
! Description
+
|-
+
| '''name'''
+
| String
+
| true
+
| The name of the context.
+
|-
+
| '''parentContextId'''
+
| String (UUID)
+
| false
+
| The UUID of the parent Context if any
+
|}
+
 
+
===== Responses =====
+
 
+
{|class="wikitable"
+
! Code
+
! Type
+
! Description
+
|-
+
| 200
+
| String
+
| The json representation of the context.
+
|}
+
 
+
===== Examples =====
+
 
+
Create a new Context with name '''gcube''' with no parent. It is a ROOT Context.
+
 
+
''Request URL''
+
 
+
<pre>PUT /resource-registry/context?name=gcube</pre>
+
 
+
''Response Body''
+
 
+
<pre>
+
{
+
"@class":"Context",
+
"header": {
+
"@class":"Header",
+
"uuid":"2705dd32-c857-444b-818a-3ec69e339e5d",
+
"creator":"luca.frosini",
+
"creationTime":"2017-03-17 11:47:55",
+
"lastUpdateTime":"2017-03-17 11:47:55"
+
},
+
"name":"gCube"
+
}
+
</pre>
+
 
+
 
+
 
+
Create a new Context with name '''devsec''' as child of Context with UUID '''2705dd32-c857-444b-818a-3ec69e339e5d (gcube)'''
+
 
+
''Request URL''
+
 
+
<pre>/resource-registry/context?name=devsec&parentContextId=2705dd32-c857-444b-818a-3ec69e339e5d</pre>
+
 
+
''Response Body''
+
 
+
<pre>
+
{
+
"@class":"Context",
+
"header": {
+
"@class":"Header",
+
"uuid":"30f6254c-c87a-451e-bc0f-7cfcbd94a84a",
+
"creator":"luca.frosini",
+
"creationTime":"2017-03-17 11:47:56",
+
"lastUpdateTime":"2017-03-17 11:47:56"
+
}
+
"name":"devsec"
+
}
+
</pre>
+
 
+
 
+
Create a new Context with name '''devVRE''' as child of Context with UUID '''30f6254c-c87a-451e-bc0f-7cfcbd94a84a (devsec)'''
+
 
+
''Request URL''
+
 
+
<pre>/resource-registry/context?name=devVRE&parentContextId=30f6254c-c87a-451e-bc0f-7cfcbd94a84a</pre>
+
 
+
''Response Body''
+
 
+
<pre>
+
{
+
"@class":"Context",
+
"header": {
+
"@class":"Header",
+
"uuid":"9d73d3bd-1873-490c-b0a7-e3c0da11ad52",
+
"creator":"luca.frosini",
+
"creationTime":"2017-03-17 11:47:57",
+
"lastUpdateTime":"2017-03-17 11:47:57"
+
}
+
"name":"devVRE"
+
}
+
</pre>
+
 
+
==== Rename ====
+
 
+
<pre>POST /resource-registry/context/rename/{UUID}</pre>
+
 
+
===== Description =====
+
 
+
Rename a Context identified by the UUID provided as path parameter to the new name provided as query parameter.
+
 
+
===== Parameters =====
+
 
+
{|class="wikitable"
+
! Name
+
! Type
+
! Required
+
! Description
+
|-
+
| '''{''Path Paramenter''}'''
+
| String (UUID)
+
| true
+
| The UUID of the target context.
+
|-
+
| '''name'''
+
| String
+
| true
+
| The new name of the target context.
+
|}
+
 
+
===== Responses =====
+
 
+
{|class="wikitable"
+
! Code
+
! Type
+
! Description
+
|-
+
| 200
+
| String
+
| The json representation of the context.
+
|}
+
 
+
===== Examples =====
+
 
+
Rename a Context '''9d73d3bd-1873-490c-b0a7-e3c0da11ad52''' (was '''devVRE''') to the new name '''devNext'''.
+
 
+
''Request URL''
+
 
+
<pre>POST /resource-registry/context/rename/9d73d3bd-1873-490c-b0a7-e3c0da11ad52?name=devNext</pre>
+
 
+
''Response Body''
+
 
+
<pre>
+
{
+
"@class":"Context",
+
"header": {
+
"@class":"Header",
+
"uuid":"9d73d3bd-1873-490c-b0a7-e3c0da11ad52",
+
"creator":"luca.frosini",
+
"creationTime":"2017-03-17 11:47:56",
+
"lastUpdateTime":"2017-03-17 11:52:56"
+
}
+
"name":"devNext"
+
}
+
</pre>
+
 
+
==== Move ====
+
 
+
<pre>POST /resource-registry/context/move/d821bcc0-946b-11e6-bdf4-800200c9a66[?parentContextId=a2fe0030-7b3d-4617-ba37-532c0e4b778d</pre>
+
 
+
==== Delete ====
+
 
+
<pre>DELETE /resource-registry/context/d821bcc0-946b-11e6-bdf4-0800200c9a66</pre>
+
 
+
=== Schema Management ===
+
 
+
At time of writing this port type is only accessible by using REST API.
+
A java client is under development.
+
 
+
==== Type Definition ====
+
 
+
Any Type is described by the following attributes:
+
 
+
* '''name''' (String): Type Name
+
* '''description''' (String): The description of the Type. <code>default=null</code>.
+
* '''abstractType''' (Boolean): Indicate if the type is abstract so that it cannot be instatiated. In other words only subtypes of this type can be isntantiated. <code>default=false</code>.
+
* '''superclasses''' (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported.
+
* Zero o more [[Facet_Based_Resource_Model#Property | Properties]]
+
 
+
===== Property =====
+
 
+
Any [[Facet_Based_Resource_Model#Property | Property]] is described by the following attributes:
+
 
+
* '''name''' : Property Name
+
* '''type''' : The Type of the Property (e.g. String, Integer, ...). See [[#Property_Type|Property Type]]
+
* '''description''' : The description of the Property. <code>default=null</code>.
+
* '''mandatory''' : Indicate if the Property is mandatory. <code>default=false</code>.
+
* '''readOnly''' : The Property cannot change its value. <code>default=false</code>.
+
* '''notNull''' : Whether the property must assume a value diverse from 'null' or not. <code>default=false</code>
+
* '''max''' : <code>default=null</code>
+
* '''min''' : <code>default=null</code>
+
* '''regexpr''' : A [https://en.wikipedia.org/wiki/Regular_expression Regular Expression] to validate the property value, <code>default=null</code>. A good online tool for regex is avalable at [https://regex101.com/ https://regex101.com/]
+
 
+
====== Property Type Mapping ======
+
 
+
[[Facet_Based_Resource_Model#Basic_Property_Type | Property Type]] are mapped to and integer to be used in property definition:
+
 
+
Type binder is defined here:
+
[http://svn.research-infrastructures.eu/public/d4science/gcube/trunk/information-system/information-system-model/src/main/java/org/gcube/informationsystem/types/Type.java]
+
 
+
{|class="wikitable"
+
! Type
+
! Integer Mapping
+
! Java type
+
! Description
+
|-
+
| Boolean
+
| 0
+
| <code>java.lang.Boolean</code> or <code>boolean</code>
+
| Handles only the values <em>True</em> or <em>False</em>.
+
|-
+
| Integer
+
| 1
+
| <code>java.lang.Integer</code> or <code>int</code> or  <code>java.math.BigInteger</code>
+
| 32-bit signed Integers.
+
|-
+
| Short
+
| 2
+
| <code>java.lang.Short</code> or <code>short</code>
+
| Small 16-bit signed integers.
+
|-
+
| Long
+
| 3
+
| <code>java.lang.Long</code> or <code>long</code>
+
| Big 64-bit signed integers.
+
|-
+
| Float
+
| 4
+
| <code>java.lang.Float</code> or <code>float</code>
+
| Decimal numbers
+
|-
+
| Double
+
| 5
+
| <code>java.lang.Double</code> or <code>double</code>
+
| Decimal numbers with high precision.
+
|-
+
| Date
+
| 6
+
| <code>java.util.Date</code>
+
| Any date with the precision up to milliseconds.
+
|-
+
| String
+
| 7
+
| <code>java.lang.String</code>
+
| Any string as alphanumeric sequence of chars.
+
|-
+
| Binary
+
| 8
+
| <code>java.lang.Byte[]</code> or <code>byte[]</code>
+
| Can contain any value as byte array.
+
|-
+
| Embedded
+
| 9
+
| <code>?  extends org.gcube.informationsystem.model.embedded.Embedded</code>
+
| This is an Object contained inside the owner Entity and has no [[#Header|Header]]. It is reachable only by navigating the owner Entity.
+
|-
+
| Embedded list
+
| 10
+
| <code>List&lt;?  extends org.gcube.informationsystem.model.embedded.Embedded&gt;</code>
+
| List of Objects contained inside the owner Entity and have no [[#Header|Header]]. They are reachable only by navigating the owner Entity.
+
|-
+
| Embedded set
+
| 11
+
| <code>Set&lt;? extends org.gcube.informationsystem.model.embedded.Embedded&gt;</code>
+
| Set (no duplicates) of Objects contained inside the owner Entity and have no [[#Header|Header]]. They are reachable only by navigating the owner Entity.
+
|-
+
| Embedded map
+
| 12
+
| <code>Map&lt;String, ? extends org.gcube.informationsystem.model.embedded.Embedded&gt;</code>
+
| Map of Objects contained inside the owner Entity and have no [[#Header|Header]]. They are reachable only by navigating the owner Entity.
+
|-
+
| Byte
+
| 17
+
| <code>java.lang.Byte</code> or <code>byte</code>
+
| Single byte. usesful to store small 8-bit signed integers.
+
|}
+
 
+
==== Resource Type Creation ====
+
 
+
<pre>
+
PUT /resource-registry/schema/Resource
+
</pre>
+
 
+
'''''Request Body'''''
+
<pre>
+
{
+
"name":"Actor",
+
"description":"Any entity (human or machine) playing an active role.",
+
"abstractType":true, /* If the Resource cannot be instantiated */
+
"superclasses":["Resource"], /* Resource or any registered specialization. */
+
"properties":null /* MUST be null. The Resource cannot have any property. */
+
}
+
</pre>
+
 
+
==== Facet Type Creation ====
+
 
+
<pre>
+
PUT /resource-registry/schema/Facet
+
</pre>
+
 
+
'''''Request Body'''''
+
<pre>
+
{
+
"name":"ContactFacet",
+
"description":"This facet is expected to capture contact information",
+
"abstractType": false,
+
"superclasses":["Facet"],
+
"properties":[
+
{
+
"name":"name",
+
"description":"First Name",
+
"mandatory":true,
+
"readonly":false,
+
"notnull":true,
+
"max":null,
+
"min":null,
+
"regexpr":null,
+
"linkedType":null,
+
"linkedClass":null,
+
"type":7 /* String*/
+
},{
+
"name":"eMail",
+
"description": "A restricted range of RFC‑822 compliant email address. ... ",
+
"mandatory":true,
+
"readonly":false,
+
"notnull":true,
+
"max":null,
+
"min":null,
+
"regexpr":"^[a-z0-9._%+-]{1,128}@[a-z0-9.-]{1,128}$",
+
"linkedType":null,
+
"linkedClass":null,
+
"type":7 /* String */
+
}
+
]
+
}
+
</pre>
+
 
+
==== IsRelatedTo Type Creation ====
+
<pre>
+
PUT /resource-registry/schema/IsRelatedTo
+
</pre>
+
 
+
'''''Request Body'''''
+
<pre>
+
{
+
"name":"Hosts",
+
"description": "…”,
+
"abstractType":false,
+
"superclasses":["IsRelatedTo"],
+
"properties":[]
+
}
+
</pre>
+
 
+
==== ConsistsOf Type Creation ====
+
 
+
<pre>
+
PUT /resource-registry/schema/ConsistsOf
+
</pre>
+
 
+
'''''Request Body'''''
+
<pre>
+
{
+
"name":"HasContact",
+
"description":"",
+
"abstractType":true,
+
"superclasses":["ConsistsOf"],
+
"properties":[]
+
}
+
</pre>
+
 
+
==== Embedded Type Creation ====
+
<pre>
+
PUT /resource-registry/schema/Embedded
+
</pre>
+
 
+
'''''Request Body'''''
+
<pre>
+
{
+
"name":"AccessPolicy",
+
"description":"",
+
"abstractType":false,
+
"superclasses":["Embedded"],
+
"properties":[{
+
"name":"policy",
+
"description":"",
+
"mandatory":false,
+
"readonly":false,
+
"notnull":false,
+
"max":null,
+
"min":null,
+
"regexpr":null,
+
"linkedType":null,
+
"linkedClass":”ValueSchema”,
+
"type": 9  /* Embedded */
+
},{
+
"name":"note",
+
"description":"",
+
"mandatory": false,
+
"readonly":false,
+
"notnull":false,
+
"max":null,
+
"min":null,
+
"regexpr":null,
+
"linkedType":null,
+
"linkedClass":null,
+
"type":7 /* String */
+
}]
+
}
+
</pre>
+
  
=== ER Management ===
+
Resource Registry Publisher is a java library providing RPC facilities to interact with [[Resource Registry Service - Instances Management | Instances Management]] and [[Resource Registry Service - Instances Sharing Management | Instances Sharing Management]].
 +
The library hides all the complexity of marshalling and unmarshalling of requests and results.
 +
By using this library any client is able to manage java classes instead of JSON objects.
  
Apart the REST API this port type can be used also by using a Java client
+
To use the Java library to interact with Context Collection declare the following dependency in your pom.xml file.
  
<pre>
+
<source lang="xml">
 
<dependency>
 
<dependency>
 
<groupId>org.gcube.information-system</groupId>
 
<groupId>org.gcube.information-system</groupId>
 
<artifactId>resource-registry-publisher</artifactId>
 
<artifactId>resource-registry-publisher</artifactId>
<version>[1.0.0-SNAPSHOT, 2.0.0-SNAPSHOT)</version>
+
<version>[4.0.0,5.0.0-SNAPSHOT)</version>
</dependency>
+
<dependency>
</pre>
+
</source>
  
To use the client you need first get a ''resourceRegistryPublisher'' instance.
 
By using create method the library automatically query the Information System to get the correct endpoint for the current context.
 
  
<pre>
+
=== Resource Registry Query Template Client ===
SecurityTokenProvider.instance.set("Your-NextNext-Token-Here"); //If not already set
+
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();
+
</pre>
+
  
 +
Resource Registry Query Template Client is a java library providing RPC facilities to interact with [[Resource Registry Service - Query Templates Management | Query Templates Management]].
  
==== Facet Instances APIs ====
+
To use the Java library to interact with Query Template collection declare the following dependency in your pom.xml file.
  
===== Create Facet Instance =====
+
<source lang="xml">
 +
<dependency>
 +
<groupId>org.gcube.information-system</groupId>
 +
<artifactId>resource-registry-query-template-client</artifactId>
 +
<version>[1.0.0,2.0.0-SNAPSHOT)</version>
 +
<dependency>
 +
</source>
  
====== REST API ======
+
=== Resource Registry Client ===
<pre>
+
PUT /resource-registry/er/facet/CPUFacet
+
</pre>
+
  
'''''Request Body'''''
+
Resource Registry Client is a java library providing RPC facilities to interact with [[Resource Registry Service - Query & Access|Query & Access]].
<pre>
+
The library hides all the complexity of marshalling and unmarshalling of requests and results.
{
+
By using this library any client is able to manage java classes instead of JSON objects.
"@class":"CPUFacet",
+
"header":null,
+
"model":"Opteron",
+
"vendor":"AMD",
+
"clockSpeed":"1 GHz"
+
}
+
</pre>
+
  
'''''Response Body'''''
+
To use the Java library to interact with Context Collection declare the following dependency in your pom.xml file.
<pre>
+
{
+
"@class":"CPUFacet", "model":"Opteron", "vendor":"AMD", "clockSpeed":"1 GHz",
+
"header": {
+
"uuid":"69f0b376-38d2-4a85-bc63-37f9fa323f82",
+
"creator":"luca.frosini", "creationTime":"2016-10-05 11:16:24",
+
"lastUpdateTime":"2016-10-05 11:16:24
+
}
+
}
+
</pre>
+
  
====== Java API ======
+
<source lang="xml">
<pre>
+
<dependency>
CPUFacet cpuFacet = new CPUFacetImpl();
+
<groupId>org.gcube.information-system</groupId>
cpuFacet.setClockSpeed("1 GHz");
+
<artifactId>resource-registry-client</artifactId>
cpuFacet.setModel("Opteron");
+
<version>[4.0.0,5.0.0-SNAPSHOT)</version>
cpuFacet.setVendor("AMD");
+
<dependency>
 
+
</source>
CPUFacet createdCpuFacet = resourceRegistryPublisher.createFacet(CPUFacet.class, cpuFacet);
+
UUID uuid = createdCpuFacet.getHeader().getUUID(); // 69f0b376-38d2-4a85-bc63-37f9fa323f82
+
</pre>
+
 
+
===== Update Facet Instance =====
+
 
+
====== REST API ======
+
<pre>
+
POST /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82
+
</pre>
+
 
+
'''''Request Body'''''
+
<pre>
+
{
+
"@class":"CPUFacet",
+
"header":{"uuid":"69f0b376-38d2-4a85-bc63-37f9fa323f82"}, /* if you pass the header only the UUID is checked and must be the same of the one provided in the URL*/
+
"model":"Opteron",
+
"vendor":"AMD",
+
"clockSpeed":"2 GHz"
+
}
+
</pre>
+
 
+
'''''Response Body'''''
+
<pre>
+
{
+
"@class":"CPUFacet", "model":"Opteron", "vendor":"AMD", "clockSpeed":"2 GHz",
+
"header": {
+
"uuid":"69f0b376-38d2-4a85-bc63-37f9fa323f82",
+
"creator":"luca.frosini", "creationTime":"2016-10-05 11:16:24",
+
"lastUpdateTime":"2016-10-05 11:17:32"
+
}
+
}
+
</pre>
+
 
+
====== Java API ======
+
<pre>
+
createdCpuFacet.setClockSpeed("2 GHz");
+
CPUFacet updatedCpuFacet = resourceRegistryPublisher.updateFacet(CPUFacet.class, createdCpuFacet);
+
</pre>
+
 
+
===== Delete Facet Instance =====
+
 
+
====== REST API ======
+
<pre>
+
DELETE /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82
+
</pre>
+
 
+
'''''Response Body'''''
+
<pre>
+
true
+
</pre>
+
 
+
====== Java API ======
+
<pre>
+
boolean deleted = resourceRegistryPublisher.deleteFacet(createdCpuFacet);
+
</pre>
+
 
+
==== Resource Instances APIs ====
+
 
+
===== Create Resource Instance =====
+
 
+
====== REST API ======
+
<pre>
+
PUT /resource-registry/er/resource/HostingNode
+
</pre>
+
 
+
'''''Request Body'''''
+
<pre>
+
{
+
"@class":"HostingNode",
+
"consistsOf":[
+
{
+
"@class":"ConsistsOf",
+
"target":{
+
"@class":"CPUFacet",
+
"model":"Opteron",
+
"vendor":"AMD",
+
"clockSpeed":"3 GHz"
+
}
+
},{
+
"@class":"IsIdentifiedBy",
+
"target":{
+
"@class":"NetworkingFacet",
+
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933"},
+
/* In this example we suppose that the NetworkingFacet was already created, so the UUID is enought to attach it by using IsIdentifiedBy relation */
+
}
+
}
+
],
+
"isRelatedTo":[
+
{
+
"@class":"Hosts",
+
"propagationConstraint":{
+
"add":"unpropagate",
+
"remove": "cascade"
+
},
+
"target":{
+
"@class":"EService",
+
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3"}
+
/* The EService was already created, so the UUID is enought to attach it by using Hosts relation */
+
}
+
}
+
]
+
}
+
 
+
</pre>
+
 
+
'''''Response'''''
+
<pre>
+
{
+
"@class":"HostingNode",
+
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84"},
+
"consistsOf":[
+
{
+
"@class":"ConsistsOf",
+
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
+
"target":{
+
"@class":"CPUFacet",
+
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
"model":"Opteron",
+
"vendor":"AMD",
+
"clockSpeed":"1 GHz"
+
}
+
},{
+
"@class":"IsIdentifiedBy",
+
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
"target":{
+
"@class":"NetworkingFacet",
+
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
"ipAddress" : "146.48.87.183",
+
"hostName": "pc-frosini.isti.cnr.it",
+
"domainName" : "isti.cnr.it",
+
"mask" : "255.255.248.0",
+
"broadcastAddress":"146.48.87.255"
+
}
+
}
+
],
+
"isRelatedTo":[
+
{
+
"@class":"Hosts",
+
"header":{"uuid":"47494ad0-e606-4630-9def-4c607761ae14", ...},
+
"propagationConstraint":{
+
"add":"unpropagate",
+
"remove": "cascade"
+
},
+
"target":{
+
"@class":"EService",
+
"header":{"uuid":"9bff49c8-c0a7-45de-827c-accb71defbd3", ...}
+
}
+
}
+
]
+
}
+
</pre>
+
 
+
====== Java API ======
+
<pre>
+
NetworkingFacet networkingFacet = new NetworkingFacetImpl();
+
networkingFacet.setIPAddress("146.48.87.183");
+
networkingFacet.setHostName("pc-frosini.isti.cnr.it");
+
networkingFacet.setDomainName("isti.cnr.it");
+
networkingFacet.setMask("255.255.248.0");
+
networkingFacet.setBroadcastAddress("146.48.87.255");
+
 
+
networkingFacet = resourceRegistryPublisher.createFacet(NetworkingFacet.class, networkingFacet);
+
 
+
HostingNode hostingNode = new HostingNodeImpl();
+
 
+
CPUFacet cpuFacet = new CPUFacetImpl();
+
cpuFacet.setClockSpeed("1 GHz");
+
cpuFacet.setModel("Opteron");
+
cpuFacet.setVendor("AMD");
+
hostingNode.addFacet(cpuFacet);
+
 
+
isIdentifiedBy = new IsIdentifiedByImpl<Resource, Facet>(hostingNode, networkingFacet, null);
+
hostingNode.attachFacet(isIdentifiedBy);
+
 
+
PropagationConstraint propagationConstraint = new PropagationConstraintImpl();
+
propagationConstraint.setRemoveConstraint(RemoveConstraint.cascade);
+
propagationConstraint.setAddConstraint(AddConstraint.unpropagate);
+
 
+
Hosts<HostingNode, EService> hosts = new HostsImpl<HostingNode, EService>(hostingNode, eService, propagationConstraint);
+
hostingNode.attachResource(hosts);
+
 
+
hostingNode = resourceRegistryPublisher.createResource(HostingNode.class, hostingNode);
+
</pre>
+
 
+
===== Update Resource Instance =====
+
 
+
====== REST API ======
+
<pre>
+
POST /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84
+
</pre>
+
 
+
'''''Request Body'''''
+
<pre>
+
{
+
"@class":"HostingNode",
+
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
+
"consistsOf":[
+
{
+
"@class":"ConsistsOf",
+
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
+
"target":{
+
"@class":"CPUFacet",
+
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
"model":"Opteron",
+
"vendor":"AMD",
+
"clockSpeed":"1 GHz"
+
}
+
},{
+
"@class":"IsIdentifiedBy",
+
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
"target":{
+
"@class":"NetworkingFacet",
+
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
"ipAddress" : "146.48.87.183",
+
"hostName": "pc-frosini.isti.cnr.it",
+
"domainName" : "isti.cnr.it",
+
"mask" : "255.255.248.0",
+
"broadcastAddress":"146.48.87.255",
+
"username":"luca.frosini" /* Added this property */
+
}
+
}
+
]
+
}
+
</pre>
+
 
+
'''''Response'''''
+
<pre>
+
{
+
"@class":"HostingNode",
+
"header":{"uuid":"670eeabf-76c7-493f-a449-4e6e139a2e84", ...},
+
"consistsOf":[
+
{
+
"@class":"ConsistsOf",
+
"header":{"uuid":"9d0b1b2b-ac4e-40a9-8dea-bec90076e0ca", ...},
+
"target":{
+
"@class":"CPUFacet",
+
"header":{"uuid":"1daef6a8-5ca4-4700-844b-2a2d784e17b0", ...},
+
"model":"Opteron",
+
"vendor":"AMD",
+
"clockSpeed":"1 GHz"
+
}
+
},{
+
"@class":"IsIdentifiedBy",
+
"header":{"uuid":"02a7072c-4f72-4568-945b-9ddccc881e9f", ...},
+
"target":{
+
"@class":"NetworkingFacet",
+
"header":{"uuid":"59617b01-5856-4d8e-b85c-590a42039933", ...},
+
"ipAddress" : "146.48.87.183",
+
"hostName": "pc-frosini.isti.cnr.it",
+
"domainName" : "isti.cnr.it",
+
"mask" : "255.255.248.0",
+
"broadcastAddress":"146.48.87.255",
+
"username":"luca.frosini"
+
}
+
}
+
]
+
}
+
</pre>
+
 
+
====== Java API ======
+
<pre>
+
 
+
/* This is just a code example, here we suppose that there is only one identification Facet of the type (NetworkingFacet). This could not be true  in real scenario*/
+
networkingFacet = (NetworkingFacet) hostingNode.getIdentificationFacets().get(0);
+
networkingFacet.setAdditionalProperty("username", "luca.frosini");
+
+
hostingNode = resourceRegistryPublisher.updateResource(HostingNode.class, hostingNode);
+
 
+
</pre>
+
 
+
===== Delete Resource Instance =====
+
 
+
====== REST API ======
+
<pre>
+
DELETE /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84
+
</pre>
+
 
+
====== Java API ======
+
<pre>
+
boolean deleted = resourceRegistryPublisher.deleteResource(hostingNode);
+
</pre>
+
 
+
==== Relation Instances APIs ====
+
 
+
<pre>
+
</pre>
+
 
+
=== Query & Access ===
+
 
+
 
+
==== Exists ====
+
 
+
<pre>HEAD /resource-registry/access/instance/{ER-Type}/{INSTANCE UUID}</pre>
+
 
+
Example
+
 
+
<pre>HEAD /resource-registry/access/instance/ContactFacet/4d28077b-566d-4132-b073-f4edaf61dcb9</pre>
+
 
+
 
+
==== Get Instance ====
+
 
+
<pre>GET /resource-registry/access/instance/{ER-Type}/{INSTANCE UUID}</pre>
+
 
+
Example
+
 
+
<pre>GET /resource-registry/access/instance/ContactFacet/4d28077b-566d-4132-b073-f4edaf61dcb9</pre>
+
 
+
 
+
 
+
==== Get All Instances of a Specific Type ====
+
 
+
<pre>GET /resource-registry/access/instances/{ER-Type}?[polymorphic=(true|false)][&reference={INSTANCE UUID}][&direction=(in|out|both)]</pre>
+
 
+
Default:
+
* polymorphic : false
+
* direction : both
+
 
+
direction has sense only if reference UUID is provided, is ignored otherwise.
+
 
+
 
+
<pre>GET /resource-registry/access/instances/EService?polymorphic=true</pre>
+
 
+
<pre>GET /resource-registry/access/instances/EService?polymorphic=true&reference=4d28077b-566d-4132-b073-f4edaf61dcb9&direction=(in|out|both)</pre>
+
 
+
 
+
==== Raw Query ====
+
 
+
<pre>GET /resource-registry/access?query=SELECT FROM Facet</pre>
+

Latest revision as of 17:16, 1 February 2022

The Resource Registry is the core component of the gCube Information System designed to support the operation of a hybrid cloud-based infrastructure:

  • To capture, transmit, store, retrieve and manipulate data from any software system enabled on the infrastructure
    • Location and properties
    • Status, load, exploitation usage, and accounting data
  • To provide access to information, organized to enable
    • Monitoring, validation, and reporting
    • Elasticity and pooling of resources
  • To support any software system to
    • Discover services and infrastructure resources

The Resource Registry - core of a SOA within the complexities of a hybrid cloud-based infrastructure – must enable

  • a set of resource management functions
    • enabling functions
      • publication, discovery
      • monitoring, deployment
      • contextualization, security, execution
    • data management functions
      • access, store
      • index, search
      • transfer, transform
  • plus, a set of applications
    • built against those functions
  • Resource types: abstract view over functions
    • defined by specifications
    • multiple implementations, over time / concurrently
  • different implementations, different information
    • system cannot globally define them
    • implementations produce/consume different facets, independently
  • resource semantics dynamic
    • no longer predefined in class hierarchies
    • implicitly captured by current facets
    • changes over time / across “similar” resources

Architecture

The constituent components are:

Resource Registry Service

Resource Registry Service is the key component of the Information System. It is a web service running on SmartGears responsible for storing information regarding the Infrastructure, in particular, the global and partial view of:

  • the resources (e.g. computing, storage, services, software, datasets);
  • their current status (e.g. up and running, available);
  • their relationships with other resources.
  • the policies governing their exploitation.

Resource Registry is developed only by using the concepts defined in the IS Model and it provides the capabilities to enrich its knowledge by creating new types of entities and relations and their schemas.

Resource Registry is capable of serving different applications domains (i.e. Context). To achieve this goal, the Resource Registry provides capabilities to manage Contexts (the contexts are hierarchical) and associate the entities and relations to one or more of the Contexts as requested by the different clients.

The Resource registry is also responsible for notifying any update or creation of any entity or relation to Information System Subscription Notification Service.

Maven coordinates are:

<dependency>
	<groupId>org.gcube.information-system</groupId>
	<artifactId>resource-registry</artifactId>
	<version>[4.0.0,5.0.0-SNAPSHOT)</version>
<dependency>


To reach its goals Resource Registry offers 5 port types:

Every Port type is exposed as REST API.

Every REST API is JSON based. In other words, any content of an HTTP request is represented in JSON.

Resource Registry Context Client

Resource Registry Schema is a java library providing RPC facilities to interact with Context Management. The library hides all the complexity of marshalling and unmarshalling of requests and results. By using this library any client is able to manage java classes instead of JSON objects.

To use the Java library to interact with Context Collection declare the following dependency in your pom.xml file.

<dependency>
	<groupId>org.gcube.information-system</groupId>
	<artifactId>resource-registry-context-client</artifactId>
	<version>[4.0.0,5.0.0-SNAPSHOT)</version>
<dependency>

Resource Registry Schema Client

Resource Registry Schema is a java library providing RPC facilities to interact with Type Management. The library hides all the complexity of marshalling and unmarshalling of requests and results. By using this library any client is able to manage java classes instead of JSON objects.

To use the Java library to interact with Context Collection declare the following dependency in your pom.xml file.

<dependency>
	<groupId>org.gcube.information-system</groupId>
	<artifactId>resource-registry-schema-client</artifactId>
	<version>[4.0.0,5.0.0-SNAPSHOT)</version>
<dependency>

Resource Registry Publisher

Resource Registry Publisher is a java library providing RPC facilities to interact with Instances Management and Instances Sharing Management. The library hides all the complexity of marshalling and unmarshalling of requests and results. By using this library any client is able to manage java classes instead of JSON objects.

To use the Java library to interact with Context Collection declare the following dependency in your pom.xml file.

<dependency>
	<groupId>org.gcube.information-system</groupId>
	<artifactId>resource-registry-publisher</artifactId>
	<version>[4.0.0,5.0.0-SNAPSHOT)</version>
<dependency>


Resource Registry Query Template Client

Resource Registry Query Template Client is a java library providing RPC facilities to interact with Query Templates Management.

To use the Java library to interact with Query Template collection declare the following dependency in your pom.xml file.

<dependency>
	<groupId>org.gcube.information-system</groupId>
	<artifactId>resource-registry-query-template-client</artifactId>
	<version>[1.0.0,2.0.0-SNAPSHOT)</version>
<dependency>

Resource Registry Client

Resource Registry Client is a java library providing RPC facilities to interact with Query & Access. The library hides all the complexity of marshalling and unmarshalling of requests and results. By using this library any client is able to manage java classes instead of JSON objects.

To use the Java library to interact with Context Collection declare the following dependency in your pom.xml file.

<dependency>
	<groupId>org.gcube.information-system</groupId>
	<artifactId>resource-registry-client</artifactId>
	<version>[4.0.0,5.0.0-SNAPSHOT)</version>
<dependency>