SourceForge : View Wiki Page: Collections

Search Wiki Pages Project: occi-wg Wiki > Collections > View Wiki Page

wiki2456: Collections

Opens

Should a client get to choose how many Kinds are returned in each listing? Or should these be provider set?

Introduction

OCCI collections are represented by Categories. Categories have been modelled to allow a many to many relationship between themselves and Resources. The Category type groups related sub-class instances of Kind. Such a group is a collection of Kinds that share the same Category. By default an OCCI provider MUST support collections through the mandatory categories (e.g. link, sub-types of Resource). There are three ways of interacting with Collections:

Add a resource or resources to a collection,
Remove a resource from a collection,
List a collection's contents,
Create custom collections.

Adding to Collection

One Resource per Client Request

Implementations MUST support this. By creating a new sub-Resource e.g. Compute and associating that resource with its respective category (Compute in this case), an OCCI client is implicitly adding that requested resource instance to the compute collection. To assign an instance of a particular type of Kind instance as part of a collection is merely a matter of associating that instance with a Category. Such an instance can be associated with one or ore categories and hence collections.

Multiple Resources per Client Request

Implementations SHOULD support this. OCCI implementations SHOULD offer the ability to receive multiple resources per request as an atomic unit. To do this the client MUST supply multiple Resources within the body of a request in a form suitable for the selected rendering (e.g. multipart, see HTTP rendering). If an implementation does not support this feature, then when presented with such a request the implementation should generate an error signalling that it is unsupported.

Removing from Collection

Implementations MUST support this. A sub-class instance of Kind can be removed from any collection that is supported by a provider by using the relevant remove operation (e.g. DELETE in the HTTP header rendering). Removing such an instance from a collection MUST not destroy the instance. It MUST only disassociate the instance with the Collection. There is one exception to this rule. If a client disassociates the instance from the instance’s defining Category (e.g. compute for Compute) then the result MUST be to destroy that instance and be disassociated from all other related Categories/Collections by the implementation to prevent “dangling” references.

Creating Collection

Other than the collection (categories) supported by a provider, a client may wish to add resources to user-defined categories for the purpose of organisation. To do this a client can associate tags with the resources in questions. A ‘tag’ is a core OCCI Category that has one attribute that holds the value of the tag. Tags are used in the very same way as other core Categories. The tag specification is shown below.

Term	Scheme	Title	Related Category
tag	http://schemas.ogf.org/occi/core#	A tag	None

Attribute	Type	Multiplicity	Client Mutability	Description
occi.core.tag	String	1	Mutable	The value of the tag which describes the related Kind

Navigating a Collection

Implementations MUST support this. Collections are operated on by Link Actions, using the relevant Link (See Link & Action). When a client requests a listing of a collection’s associated Kinds, an implementation SHOULD, for reasons of performance, return a predefined number of Kinds as a sub-set or “page”. When listed, the page of Kinds MUST provide a means to navigate through the collection so as to allow the retrieval of the next, previous, first and last pages. This functionality MUST be implemented using the Link type. There are four Links used to navigate through collections:

First – following this Link target returns the first page of Kinds for the current collection.
Next – following this Link target returns the next page of Kinds for the current collection.
Previous – following this Link target returns the previous page of Kinds relative to the current sub-set.
Last – following this Link target returns the last page of Kinds for the current collection.

A collection must be divided into consistently ordered pages so that the listings returned using the above means of navigation remains consistent. Collections may be listed as a set of identifiers (e.g. URIs) to the target Kinds. Alternatively, a collection may be listed as a set of full Kind representations inline. How a collection is rendered is specified by the particular rendering in use.

HTTP Text Header Rendering Specific

To send an atomic request for multiple resources a client can use the HTTP multipart request format [1]. When issuing a multipart request to an OCCI implementation the client must:

Specify optional request headers: A client may optionally include additional header name/values that extensions of the multiple resource request requires. Another extension use case here could use this as a means to group common header name/values of the complete request together.
Specify each multipart entity content: Each multipart entity should contain the full specification for the requested resource and use the HTTP header rendering for that particular resource. Each multipart entity is comprised of both a set of HTTP headers and a body of arbitrary content. Resource specifications must be set in the body of the multipart entity (see note* below). The number and types of resources in the multipart request body is arbitrary.

The response to a multipart request is the same as the response to a single resource request. Below is an example if a full multipart request that requires the target OCCI service provider to provision two virtual machines.

POST /service HTTP/1.1
Category: service; scheme='http://sla-at-soi.eu/ism/service#'; title='A infrastructure service'
Attribute: eu.slasoi.task.notificationUri='andy@home.edmonds.be'
Content-Length: 874
Content-Type: multipart/form-data; boundary=6CGmLpQ1UDOw7YsNh4coNQ2WsurgqbrF2-lz
Host: localhost:8080
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.0.3 (java 1.5)
Expect: 100-Continue

--6CGmLpQ1UDOw7YsNh4coNQ2WsurgqbrF2-lz
Content-Disposition: form-data; name="1"
Content-Type: text/plain; charset=MacRoman
Content-Transfer-Encoding: 8bit

Category: compute; scheme='http://schemas.ogf.org/occi/infrastructure#'; title=''
Attribute: occi.compute.hostname=multi1
Attribute: occi.compute.cores=1
Attribute: occi.compute.memory=256
Attribute: eu.slasoi.task.notificationUri='andy@home.edmonds.be'
--6CGmLpQ1UDOw7YsNh4coNQ2WsurgqbrF2-lz
Content-Disposition: form-data; name="2"
Content-Type: text/plain; charset=MacRoman
Content-Transfer-Encoding: 8bit

Category: compute; scheme='http://schemas.ogf.org/occi/infrastructure#'; title=''
Attribute: occi.compute.hostname=multi2
Attribute: occi.compute.cores=1
Attribute: occi.compute.memory=256
Attribute: eu.slasoi.task.notificationUri='andy@home.edmonds.be'
--6CGmLpQ1UDOw7YsNh4coNQ2WsurgqbrF2-lz--

*Andy: using java libraries I have not been able to extract headers in each multipart entity contained in the request.

Hide Details

	Versions		Associations		Attachments		Back Links

Version	Version Comment	Created By
Version 12		Andy Edmonds - 10/04/2010
Version 11	formatting	Andy Edmonds - 10/04/2010
Version 10		Andy Edmonds - 10/04/2010
Version 9	added description on HTTP rendering multipart request	Andy Edmonds - 10/04/2010
Version 8		Andy Edmonds - 10/03/2010
Version 7	added opens	Andy Edmonds - 10/03/2010
Version 6	further collection updates	Andy Edmonds - 10/03/2010
Version 5		Andy Edmonds - 10/03/2010
Version 4		Andy Edmonds - 10/03/2010
Version 3	adding collection/category description	Andy Edmonds - 10/03/2010
Version 2		Andy Edmonds - 09/21/2010
Version 1		Andy Edmonds - 09/21/2010