Information System Resource Registry

From Gcube Wiki
Revision as of 17:24, 6 November 2017 by Luca.frosini (Talk | contribs) (→‎Responses)

Jump to: navigation, search

The Resource Registry is an Information System designed to support the operation of an 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 an 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 to store 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 Facet_Based_Resource_Model#Entity entities and Facet_Based_Resource_Model#Relation 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 to notify any update or creation of any entity or relation to Information System Subscription Notification Service.

To reach its goals Resource Registry offers 4 port types:

Every Port type is exposed as REST API.

Every REST api is JSON based. This means that any content present in an HTTP request is formatted by using JSON standard.

Each port type and the provided API is presented in the section Interacting with Resource Registry Service

Resource Registry Context Client

Resource Registry Schema is a java library providing RPC facilities to interact with Context Management port type. The library hide all the complexity of marshalling and unmarshalling of requests and result. By using this library any client is able to manage java classes instead of json object.

Resource Registry Schema Client

Resource Registry Schema is a java library providing RPC facilities to interact with Schema Management port type. The library hide all the complexity of marshalling and unmarshalling of requests and result. By using this library any client is able to manage java classes instead of json object.

Resource Registry Publisher

Resource Registry Publisher is a java library providing RPC facilities to interact with ER Management port type. The library hide all the complexity of marshalling and unmarshalling of requests and result. By using this library any client is able to manage java classes instead of json object.

Resource Registry Client

Resource Registry Client is a java library providing RPC facilities to interact with Query & Access port type. The library hide all the complexity of marshalling and unmarshalling of requests and result. By using this library any client is able to manage java classes instead of json object.

Interacting with Resource Registry Service

This sections provide information regarding hot to interact with Resource Registry Service . REST and JAVA API are presented for each functionality.

Please note that the provided examples can intentionally hide some details in the response to avoid unneeded complexity.

Context Management

It is responsible for managing Context belonging to the same Application Domain.

Security configuration based on Authorization Framework make this port type accessible only from Resource Manager. In other words no others client is allowed to manage Context rather than Resource Manager.

Context requirements:

  • No predefined number of levels.
  • Possibility to change the name of the Context with no impact for any component.
  • Possibility to move a Context from a parent Context to another.

Available Methods:

Any action made to Contexts succeed if the following requirements are guaranteed:

  • 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.

At time of writing this port type is only accessible by using REST API. Resource Registry Context Client (java client) is under development.

Create

PUT /resource-registry/context
Description

Create new Context as child of another Context (if any).

Parameters
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
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 

PUT /resource-registry/context?name=gcube

Response Body 

{
	"@class":"Context",
	"name":"gcube",
	"header": {
		"@class":"Header",
		"uuid":"2705dd32-c857-444b-818a-3ec69e339e5d",
		"creator":"luca.frosini",
		"lastUpdater":"luca.frosini",
		"creationTime":"2017-03-17 11:47:55",
		"lastUpdateTime":"2017-03-17 11:47:55"
	}
}


Create a new Context with name devsec as child of Context with UUID 2705dd32-c857-444b-818a-3ec69e339e5d (gcube)

Request URL 

/resource-registry/context?name=devsec&parentContextId=2705dd32-c857-444b-818a-3ec69e339e5d

Response Body 

{
	"@class":"Context",
	"name":"devsec",
	"header": {
		"@class":"Header",
		"uuid":"30f6254c-c87a-451e-bc0f-7cfcbd94a84a",
		"creator":"luca.frosini",
		"lastUpdater":"luca.frosini",
		"creationTime":"2017-03-17 11:47:56",
		"lastUpdateTime":"2017-03-17 11:47:56"
	}
}


Create a new Context with name devVRE as child of Context with UUID 30f6254c-c87a-451e-bc0f-7cfcbd94a84a (devsec)

Request URL 

/resource-registry/context?name=devVRE&parentContextId=30f6254c-c87a-451e-bc0f-7cfcbd94a84a

Response Body 

