THIS DOCUMENT AND THE SOFTWARE THAT IT DESCRIBES IS PROVIDED BY IAIN JAMES MARSHALL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

1. Disclaimer
2. Introduction to the CompatibleOne OCCI Server Library.
3. The Application Programming Interface of the CompatibleOne OCCI Server Library.
   1. Starting an OCCI Server
   2. Creating and OCCI Category
   3. Addition of an OCCI Attribute to an OCCI Category
   4. Addition of an OCCI Action to an OCCI Category
   5. Removal of an OCCI Category
4. The Structures and Data Types of the CompatibleOne OCCI Server Library.
   1. The OCCI Category Structure
   2. The OCCI Category Attribute
   3. The OCCI Category Action
5. References.
6. Publication and Licensing Information.

This document describes the CompatibleOne OCCI Server Library which provides the basic building block for the construction of CompatibleOne OCCI Service components comprising the Accords platform.

This library is a standard "C" library allowing easy integration for use in any other programming language environment. The library is built on top of the REST/HTTP server Library and makes implicite but extensive use of the collection functions described in the document CO-REST : CompatibleOne Rest Server.

This OCCI server package provides all the functions required to build the OCCI category structures needed for the description of the behaviour of the OCCI server. The list of categories is passed to the OCCI server on startup and provides the tables of interface methods to be called back as required to satisfy the service requests received through the underlying HTTP/REST server.

The concepts and terminology required for the correct understanding of the information provided in this document may be aquired using the specifications published on the Open Cloud Computing Interface (OCCI) web site.

The overall architecture of the use of this library can be seen in the following table.

From the above it should be understood that:

1. The application program instance encapsulates the entire OCCI server mechanism.
2. The OCCI Category and Action management mechanisms prepare the list of Categories, Attributes and Actions.
3. The OCCI Server Layer is responsible for directing requests back to the appropriate Category Methods.
4. The REST Server Layer is responsible for handling of all HTTP operations, requests and responses through the method table.
5. The REST/HTTP methods applied to OCCI categories through this architecture perform the ultimate CRUD operations on the Category instances.

This section of this document describes the public functional interface of the CompatibleOne OCCI Server Library which provides a basic building block for the construction of the CompatibleOne OCCI Accords platform and tools.

Syntax

int occi_server (	char * name,
	int port,
	char * tls,
	struct occi_category * categories,
	char * authorisation	)

Description

The OCCI Server Library is built on top of the functionalities provided by the REST Server library and delegates responsibility for the processing of all aspects of the low level HTTP communication, message reception and response transmission.

Each of the categories in the category list will provide their own functional interface table for each of the REST operational verbs ( GET, POST, PUT, DELETE, HEAD).

Actions defined for individual categories will provide the function pointer to the application function implementing their particular

behaviour. These function relays allow the actual behaviour of the server to be defined outside of the library and will be invoked passing the concerned OCCI category object, the client connection structure and the request description structure as parameters.

Each The function relay is to return a valid REST response structure pointer describing the details of the response to be produced and returned to the client by the REST server.

Parameters

The name parameter

provides of the name of the server and will be used by the HTTP Server header field that will be returned in each response message issued by the underlying REST server.

The port parameter

provides the TCP port number on which the REST server is to listen.

The tls parameter

which, when not NULL, provides the name of the transport layer security configuration to be used to specify keys and certificates and other TLS operational conditions.

The categories parameter

will provide the list of OCCI categories that are required to describe the server in terms of its OCCI capabilities. This list of categories will be built using the different functions provided by this library to this effect.

The authorisation parameter

may provide a non NULL string that is to be used by an HTTP X-OCCI-AUTH header field to provide application specific authorisation information to be supplied by the server with each and every response message.

Example

#include "standard.h"
#include "rest.h"
#include "occi.h"
extern	struct occi_category * build_category_list();
int	main( int argc, char * argv[] )
{
	char *	agentname="OcciTest";
	int	port=8088;
	char *  tls=(char *) 0;
	int	threads=1;
	struct	occi_category * list=(struct occ_category *) 0;
	char *	authorisation=(char *) 0;
	int	status=0;

	/* tool specific command line processing ..... */

	if (!( list = build_category_list() )) 
	{
		printf("\nerror building OCCI category list\n");
		return(1);
	}
	else 
	{
		if ((status = occi_server( agentname, port, tls, threads,list, authorisation )) != 0)
			printf("\nerror starting OCCI server : %u\n",status);

		list =  occi_remove_categories( list );
		return( status );
	}
}

An example of the build_category_list function is demonstrated in the category list builder.

Syntax

struct occi_category * occi_remove_category ( struct occi_category * category )

Description

This function allows the removal of a complete OCCI category representation structure including its underlying attribute and action lists. All memory associated with the category control structure will be released.

Parameters

The category parameter

This parameter provides the pointer to the OCCI category control structure to be released and removed.

Example

An example of the use of this function is provided in the example demonstrating the category list builder.

Syntax

struct occi_attribute * occi_add_attribute (
	struct occi_category * category,
	char * name,
	int mandatory,
	int immutable	)

