Skip to main content
Jump to: navigation, search

Difference between revisions of "SMILA/Documentation/ObjectStore/Bundle org.eclipse.smila.objectstore"

 
(7 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= Bundle org.eclipse.smila.objectstore =
+
= Bundle org.eclipse.smila.objectstore =
<b>since SMILA 0.9.0</b>
+
  
This page only gives a rough overview of the components. Please refer to the JavaDoc for specific information:
+
This page gives only a rough overview of the components. Please refer to the [http://build.eclipse.org/rt/smila/javadoc/current/index.html?org/eclipse/smila/objectstore/package-summary.html JavaDoc] for specific information.
[http://build.eclipse.org/rt/smila/javadoc/current/index.html?org/eclipse/smila/objectstore/package-summary.html org.eclipse.smila.objectstore JavaDoc]
+
  
== org.eclipse.smila.objectstore.ObjectStoreService ==
+
== org.eclipse.smila.objectstore.ObjectStoreService ==
  
=== JavaDoc ===
+
=== JavaDoc ===
The JavaDoc for the <tt>ObjectStoreService</tt> API can be found in [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/ObjectStoreService.html org.eclipse.smila.objectstore.ObjectStoreService].
+
The JavaDoc for the <tt>ObjectStoreService</tt> API can be found at [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/ObjectStoreService.html org.eclipse.smila.objectstore.ObjectStoreService].  
  
=== Description ===
+
=== Description ===
An ObjectStoreService is mainly used in SMILA to store binary data during bulk processing. Data objects in this
+
In SMILA, the ObjectStoreService is mainly used to store binary data during bulk processing. Data objects pertaining to this service are for example large bulks of records that are to be processed in a single step by some worker.
service are for example big bulks of records that are to be processed in a single step by some worker.
+
  
The interface of ObjectStore services are defined in the interface <tt>org.eclipse.smila.objectstore.ObjectStoreService</tt>.
+
The interface of ObjectStoreService is defined in <tt>org.eclipse.smila.objectstore.ObjectStoreService</tt>.  
  
== org.eclipse.smila.objectstore.StoreObject ==
+
== org.eclipse.smila.objectstore.StoreObject ==
  
=== JavaDoc ===
+
=== JavaDoc ===
The JavaDoc for the <tt>StoreObject</tt> interface can be found in [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/StoreObject.html org.eclipse.smila.objectstore.StoreObject].
+
The JavaDoc for the <tt>StoreObject</tt> interface can be found at [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/StoreObject.html org.eclipse.smila.objectstore.StoreObject].  
  
=== Description ===
+
=== Description ===
A <tt>StoreObject</tt> contains information about an object in a store.
+
A <tt>StoreObject</tt> contains information about an object in a store. Common pieces of information provided by <tt>StoreObject</tt> are:
  
Common information are:
+
*ID (String)  
* ID (String)
+
**Contains the ID of the object. Can be used to request the object from the store.  
** the ID of the object. With this ID the object can be adressed within a store.
+
*Size (long)  
* size (long)
+
**Contains the size of the object in byte.
** the size (in bytes) of the object
+
*Timestamp (Date)  
* timestamp (Date)
+
**Contains the timestamp of the object. In the file system based object store implementation this is the time of the latest modification of the object.
** the timestamp of the file, in the filesystem based objectstore this is the time of the last modification of this object.
+
  
Any ObjectStore implementation might add additional information to the above.
+
In addition to the above, an ObjectStore implementation might add further information as required.
  
== org.eclipse.smila.objectstore.StoreOutputStream ==
+
== org.eclipse.smila.objectstore.StoreOutputStream ==
=== JavaDoc ===
+
=== JavaDoc ===
The JavaDoc for the <tt>StoreOutputStream</tt> interface can be found in [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/StoreOutputStream.html org.eclipse.smila.objectstore.StoreOutputStream].
+
The JavaDoc for the <tt>StoreOutputStream</tt> interface can be found at [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/StoreOutputStream.html org.eclipse.smila.objectstore.StoreOutputStream].  
  
=== Description ===
+
=== Description ===
The <tt>StoreOutputStream</tt> interface defines an extension of the <tt>java.io.OutputStream</tt> that allows a stream to be aborted (if it has not been closed yet). I.e. the content of the stream will not be visible but will be discarded.
+
The <tt>StoreOutputStream</tt> interface defines an extension of <tt>java.io.OutputStream</tt> that allows a stream to be aborted if it has not been closed yet, meaning the content of the stream will not be visible but discarded.
  
Thus the content of the StoreOutputStream will only be visible after <tt>close()</tt> is called sucessfully.
+
As a result, the content of <tt>StoreOutputStream</tt> will only be visible after <tt>close()</tt> has been called successfully.
  
 +
== Exceptions defined in org.eclipse.smila.objectstore  ==
 +
=== JavaDoc  ===
 +
The JavaDoc for the exceptions defined in <tt>org.eclipse.smila.objectstore</tt> can be found at [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/package-summary.html org.eclipse.smila.objectstore].
  
== Exceptions defined in org.eclipse.smila.objectstore ==
+
=== Description  ===
=== JavaDoc ===
+
The individual exceptions are (in hierarchical order):  
The JavaDoc for the Exceptions interface can be found in [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/package-summary.html org.eclipse.smila.objectstore].
+
  
=== Description ===
+
*<tt>ObjectStoreException</tt>: This is the base class of all object store exceptions. There are subclasses which give more details about the exception:  
The exceptions of the <tt>org.eclipse.smila.objectstore</tt> are:
+
**<tt>BadRequestException</tt>: Caused by invalid arguments or other conditions that render it impossible to perform the requested operation.
*<tt>ObjectStoreException</tt>
+
***<tt>InvalidStoreNameException</tt>: The store name does not apply to the restrictions defined by the respective service implementation.  
** the base class of the object store exceptions. There are subclasses to give more detailed information:
+
***<tt>NoSuchObjectException</tt>: The requested object does not exist.
*<tt>BadRequestException</tt>
+
***<tt>NoSuchStoreException</tt>: The requested store does not exist.
** caused by invalid arguments or other conditions that make it impossible to perform an operation
+
***<tt>StoreExistsException</tt>: The store to be created already exists.
*<tt>NoSuchObjectException</tt>
+
**<tt>ServiceUnavailableException</tt>: The request could not be fulfilled by the service due to some temporary condition. The client may retry the request shortly afterwards.
** the requested object does not exist
+
*<tt>InvalidStoreNameException</tt>
+
** the store name does not apply to the service implementation's restrictions for store names.
+
*<tt>NoSuchStoreException</tt>
+
** the requested store does not exist
+
*<tt>StoreExistsException</tt>
+
** the store to be created already exists
+
*<tt>ServiceUnavailableException</tt>
+
** due to some temporary conditions the request cannot be fulfilles by the service. The client can retry a short period of time later.
+
  
The hierarchie of the exception is as follows:
+
== Handlers in org.eclipse.smila.objectstore  ==
*<tt>ObjectStoreException</tt>
+
=== JavaDoc  ===
**<tt>BadRequestException</tt>
+
The JavaDoc for the handlers of the <tt>org.eclipse.smila.objectstore</tt> bundle can be found at [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/httphandler/package-summary.html org.eclipse.smila.objectstore.httphandler].
***<tt>InvalidStoreNameException</tt>
+
***<tt>NoSuchObjectException</tt>
+
***<tt>NoSuchStoreException</tt>
+
***<tt>StoreExistsException</tt>
+
**<tt>ServiceUnavailableException</tt>
+
  
== org.eclipse.smila.objectstore handlers ==
+
=== Description  ===
=== JavaDoc ===
+
The following handlers exist:  
The JavaDoc for the <tt>org.eclipse.smila.objectstore</tt> bundle's handlers can be found in [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/httphandler/package-summary.html org.eclipse.smila.objectstore.httphandler].
+
  
=== Description ===
+
==== ObjectStoreServiceHandler  ====
The following handlers exist:
+
This handler lists the stores handled by <tt>ObjectStoreService</tt>.
  
==== ObjectStoreServiceHandler ====
+
<b>Supported operations:</b>
This handler lists the stores handled by the <tt>ObjectStoreService</tt>.
+
  
* URL: <pre>http://<hostname>:8080/smila/store/</pre>.
+
*GET: Lists all stores handled by <tt>ObjectStoreService</tt>.
* Allowed methods: GET, no further parameters or request body
+
 
* Response Status Codes:
+
<b>Usage:</b>
** 200 OK: Successful execution
+
 
** 500 INTERNAL SERVER ERROR: An internal error occurred
+
*URL: <tt><nowiki>http://&lt;hostname&gt;:8080/smila/store/</nowiki></tt>
** 503 SERVICE UNAVAILABLE: The service is currently unable to perform the requested operation, please retry later.
+
*Allowed methods:
 +
**GET (no further URL parameters and no request body allowed)
 +
*Response status codes:  
 +
**200 OK: Upon successful execution.
 +
**500 INTERNAL SERVER ERROR: An internal error occurred.
 +
**503 SERVICE UNAVAILABLE: The service is currently unable to perform the requested operation, please retry later.
 +
 
 +
<b>Example:</b>
  
Example:
 
 
<pre>
 
<pre>
GET http://<hostname>:8080/smila/store/
+
GET http://&lt;hostname&gt;:8080/smila/store/
 
200 OK
 
200 OK
 
{
 
{
Line 106: Line 94:
 
</pre>
 
</pre>
  
==== StoreAdminHandler ====
+
==== StoreAdminHandler ====
This handler allows the stores handled by the <tt>ObjectStoreService</tt> to be managed or queried.
+
This handler allows the stores handled by the <tt>ObjectStoreService</tt> to be managed or queried.  
  
Operations:
+
<b>Supported operations:</b>
* GET: returns the store information, without the optional parameter <pre>returnObjects</pre> set to <pre>false</pre> also information on the contained objects will be returned
+
* PUT: creates a new store, optionally parameters can be sent with the PUT command as a JSON body.
+
* DELETE: deletes a store (if the store does not exist, it will be ignored and 200 OK will be returned)
+
  
* URL: <pre>http://<hostname>:8080/smila/store/<store-name></pre>.
+
*GET: Returns the store information. Without the optional parameter <tt>returnObjects</tt> set to <tt>false</tt> also information on the contained objects will be returned.
* Allowed methods: GET, with an optional parameter <pre>returnObjects</pre>, PUT, DELETE
+
*PUT: Creates a new store. Optional parameters can be sent as part of a JSON body.
* Response Status Codes:
+
*DELETE: Deletes a store. If the store does not exist, it will be ignored and 200 OK will be returned.
** 200 OK: Successful execution (GET, DELETE)
+
 
** 201 CREATED: Successful creation of a store (PUT)
+
<b>Usage:</b>
** 400 BAD REQUEST: the user provided information that lead to an error, e.g. an invalid store name, or tried to create a store that already existed, etc.
+
 
** 404 NOT FOUND: the requested store could not be found
+
*URL: <tt><nowiki>http://&lt;hostname&gt;:8080/smila/store/&lt;store-name&gt;/</nowiki></tt>.  
** 500 INTERNAL SERVER ERROR: An internal error occurred
+
*Allowed methods:
** 503 SERVICE UNAVAILABLE: The service is currently unable to perform the requested operation, please retry later.
+
**GET (with optional URL parameter <tt>returnObjects</tt>)
 +
**PUT
 +
**DELETE  
 +
*Response status codes:  
 +
**200 OK: Upon successful execution (GET, DELETE).
 +
**201 CREATED: Upon successful creation of a store (PUT).
 +
**400 BAD REQUEST: The calling client provided some information that lead to an error, e.g. an invalid store name, or tried to create a store that already exists etc.  
 +
**404 NOT FOUND: The requested store could not be found.
 +
**500 INTERNAL SERVER ERROR: An internal error occurred.
 +
**503 SERVICE UNAVAILABLE: The service is currently unable to perform the requested operation, please retry later.
 +
 
 +
<b>Examples:</b>
  
Examples:
 
 
<pre>
 
<pre>
GET http://<hostname>:8080/smila/store/store1?returnObjects=false
+
GET http://&lt;hostname&gt;:8080/smila/store/store1/?returnObjects=false
 +
 
 
200 OK
 
200 OK
 
{
 
{
Line 138: Line 134:
  
 
<pre>
 
<pre>
GET http://<hostname>:8080/smila/store/store1
+
GET http://&lt;hostname&gt;:8080/smila/store/store1/
 +
 
 
200 OK
 
200 OK
 
{
 
{
  "storeName" : "store1",
+
"storeName" : "store1",
  "storeProperties" : {
+
"storeProperties" : {
  },
+
},
  "objectCount" : 1,
+
"objectCount" : 1,
 +
"size" : 25,
 +
"objects" : [ {
 +
  "id" : "sample-object",
 
   "size" : 25,
 
   "size" : 25,
   "objects" : [ {
+
   "timestamp" : "2011-06-20T17:12:35.417+0200"
    "id" : "sample-object",
+
} ]
    "size" : 25,
+
    "timestamp" : "2011-06-20T17:12:35.417+0200"
+
  } ]
+
 
}
 
}
</pre>
+
</pre>  
  
==== StoreObjectHandler ====
+
==== StoreObjectHandler ====
  
This handler allows to PUT, GET or DELETE objects to or from a store.
+
This handler allows to PUTting, GETting, or DELETing objects to or from a store.  
  
Operations:
+
<b>Supported operations:</b>
* GET: retrieves an object from a store.
+
* PUT: puts a new object (or updates an existing one) in a store. The content of the object is sent with the PUT command as a JSON body.
+
* DELETE: deletes an object from a store (if the object does not exist, it will be ignored and 200 OK will be returned)
+
  
* URL: <pre>http://<hostname>:8080/smila/store/<store-name></pre>.
+
*GET: Retrieves an object from a store.
* Allowed methods: GET, PUT, DELETE
+
*PUT: Puts a new object to or updates an existing one in a store. The content of the object is sent with the PUT command as a JSON body.
* Response Status Codes:
+
*DELETE: Deletes an object from a store. If the object does not exist, it will be ignored and 200 OK will be returned.
** 200 OK: Successful execution
+
 
** 400 BAD REQUEST: the user provided information that lead to an error, e.g. an invalid store or object name etc.
+
<b>Usage:</b>
** 404 NOT FOUND: the requested object (or the store) could not be found
+
 
** 500 INTERNAL SERVER ERROR: An internal error occurred
+
*URL: <tt><nowiki>http://&lt;hostname&gt;:8080/smila/store/&lt;store-name&gt;/&lt;object-id&gt;/</nowiki></tt>.  
** 503 SERVICE UNAVAILABLE: The service is currently unable to perform the requested operation, please retry later.
+
*Allowed methods
 +
**GET
 +
**PUT
 +
**DELETE  
 +
*Response status codes:  
 +
**200 OK: Upon successful execution.
 +
**400 BAD REQUEST: The client provided information that lead to an error, e.g. an invalid store or object name etc.  
 +
**404 NOT FOUND: The requested object (or the store) could not be found.
 +
**500 INTERNAL SERVER ERROR: An internal error occurred.
 +
**503 SERVICE UNAVAILABLE: The service is currently unable to perform the requested operation, please retry later.
 +
 
 +
<b>Examples:</b>
  
Examples:
 
 
<pre>
 
<pre>
PUT http://<hostname>:8080/smila/store/store2/object1
+
PUT http://&lt;hostname&gt;:8080/smila/store/store2/object1/
 
{
 
{
 
   "id": "object1",
 
   "id": "object1",
Line 183: Line 187:
  
 
<pre>
 
<pre>
GET http://<hostname>:8080/smila/store/store2/object1
+
GET http://&lt;hostname&gt;:8080/smila/store/store2/object1/
 +
 
 
200 OK
 
200 OK
 
{
 
{
  "id": "object1",
+
"id": "object1",
  "content": "my content."
+
"content": "my content."
 
}
 
}
</pre>
+
</pre>  
 
+
 
+
  
=== Implementations ===
+
=== Implementations ===
 
A file system based implementation can be found in package [[SMILA/Documentation/ObjectStore/filesystem/SimpleObjectStoreService|org.eclipse.smila.objectstore.filesystem]].
 
A file system based implementation can be found in package [[SMILA/Documentation/ObjectStore/filesystem/SimpleObjectStoreService|org.eclipse.smila.objectstore.filesystem]].

Latest revision as of 11:40, 23 January 2012

Bundle org.eclipse.smila.objectstore

This page gives only a rough overview of the components. Please refer to the JavaDoc for specific information.

org.eclipse.smila.objectstore.ObjectStoreService

JavaDoc

The JavaDoc for the ObjectStoreService API can be found at org.eclipse.smila.objectstore.ObjectStoreService.

Description

In SMILA, the ObjectStoreService is mainly used to store binary data during bulk processing. Data objects pertaining to this service are for example large bulks of records that are to be processed in a single step by some worker.

The interface of ObjectStoreService is defined in org.eclipse.smila.objectstore.ObjectStoreService.

org.eclipse.smila.objectstore.StoreObject

JavaDoc

The JavaDoc for the StoreObject interface can be found at org.eclipse.smila.objectstore.StoreObject.

Description

A StoreObject contains information about an object in a store. Common pieces of information provided by StoreObject are:

  • ID (String)
    • Contains the ID of the object. Can be used to request the object from the store.
  • Size (long)
    • Contains the size of the object in byte.
  • Timestamp (Date)
    • Contains the timestamp of the object. In the file system based object store implementation this is the time of the latest modification of the object.

In addition to the above, an ObjectStore implementation might add further information as required.

org.eclipse.smila.objectstore.StoreOutputStream

JavaDoc

The JavaDoc for the StoreOutputStream interface can be found at org.eclipse.smila.objectstore.StoreOutputStream.

Description

The StoreOutputStream interface defines an extension of java.io.OutputStream that allows a stream to be aborted if it has not been closed yet, meaning the content of the stream will not be visible but discarded.

As a result, the content of StoreOutputStream will only be visible after close() has been called successfully.

Exceptions defined in org.eclipse.smila.objectstore

JavaDoc

The JavaDoc for the exceptions defined in org.eclipse.smila.objectstore can be found at org.eclipse.smila.objectstore.

Description

The individual exceptions are (in hierarchical order):

  • ObjectStoreException: This is the base class of all object store exceptions. There are subclasses which give more details about the exception:
    • BadRequestException: Caused by invalid arguments or other conditions that render it impossible to perform the requested operation.
      • InvalidStoreNameException: The store name does not apply to the restrictions defined by the respective service implementation.
      • NoSuchObjectException: The requested object does not exist.
      • NoSuchStoreException: The requested store does not exist.
      • StoreExistsException: The store to be created already exists.
    • ServiceUnavailableException: The request could not be fulfilled by the service due to some temporary condition. The client may retry the request shortly afterwards.

Handlers in org.eclipse.smila.objectstore

JavaDoc

The JavaDoc for the handlers of the org.eclipse.smila.objectstore bundle can be found at org.eclipse.smila.objectstore.httphandler.

Description

The following handlers exist:

ObjectStoreServiceHandler

This handler lists the stores handled by ObjectStoreService.

Supported operations:

  • GET: Lists all stores handled by ObjectStoreService.

Usage:

  • URL: http://<hostname>:8080/smila/store/
  • Allowed methods:
    • GET (no further URL parameters and no request body allowed)
  • Response status codes:
    • 200 OK: Upon successful execution.
    • 500 INTERNAL SERVER ERROR: An internal error occurred.
    • 503 SERVICE UNAVAILABLE: The service is currently unable to perform the requested operation, please retry later.

Example:

GET http://<hostname>:8080/smila/store/
200 OK
{
  "stores" : [ {
    "store" : "store1",
    "url" : "http://localhost:8080/smila/store/store1/"
  }, {
    "store" : "store2",
    "url" : "http://localhost:8080/smila/store/store2/"
  } ]
}

StoreAdminHandler

This handler allows the stores handled by the ObjectStoreService to be managed or queried.

Supported operations:

  • GET: Returns the store information. Without the optional parameter returnObjects set to false also information on the contained objects will be returned.
  • PUT: Creates a new store. Optional parameters can be sent as part of a JSON body.
  • DELETE: Deletes a store. If the store does not exist, it will be ignored and 200 OK will be returned.

Usage:

  • URL: http://<hostname>:8080/smila/store/<store-name>/.
  • Allowed methods:
    • GET (with optional URL parameter returnObjects)
    • PUT
    • DELETE
  • Response status codes:
    • 200 OK: Upon successful execution (GET, DELETE).
    • 201 CREATED: Upon successful creation of a store (PUT).
    • 400 BAD REQUEST: The calling client provided some information that lead to an error, e.g. an invalid store name, or tried to create a store that already exists etc.
    • 404 NOT FOUND: The requested store could not be found.
    • 500 INTERNAL SERVER ERROR: An internal error occurred.
    • 503 SERVICE UNAVAILABLE: The service is currently unable to perform the requested operation, please retry later.

Examples:

GET http://<hostname>:8080/smila/store/store1/?returnObjects=false

200 OK
{
  "storeName" : "store1",
  "storeProperties" : {
  },
  "objectCount" : 1,
  "size" : 25
}
GET http://<hostname>:8080/smila/store/store1/

200 OK
{
 "storeName" : "store1",
 "storeProperties" : {
 },
 "objectCount" : 1,
 "size" : 25,
 "objects" : [ {
  "id" : "sample-object",
  "size" : 25,
  "timestamp" : "2011-06-20T17:12:35.417+0200"
 } ]
}

StoreObjectHandler

This handler allows to PUTting, GETting, or DELETing objects to or from a store.

Supported operations:

  • GET: Retrieves an object from a store.
  • PUT: Puts a new object to or updates an existing one in a store. The content of the object is sent with the PUT command as a JSON body.
  • DELETE: Deletes an object from a store. If the object does not exist, it will be ignored and 200 OK will be returned.

Usage:

  • URL: http://<hostname>:8080/smila/store/<store-name>/<object-id>/.
  • Allowed methods
    • GET
    • PUT
    • DELETE
  • Response status codes:
    • 200 OK: Upon successful execution.
    • 400 BAD REQUEST: The client provided information that lead to an error, e.g. an invalid store or object name etc.
    • 404 NOT FOUND: The requested object (or the store) could not be found.
    • 500 INTERNAL SERVER ERROR: An internal error occurred.
    • 503 SERVICE UNAVAILABLE: The service is currently unable to perform the requested operation, please retry later.

Examples:

PUT http://<hostname>:8080/smila/store/store2/object1/
{
  "id": "object1",
  "content": "my content."
}
200 OK
GET http://<hostname>:8080/smila/store/store2/object1/

200 OK
{
 "id": "object1",
 "content": "my content."
}

Implementations

A file system based implementation can be found in package org.eclipse.smila.objectstore.filesystem.

Back to the top