{
	"@class":"Context",
	"name":"devVRE",
	"header": {
		"@class":"Header",
		"uuid":"9d73d3bd-1873-490c-b0a7-e3c0da11ad52",
		"lastUpdater":"luca.frosini",
		"creator":"luca.frosini",
		"creationTime":"2017-03-17 11:47:57",
		"lastUpdateTime":"2017-03-17 11:47:57"
	}
}

If you try to create again a Context with name gcube with no parent. You will obtain a 400 Bad Request HTTP error

Request URL 

PUT /resource-registry/context?name=gcube

Response Body 

{
    "@class": "ContextCreationException",
    "message": "A root context with the same name (gcube) already exist"
}

This will happen anytime you try to create a context with the same name, having the same parent, of an existing Context.

Rename

POST /resource-registry/context/rename/{UUID}
Description

Rename a Context identified by the UUID provided as path parameter to the new name provided as query parameter.

Parameters
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
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 

POST /resource-registry/context/rename/9d73d3bd-1873-490c-b0a7-e3c0da11ad52?name=devNext

Response Body 

{
	"@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"
}

Move

POST /resource-registry/context/move/d821bcc0-946b-11e6-bdf4-800200c9a66[?parentContextId=a2fe0030-7b3d-4617-ba37-532c0e4b778d]

Delete

DELETE /resource-registry/context/d821bcc0-946b-11e6-bdf4-0800200c9a66

Schema Management

At time of writing this port type is only accessible by using REST API. Resource Registry Schema Client (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. default=null.
  • 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. default=false.
  • superclasses (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported.
  • Zero o more Properties
Property

Any Property is described by the following attributes:

  • name : Property Name
  • type : The Type of the Property (e.g. String, Integer, ...). See Property Type
  • description : The description of the Property. default=null.
  • mandatory : Indicate if the Property is mandatory. default=false.
  • readOnly : The Property cannot change its value. default=false.
  • notNull : Whether the property must assume a value diverse from 'null' or not. default=false
  • max : default=null
  • min : default=null
  • regexpr : A Regular Expression to validate the property value, default=null. A good online tool for regex is avalable at https://regex101.com/
Property Type Mapping

Property Type are mapped to and integer to be used in property definition:

Type binder is defined here: [1]

Type Integer Mapping Java type Description
Boolean 0 java.lang.Boolean or boolean Handles only the values True or False.
Integer 1 java.lang.Integer or int or java.math.BigInteger 32-bit signed Integers.
Short 2 java.lang.Short or short Small 16-bit signed integers.
Long 3 java.lang.Long or long Big 64-bit signed integers.
Float 4 java.lang.Float or float Decimal numbers
Double 5 java.lang.Double or double Decimal numbers with high precision.
Date 6 java.util.Date Any date with the precision up to milliseconds.
String 7 java.lang.String Any string as alphanumeric sequence of chars.
Binary 8 java.lang.Byte[] or byte[] Can contain any value as byte array.
Embedded 9 ? extends org.gcube.informationsystem.model.embedded.Embedded This is an Object contained inside the owner Entity and has no Header. It is reachable only by navigating the owner Entity.
Embedded list 10 List<? extends org.gcube.informationsystem.model.embedded.Embedded> List of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity.
Embedded set 11 Set<? extends org.gcube.informationsystem.model.embedded.Embedded> Set (no duplicates) of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity.
Embedded map 12 Map<String, ? extends org.gcube.informationsystem.model.embedded.Embedded> Map of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity.
Byte 17 java.lang.Byte or byte Single byte. usesful to store small 8-bit signed integers.

Resource Type Creation

PUT /resource-registry/schema/Resource

Request Body 

{
	"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. */
}

Facet Type Creation

PUT /resource-registry/schema/Facet

Request Body 

{
	"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 */
		}
	]
}

IsRelatedTo Type Creation

PUT /resource-registry/schema/IsRelatedTo

Request Body 

{
	"name":"Hosts",
	"description": "…”,
	"abstractType":false,
	"superclasses":["IsRelatedTo"],
	"properties":[]
}

ConsistsOf Type Creation

PUT /resource-registry/schema/ConsistsOf

Request Body 