Description

This library function is to be used for the addition of an OCCI Attribute control structure to an OCCI Category control structure. The parameters provided at the call will be used to describe the attribute.

Parameters

The category parameter

This must provides a pointer to the valid OCCI Category control structure to which the new attribute is to be appended.

The name parameter

This string parameter provides the name to be used to identify and access this attribute value.

The mandatory parameter

As its name suggests this boolean value indicates if the attribute is mandatory and as such is required to be part of OCCI renderings transiting between the client and the server.

The immutable parameter

Again as its name suggests, this boolean parameter indicates if modification of the attribute is to be allowed by the client.

Example

An example of the use of this function can be found here.

Syntax

struct occi_action * occi_add_action (
	struct occi_category * category,
	char * name,
	char * parameters,
	void * action	)

Description

This library function is to be used for the addition of an OCCI Action control structure to an OCCI Category control structure. The parameters provided at the call will be used to describe the action.

Parameters

The category parameter

This must provides a pointer to the valid OCCI Category control structure to which the new action is to be appended.

The name parameter

This string parameter provides the name to be used to identify and invoke this action.

The parameters parameter

This parameter provides a comma separated list of parameter names for which values may be defined by invocation expressions for this action method.

The action parameter

This parameter, though defined for simplicity as a void * provides a function pointer to the actual operational function to Again as its name suggests, this boolean parameter indicates if modification of the attribute is to be allowed by the client.

Example

An example of the use of this function can be found here.

Syntax

struct occi_category * occi_create_category (
	char * domain,
	char * name,
	char * scheme,
	char * classname,
	char * relation,
	char * title	)

Description

This function allows the creation of an OCCI category control structure. It will be used to provide the description of an OCCI category during the operation of an OCCI Server Instance. The structure will be used as the parameter to the appropriate functions for tha addition of OCCI Attribute and Action descriptons.

Parameters

The domain parameter

This string parameter provides the domain component to be used for the construction of the complete category attribute access path of the form : domain.name.attribute.

The name parameter

This string parameter provides the name component to be used for the construction of the complete category attribute access path of the form : domain.name.attribute.

The scheme parameter

This string parameter provides the complete url to be used to locate the document contianing the formal description of the complete category in machine readable form.

The classname parameter

This string value provides the nature of the category and should be one of the following basic types as described in the XMPP Core standard document:

kind

mixin

action

link

The relation parameter

This string parameter provides the name of the OCCI category or resopurce which is the direct parent of the newly created category definition. This should at least be the basic resource type as defined in the XMPP Core standard document.

The title parameter

This string parameter provides a human readable text describing the category and its basic use and semantics.

Example

Here we have a example implementation of the function build_category_list demonstrating the use of the OCCI server supoport functions required for the construction of a valid OCCI category control structure.

	/* ------------------------------------------ */
	/* trivial example of an OCCI action function */
	/* ------------------------------------------ */
	struct rest_response * 	application_test_example(
					struct occi_category * optr, 
					struct rest_client * cptr,
					struct rest_request * rptr )
	{
		return( (struct rest_response *) 0 );
	}

	/* -------------------------------------------------- */
	/* example of creation of an OCCI category comprising */
	/* three attributes "name, description and status"    */
	/* and one action "test"                              */
	/* -------------------------------------------------- */
	struct	occi_category * build_category_list()
	{
		struct occi_category  * cptr;
		struct occi_attribute * aptr;
		struct occi_action    * fptr;
		if (!( cptr = occi_create_category( 
			"example", "test", 
			"http://example.test.org/test",
			"occi.core.resource", 
			"Example of Occi Category Creation" )))
			return( cptr );
		else if (!( aptr = occi_add_attribute( cptr, "name", 1, 0 ) ))
			return( occi_remove_category( cptr ) );
		else if (!( aptr = occi_add_attribute( cptr, "description", 0, 0 ) ))
			return( occi_remove_category( cptr ) );
		else if (!( aptr = occi_add_attribute( cptr, "status", 0, 1 ) ))
			return( occi_remove_category( cptr ) );
		else if (!( fptr = occi_add_action( cptr, "test", "", application_test_example ) ))
			return( occi_remove_category( cptr ) );
		else	return( cptr );
	}

Clearly, in the above example only one category instance is created and returned to the caller. Further instances may be appended via the double linked list pointers provided within the occi_category structure for this purpose.

This structure contains the information needed to both represent and operate an OCCI category within this C implementation of an OCCI Server. In all functional interface descriptions above the term struct occi_category refers to an entity or entity pointer of exactly this type.

The structure contains fields required for the management of the category with in the server, other fields necessary for the description of the category and finally fields needed for its flexible operation within an abstract processing tool chain.

struct	occi_category
{
	struct	occi_category  	* previous;
	struct	occi_category  	* next;
	struct	occi_attribute 	* first;
	struct	occi_attribute 	* last;
	struct	occi_action	* firstact;
	struct	occi_action	* lastact;
	char			* domain;
	char		    	* id;
	char			* scheme;
	char			* class;
	char			* title;
	char 			* rel;
	char			* location;
	int			  access;
	void			* interface;
	void			* callback;
	void			* payload;
}

