Skip to main content
Jump to: navigation, search

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

(API)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= org.eclipse.smila.objectstore =
+
= Bundle org.eclipse.smila.objectstore =
<b>since SMILA 0.9.0</b>
+
  
[http://build.eclipse.org/rt/smila/javadoc/current/index.html?org/eclipse/smila/objectstore/package-summary.html org.eclipse.smila.objectstore JavaDoc]
+
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.
  
== ObjectStoreService ==
+
== org.eclipse.smila.objectstore.ObjectStoreService ==
=== API 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].
+
=== JavaDoc  ===
 +
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].  
  
=== 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.
  
== Description ==
+
The interface of ObjectStoreService is defined in <tt>org.eclipse.smila.objectstore.ObjectStoreService</tt>.  
An ObjectStoreService is mainly used in SMILA to store binary data during bulk processing. Data objects in this
+
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>.
+
== org.eclipse.smila.objectstore.StoreObject  ==
  
=== org.eclipse.smila.objectstore.StoreObject ===
+
=== JavaDoc  ===
 +
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  ===
 +
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  ===
 +
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.
  
=== org.eclipse.smila.objectstore ===
+
As a result, the content of <tt>StoreOutputStream</tt> will only be visible after <tt>close()</tt> has been called successfully.
  
=== Implementations ===
+
== 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].
 +
 
 +
=== Description  ===
 +
The individual exceptions are (in hierarchical order):
 +
 
 +
*<tt>ObjectStoreException</tt>: This is the base class of all object store exceptions. There are subclasses which give more details about the exception:
 +
**<tt>BadRequestException</tt>: Caused by invalid arguments or other conditions that render it impossible to perform the requested operation.
 +
***<tt>InvalidStoreNameException</tt>: The store name does not apply to the restrictions defined by the respective service implementation.
 +
***<tt>NoSuchObjectException</tt>: The requested object does not exist.
 +
***<tt>NoSuchStoreException</tt>: The requested store does not exist.
 +
***<tt>StoreExistsException</tt>: The store to be created already exists.
 +
**<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.
 +
 
 +
== Handlers in org.eclipse.smila.objectstore  ==
 +
=== JavaDoc  ===
 +
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].
 +
 
 +
=== Description  ===
 +
The following handlers exist:
 +
 
 +
==== ObjectStoreServiceHandler  ====
 +
This handler lists the stores handled by <tt>ObjectStoreService</tt>.
 +
 
 +
<b>Supported operations:</b>
 +
 
 +
*GET: Lists all stores handled by <tt>ObjectStoreService</tt>.
 +
 
 +
<b>Usage:</b>
 +
 
 +
*URL: <tt><nowiki>http://&lt;hostname&gt;:8080/smila/store/</nowiki></tt>
 +
*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>
 +
 
 +
<pre>
 +
GET http://&lt;hostname&gt;:8080/smila/store/
 +
200 OK
 +
{
 +
  "stores" : [ {
 +
    "store" : "store1",
 +
    "url" : "http://localhost:8080/smila/store/store1/"
 +
  }, {
 +
    "store" : "store2",
 +
    "url" : "http://localhost:8080/smila/store/store2/"
 +
  } ]
 +
}
 +
</pre>
 +
 
 +
==== StoreAdminHandler  ====
 +
This handler allows the stores handled by the <tt>ObjectStoreService</tt> to be managed or queried.
 +
 
 +
<b>Supported operations:</b>
 +
 
 +
*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.
 +
*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.
 +
 
 +
<b>Usage:</b>
 +
 
 +
*URL: <tt><nowiki>http://&lt;hostname&gt;:8080/smila/store/&lt;store-name&gt;/</nowiki></tt>.
 +
*Allowed methods:
 +
**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>
 +
 
 +
<pre>
 +
GET http://&lt;hostname&gt;:8080/smila/store/store1/?returnObjects=false
 +
 
 +
200 OK
 +
{
 +
  "storeName" : "store1",
 +
  "storeProperties" : {
 +
  },
 +
  "objectCount" : 1,
 +
  "size" : 25
 +
}
 +
</pre>
 +
 
 +
<pre>
 +
GET http://&lt;hostname&gt;: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"
 +
} ]
 +
}
 +
</pre>
 +
 
 +
==== StoreObjectHandler  ====
 +
 
 +
This handler allows to PUTting, GETting, or DELETing objects to or from a store.
 +
 
 +
<b>Supported operations:</b>
 +
 
 +
*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.
 +
 
 +
<b>Usage:</b>
 +
 
 +
*URL: <tt><nowiki>http://&lt;hostname&gt;:8080/smila/store/&lt;store-name&gt;/&lt;object-id&gt;/</nowiki></tt>.
 +
*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>
 +
 
 +
<pre>
 +
PUT http://&lt;hostname&gt;:8080/smila/store/store2/object1/
 +
{
 +
  "id": "object1",
 +
  "content": "my content."
 +
}
 +
200 OK
 +
</pre>
 +
 
 +
<pre>
 +
GET http://&lt;hostname&gt;:8080/smila/store/store2/object1/
 +
 
 +
200 OK
 +
{
 +
"id": "object1",
 +
"content": "my content."
 +
}
 +
</pre>
 +
 
 +
=== 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