Navigation:
Documentation
Archive



Page Tree:

Child pages
  • Result Set Caching Service Contract Description v0.8 - BDOC

This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.

Skip to end of metadata
Go to start of metadata

Contract:

 

 

Unknown macro: {multi-excerpt} Result Set Caching

 

 

 

Brief description

The Result Set Caching (RSC) service is a general service that stores and retrieves a set of results -- generally results returned by another service -- to for a limited period of time.

Version

This page describes the Result Set Caching service API, v0.8

To discover the version and other metadata about deployed service code that fulfills this API, please utilize the Service Catalog Service - BDOC.

Overview and Definitions

The Result Set Caching (RSC) service is a general service that stores and retrieves a set of results -- generally results returned by another service -- to for a limited period of time. The purpose of this temporary storage is to keep service results available for application to further service-processing (e.g., in a "pipeline" process) without unnecessary transport of the result set over the network (e.g., between the service host and a caller/client of a series of services, in a "pipeline" process).

When the RSC sends / receives content, it relies on the Media type provided as a parameter by the RSC's client at the time content is added to the cache. The asserted Media type is stored as part of the Cache Item's metadata.

The RSC does not verify that the content provided constitutes a valid instance of the asserted Media type, nor does it modify the content, nor does it perform any exception handling beyond returning a "404 Not Found" if a requested item is not available from the cache.

For a full description, visit the Result Set Caching Service Description and Assumptions page of Project Bamboo's development wiki.

Assumptions

  1. The Cached Item id is generated by the RSC to ensure uniqueness
  2. The contents stored in the cache are opaque to this (RSC) service; Media type metadata is accurate only if a valid Media type was provided by the creator (client to RSC)
  3. The expiration date for the Cached Item is settable by a client service
  4. All Cached Item data (i.e., both metadata and content) are mutable except for the id itself.

References

None

Known Issues

None

ROA Layer API

RESTful service methods performing Create, Read, Update, Delete, and List functions over content cached by this service, described here as a Cached Item.

The only RESTful method currently exposed on Cached Item is READ. Other methods are accessible via the SOA layer of the architecture, see API below.

Base URLs

Currently available instances of the Bamboo Services Platform are INSECURE, are operated with NO EXPLICIT SLA, and should be considered STATELESS: that is, data may be wiped from persistent stores at any time.

A secure instances of the BSP, with URLs that do not require explicit inclusion of a port number, and for which data will be preserved on future upgrades is anticipated in Fall 2012.

Currently available base URLs:

To receive notices about maintenance, down-time, and other issues about instances of the Bamboo Services Platform you may subscribe to bsp-bulletins@lists.projectbamboo.org. You may unsubscribe here.

Schema

There is no schema associated with this API.

Cached Item

A Cached Item is assumed to be a set of results generated by another service. It's structure is opaque to this service. Its metadata is set by the service that creates a Cached Item; this service does not validate the accuracy of the provided metadata.

Read a Cached Item

Retrieve an existing cached item, specified by its ID.

Calling Method and Arguments

Invoked as an HTTP GET method on a specific instance of a cached item, qualified with an ID value. Send an HTTP request of the form:

GET /http://services.projectbamboo.org/bsp/resultsetcache/{id} HTTP/1.1

Parameter

Meaning

id

The unique identifier for the cached item as originally assigned when the item was cached. Usually provided to the client by either the Notification service or a Scholarly service

Response

On success, a response with a "200 OK" HTTP status code will be returned. The body of the HTTP message will contain the cached item in whatever format it was originally stored in the cache by a Scholarly service.

Parameter

Meaning

HTTP Header Content Type

The Media (aka Mime) type of the content returned in the body of the HTTP response

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the Get request:

Error (Status Code)

Meaning

Returned When

401

Unauthorized

The resource could not be created because the client submitting the request either has not provided authentication credentials, or authentication failed, or authorization has been refused for those credentials

404

Not Found

The resource requested for reading does not exist

500

Internal Server Error

A service error prevented the resource from being returned

SOA Layer API

Link to Javadoc here; or, include note: Javadoc will be linked once it is generated and published.

See Javadoc.

Create a Cached Item

/**
 * Adds an object to the cache.
 *
 * @param Identifier of the entity storing the object
 * @param Identifier of the service storing the object
 * @param Expiration date of the object after which it can be removed from the cache
 * @param Media Type (aka MIME type) of the object
 * @param InputStream from which to read the content to be cached
 * @return URI representing the ID of the cached object
 * @throws DocumentHandlerException; since the root cause of the exception is dependent
 * 	   on the representation abstraction, interrogate the exception message for the reason for the exception
 */
	URI createCacheItem(String creator, String service, Date expiry, MediaType mT, InputStream iS) throws DocumentHandlerException;

Read Cached Item Creation Date

/**
* Returns a cached item's creation date from the cache.
 *
 * @param Identifier of the cached object
 * @return Date item was added to the cache
 */
Date getCreated(URI id) throws FileNotFoundException;

Read Cached Item Created by User

/**
 * Returns a cached item's creator identifier from the cache.
 *
 * @param Identifier of the cached object
 * @return Identifier of the entity that stored the object
 */
String getCreator(URI id) throws FileNotFoundException;

Read Cached Item Created by Service

/**
 * Returns a cached item's service identifier from the cache.
 *
 * @param Identifier of the cached object
 * @return Identifier of the service that cached the object
 */
String getCreatedByService(URI id) throws FileNotFoundException;

Read Cached Item Media Type

/**
 * Returns a cached item's media type from the cache.
 *
 * @param Identifier of the cached object
 * @return Media Type (aka MIME type) of the object
 */
MediaType getMediaType(URI id) throws FileNotFoundException;

Read a Cached Item

/**
 * Returns a cached item.
 *
 * @param Identifier of the cached object
 * @return InputStream from which read the object in the cache
 */
InputStream getValue(URI id) throws FileNotFoundException;

Update a Cached Item

/**
 * Updates a cached item.
 *
 * @param Identifier of the cached object
 * @param InputStream from which to read the object into the cache
 * @param Identifier of the entity updating the object
 */
 void setValue(URI id, InputStream iS, String updator) throws FileNotFoundException;

Read Cached Item Expiry Date

/**
 * Returns a cached item's expiration date.
 *
 * @param Identifier of the cached object
 * @return Expiration date of the object after which it can be removed from the cache
 */
Date getExpiry(URI id) throws FileNotFoundException;

Update Cached Item Expiry Date

/**
 * Updates a cached item's expiration date.
 *
 * @param Identifier of the cached object
 * @param Expiration date of the object after which it can be removed from the cache
 * @param Identifier of the entity updating the object
 */
void setExpiry(URI id, Date expiry, String updator) throws FileNotFoundException;

Read Cached Item Last Updated on Date

/**
 * Returns a cached item's last updated date.
 *
 * @param Identifier of the cached object
 * @return Date the object was last modified in the cache
 */
 Date getUpdated(URI id) throws FileNotFoundException;

Read Cached Item Last Updated by

/**
 * Returns a cached item's last updated by entity.
 *
 * @param Identifier of the cached object
 * @return Identifier of the entity to last modify the object in cache
 */
String getUpdator(URI id) throws FileNotFoundException;

Delete a Cached Item

/**
 * Deletes a cached object from the cache.
 *
 * @param Identifier of the object
 */
void deleteCacheItem(URI id) throws FileNotFoundException;