previous

this member of the occi_category structure points to an eventual preceeding category definition in the category list. The pointer will be null when the category is the first in the list.

next

this member of the occi_category structure points to an eventual following category definition in the category list. The pointer will be null when the category is the last in the list.

first

this member of the occi_category structure points to the first attribute in the category attribute list. The pointer will be null when no attributes are defined for the category.

last

this member of the occi_category structure points to the last attribute in the category attribute list. The pointer will be null when no attributes are defined for the category.

firstact

this member of the occi_category structure points to the first action in the category action list. The pointer will be null when no actions are defined for the category.

lastact

this member of the occi_category structure points to the first action in the category action list. The pointer will be null when no actions are defined for the category.

domain

this member of the occi_category structure provides the domain name component of the full category name.

id

this member of the occi_category structure provides the identification name component of the full category name.

scheme

this member of the occi_category structure provides the url of the schema of the document describing the category.

class

this member of the occi_category structure provides the OCCI nature of the category as kind, action, link or mixin.

title

this member of the occi_category structure provides a human readable description of the category.

rel

this member of the occi_category structure provides the parent category type from which this category is derived. This would be at least the resource of the standard OCCI core.

location

this member of the occi_category structure provides the category location string used in producing access prefixs for instances of this category.

access

this member of the occi_category structure defines the access rights and behaviour of the category. This bitfield value contains definitions to be used by external tools for the interpretation and publication of categories.

interface

this member of the occi_category structure will be used to carry the table of application interface functions that will be invoked as and when required for the servicing of standard REST requests received by the OCCI server for this particular category.

callback

this member of the occi_category structure will be used to carry the table of application call back functions that will be invoked as and when required during the servicing of standard REST requests received by the OCCI server for this particular category. This method table allows the definition of CRUD extensions to be performed on particular category instance definitions during the processing of a REST operation.

payload

this member of the occi_category structure allows storage of optional data extensions as required by the processing chain prior to invocation of the occi server initiation function. The instance would be used by post and pre processing tools during REST and CRUD level operations.

This structure contains the information needed to both represent and operate an attribute of an OCCI category within this C implementation of an OCCI Server. In all functional interface descriptions above the term struct occi_attribute refers to an entity or entity pointer of exactly this type.

struct	occi_attribute
{
	struct	occi_attribute 	* previous;
	struct	occi_attribute 	* next;
	struct	occi_category  	* parent;
	char		    	* name;
	int			  mandatory;
	int			  immutable;
}

previous

this member of the occi_attribute structure points to an eventual preceeding attribute definition in the attribute list. The pointer will be null when the attribute is the first in the list.

next

this member of the occi_attribute structure points to an eventual following attribute definition in the attribute list. The pointer will be null when the attribute is the last in the list.

parent

this member of the occi_attribute structure points to the parent category structure instance to which this attribute belongs. The pointer will be null only when an attribute is not attached to the attribute list of a category.

name

this member of the occi_attribute structure provides the identification name of the attribute.

mandatory

this boolean member of the occi_attribute structure indiatces that a value for this attribute is required to be present in messages received in client requests.

immutable

this boolean member of the occi_attribute structure indicates that this attribute may not be modified by values present in messages received in client requests.

This structure contains the information needed to both represent and operate an action of an OCCI category within this C implementation of an OCCI Server. In all functional interface descriptions above the term struct occi_action refers to an entity or entity pointer of exactly this type.

struct	occi_action
{
	struct	occi_action 	* previous;
	struct	occi_action 	* next;
	struct	occi_category  	* parent;
	struct	occi_parameter	* first;
	struct	occi_parameter	* last;
	char		    	* name;
	void			* action;
}

previous

this member of the occi_action structure points to an eventual preceeding action definition in the action list. The pointer will be null when the action is the first in the list.

next

this member of the occi_action structure points to an eventual following action definition in the action list. The pointer will be null when the action is the last in the list.

parent

this member of the occi_action structure points to the parent category structure instance to which this action belongs. The pointer will be null only when an action is not attached to the action list of a category.

first

this member of the occi_action structure points to the first parameter in the action parameter list. The pointer will be null when no parameters are defined for the action.

last

this member of the occi_action structure points to the last parameter in the action parameter list. The pointer will be null when no attributes are defined for the action.

name

this member of the occi_action structure provides the identification name of the action or method.

action

this member of the occi_action structure must be initialised to point to the service function to be invoked upon reception of action invocation requests for this particular action. The target function to which this field points must be of the following signature:

	struct rest_response * 	
		application_test_example
		(
			struct occi_category * optr, 
			struct rest_client * cptr,
			struct rest_request * rptr 
		)

Definitions of the types required to be received and returned by these action service functions may be found in the document describing the application programming interfaces,structures and data types of the CompatibleOne REST Server Library.

1. CompatibleOne OCCI Client Library
2. GFD 183 OCCI Core standard
3. GDF 184 OCCI Infrastructure
4. GDF 185 OCCI HTTP Binding
5. RFC 2616 HTTP 1.1 Specifications