{
	"name":"HasContact",
	"description":"",
	"abstractType":true,
	"superclasses":["ConsistsOf"],
	"properties":[]
}

Embedded Type Creation

PUT /resource-registry/schema/Embedded

Request Body 

{
	"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 */
	}]
}

ER Management

Apart the REST API this port type can be used also by using Resource Registry Publisher java client.


Resource Registry Publisher has the following maven coordinates 

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

To use the client you need first get a ResourceRegistryPublisher instance. By using ResourceRegistryPublisher.create() method the library discover the correct endpoint to interact with the Resource Registry for the current context. 

SecurityTokenProvider.instance.set("Your-NextNext-Token-Here"); //If not already set
ResourceRegistryPublisher resourceRegistryPublisher = ResourceRegistryPublisherFactory.create();


Facet Instances APIs

Create Facet Instance
REST API
PUT /resource-registry/er/facet/CPUFacet

Request Body 

{
	"@class":"CPUFacet",
	"header":null,
	"model":"Opteron",
	"vendor":"AMD",
	"clockSpeed":"1 GHz"
}

Response Body 

{ 
	"@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
	}
}
Java API
CPUFacet cpuFacet = new CPUFacetImpl();
cpuFacet.setClockSpeed("1 GHz");
cpuFacet.setModel("Opteron");
cpuFacet.setVendor("AMD");

CPUFacet createdCpuFacet = resourceRegistryPublisher.createFacet(CPUFacet.class, cpuFacet);
UUID uuid = createdCpuFacet.getHeader().getUUID(); // 69f0b376-38d2-4a85-bc63-37f9fa323f82
Update Facet Instance
REST API
POST /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82

Request Body 

{
	"@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"
}

Response Body 

{ 
	"@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"
	}
}
Java API
createdCpuFacet.setClockSpeed("2 GHz");
CPUFacet updatedCpuFacet = resourceRegistryPublisher.updateFacet(CPUFacet.class, createdCpuFacet);
Delete Facet Instance
REST API
DELETE /resource-registry/er/facet/69f0b376-38d2-4a85-bc63-37f9fa323f82

Response Body 

true
Java API
boolean deleted = resourceRegistryPublisher.deleteFacet(createdCpuFacet);

Resource Instances APIs

Create Resource Instance
REST API
PUT /resource-registry/er/resource/HostingNode

Request Body 

{
	"@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 */
			}
		}
	]
}

Response 

{
	"@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", ...}
			}
		}
	]
}
Java API
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);
Update Resource Instance
REST API
POST /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84

Request Body 

{
	"@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 */
			}
		}
	]
}

Response 

{
	"@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"
			}
		}
	]
}
Java API

/* 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);
Delete Resource Instance
REST API
DELETE /resource-registry/er/resource/670eeabf-76c7-493f-a449-4e6e139a2e84
Java API
boolean deleted = resourceRegistryPublisher.deleteResource(hostingNode);

Relation Instances APIs



Query & Access


Exists


HEAD /resource-registry/access/instance/{ER-Type}/{INSTANCE UUID}


Example



HEAD /resource-registry/access/instance/ContactFacet/4d28077b-566d-4132-b073-f4edaf61dcb9







Get Instance


GET /resource-registry/access/instance/{ER-Type}/{INSTANCE UUID}


Example 



GET /resource-registry/access/instance/ContactFacet/4d28077b-566d-4132-b073-f4edaf61dcb9







Get All Instances of a Specific Type


GET /resource-registry/access/instances/{ER-Type}?[polymorphic=(true|false)][&reference={INSTANCE UUID}][&direction=(in|out|both)]


Default:



* polymorphic : false
* direction : both



direction has sense only if reference UUID is provided, is ignored otherwise.






GET /resource-registry/access/instances/EService?polymorphic=true


GET /resource-registry/access/instances/EService?polymorphic=true&reference=4d28077b-566d-4132-b073-f4edaf61dcb9&direction=(in|out|both)







Raw Query


GET /resource-registry/access?query=SELECT FROM Facet







Retrieved from "https://wiki.gcube-system.org/index.php?title=Information_System_Resource_Registry&oldid=29859"