Skip to content

StorageHandler

Jump to bottom Edit New page
larsb edited this page Mar 14, 2015 · 27 revisions

The StorageHandler provides a wrapper to access different storage implementations for client-side (guidance) apps in Go-Lab. Currently, a MemoryStorageHandler (storing resources in memory) and a LocalStorageHandler (storing resources in the browser's local storage) are implemented; a "vault" storage (storing resources to Graasp) will follow.

What is a resource?

In Go-Lab, in the context of the StorageHandler, a resource is a data artefact created by a guidance app or a lab. Examples are a set of hypotheses, a concept map, or a numerical dataset. A resource has a unique identifier, a metadata section (based on information from the MetadataHandler), and a content section, which contains arbitrary, tool specific data in JSON format. An example resource can be found [here](example resource).

Using the StorageHandler is closely connected to the MetadataHandler, which stores and gives access to information like username, object name and type, id of the current ILS etc., which is needed by the StorageHandler to create the object's metadata.

Creating a StorageHandler

When creating a StorageHandler object, you can choose between a MemoryStorageHandler and a LocalStorageHandler (and a VaultStorageHandler in future). All three handlers require a MetadataHandler at construction time.

var storageHandler = new golab.ils.storage.MemoryStorageHandler(metadataHandler)

or

var storageHandler = new golab.ils.storage.LocalStorageHandler(metadataHandler)

API

#### getMetadataHandler(): MetadataHandler Returns the MetadataHandler.
#### readResource(resourceId: string, callback: function(error: string, resource: object): void): void Returns a resource through a callback, identified by its resourceId.

`resourceId: string` The (unique) identifier of the resource to be retrieved.
`callback: function(error: string, resource: object):void` A callback function to return the result. On success, 'error' is undefined, else 'resource' is undefined.
#### createResource(content: object, callback: function(error: string, resource: object):void): void Creates a resource by bundling the given content and metadata, and stores it.

`content: object` An arbitrary JSON representation of the data to be stored.
`callback: function(error: string, resource:object):void` A callback function to return the result. On success, 'error' is undefined, else 'resource' is undefined. The 'resource' bundles the 'content', metadata from the MetadataHandler, a new resource identifier (accessible through resource.id, a version 4 random UUID, or possibly set by the underlying storage implementation, see example below) and the creation date.

#### updateResource(resourceId: string, content: object, callback: function(error: string, resource: object): void): void Updates a resource with new content.

`resourceId: string` The identifier of the resource to be updated.
`content: object` The new content of the resource.
`callback: function(error: string, resource: object): void` A callback function to return the result. On success, 'error' is undefined, else 'resource' is undefined.
#### deleteResource(resourceId: string, callback: function(error: string, resource: object): void): void Deletes a resource with a given resourceUd.

`resourceId: string` The identifier of the resource to be deleted.
`callback: function(error: string, resource: object): void` A callback function to return the result. On success, 'error' is undefined, else 'resource' is undefined.
#### listResourceMetaDatas(callback: function(error: string, metadatas: object[]): void): void Returns an array with all available resource metadata (in an ILS).

`callback(error: string, metadatas: object[]): void` A callback function to handle the returned result. On success, 'error' is undefined, else 'metadatas' is undefined. The returned array contains objects of the form {id: "...", metadata: {...}}, where the metadata sub-objects correspond with the metadata sections of the available resources.
#### listResourceIds(callback: function(error: string, ids: string[]): void): void Returns an array of all available resource identifiers.

`callback: function(error:string, ids: string[]): void` A callback function to handle the returned result. On success, 'error' is undefined, else 'ids' is undefined. 'ids' contains all available resource identifiers of the current storage.
#### resourceExists(resourceId: string, callback: function(error: string, exists: boolean): void): void Checks if a resource with a given identifier exists.

`resourceId: string` The identifier of the resource to check.
`callback: function(error: string, exists: boolean): void` A callback function to handle the returned result. On a successful call, 'error' is undefined, else 'exists' is undefined. 'exists' is 'true', if a resource with the given resource identifier exists, 'false' otherwise.
#### readLatestResource(resourceType: string, callback: function(error: string, resource: object): void): void A convenience function that returns the latest stored resource of a given type. This function searches for resources where 'metadata.target.objectType' equals the parameter 'resourceType', and returns the latest matching resource. If 'resourceType' is left 'undefined', any type will match.

`objectType: string` The type of the resource (cf. metadata.target.objectType).
`callback: function(error: string, resource: object): void` A callback function to return the result. On success, 'error' is undefined, else 'resource' is undefined.
#### configureFilters(filterForResourceType: boolean, filterForUser: boolean, filterForProvider: boolean, filterForAppId: boolean): void This function configures (i.e. turns on/off) the internal filters which are used when returning the array of resource metadata from 'listResourceMetaDatas'. The filters compare the resourceType, the userId, the providerId and/or the addId with the values in the 'MetadataHandler'. If activated, only matching resources are returned.
### Usage example 
// assuming we have created a 'metadataHandler' earlier...
var storageHandler = new golab.ils.storage.LocalStorageHandler(metadataHandler);

// generating a JSON respresentation of my document/model/resource
var myDocumentJSON = ....;


storageHandler.createResource(myDocumentJSON, function(error, resource) {
if (error != undefined) {
console.warn("something went wrong:");
console.warn(error);
} else {
console.log("the resource has been created successfully.");
console.log("id:"+resource.id);
}
});

Notes

  • A tool using the StorageHandler is responsible to propagate potential changes in the metadata to the MetadataHandler. E.g., if the document name (metadata.target.displayName) changes during a save operation, the tool needs to update this information in the MetadataHandler. If a resource is retrieved from the StorageHandler, and if this resource will be the main working document for a tool, the retrieved metadata has to be set in the MetadataHandler. This is necessary for a consistent handling of resource metadata (which is also being used in e.g. the ActionLogger).
Add a custom footer
Add a custom sidebar
Clone this wiki locally