org.eclipse.smila.objectstore
Interface ObjectStoreService

All Known Implementing Classes:

SimpleObjectStoreService

public interface ObjectStoreService

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. Of course, the ObjectStoreService can also be used to store small objects like record attachments or other auxiliary data. Apart from reading and writing objects (either as blobs or using streams), blobs can be appended to objects, objects can be removed, and it is possible to get a list of descriptions (StoreObject) about the current objects in a store, optionally filtered by a prefix string on the object ID. Objects are identified by a String identifiers. All implementations must support these chars::

• ASCII characters: 'a'-'z', 'A'-'Z'
• numbers: '0'-'9'
• underscores, dashes and slashes: '_', '-', '/'

Specific implementations may allow more characters. The ObjectStoreService manages objects in stores. A store can be thought of as a container of objects of the same kind. A store must be created before it can be used to store and fetch objects. In some implementations of this service it is possible that different stores have different properties, for example concerning the reliability of this store like replication of the data objects. Such properties must be specified at creation time, or the service will create a store with default properties. The properties that can be used are dependant on the specific service implementation.

Field Summary

static java.lang.String	KEY_OBJECT_COUNT key of store object count of the store info.
static java.lang.String	KEY_OBJECTS key of store objects of the store info.
static java.lang.String	KEY_SIZE key of store size of the store info.
static java.lang.String	KEY_STORE_NAME key of store name of the store info.
static java.lang.String	KEY_STORE_PROPERTIES key of store properties of the store info.

Method Summary

void	appendToObject(java.lang.String storeName, java.lang.String objectId, byte[] data) append the data to the given store and object.
void	clearStore(java.lang.String storeName) Remove all objects from the named store.
long	countStoreObjects(java.lang.String storeName, java.lang.String objectIdPrefix) Count all current objects in the named store that have an ID that starts with the given prefix.
void	createStore(java.lang.String storeName, AnyMap storeProperties) Creates a store with the given configuration properties.
void	ensureStore(java.lang.String storeName) Ensures that a store with the given name existing, regardless of the exact configuration properties.
boolean	existsObject(java.lang.String storeName, java.lang.String objectId)
boolean	existsStore(java.lang.String storeName)
void	finishObject(java.lang.String storeName, java.lang.String objectId) Prevent further append calls to this object.
byte[]	getObject(java.lang.String storeName, java.lang.String objectId) get the complete content of an object.
StoreObject	getObjectInfo(java.lang.String storeName, java.lang.String objectId) get information about a single object.
java.util.Collection<java.lang.String>	getPrefixes(java.lang.String storeName, java.lang.String objectIdPrefix) Get all prefixes of objectIds (this can also include complete ObjectIds) in the named store that have an ID that starts with the given prefix until the next separator (/).
AnyMap	getStoreInfo(java.lang.String storeName, boolean includeObjectInfos) get a description of the current store state to be displayed in administration tools (e.g. by an Http handler).
java.util.Collection<java.lang.String>	getStoreNames()
java.util.Collection<StoreObject>	getStoreObjectInfos(java.lang.String storeName) Get information about all current objects in the named store.
java.util.Collection<StoreObject>	getStoreObjectInfos(java.lang.String storeName, java.lang.String objectIdPrefix) Get information about all current objects in the named store that have an ID that starts with the given prefix.
AnyMap	getStoreProperties(java.lang.String storeName) get configuration properties of the named store.
boolean	isValidStoreName(java.lang.String storeName) Check if the argument is a valid store name for this service implementation.
void	putObject(java.lang.String storeName, java.lang.String objectId, byte[] data) write the data to the given store and object.
java.io.InputStream	readObject(java.lang.String storeName, java.lang.String objectId) get a stream for reading the object content.
void	removeAllStores() remove all stores from the service.
void	removeObject(java.lang.String storeName, java.lang.String objectId) remove the object from the store.
void	removeObjects(java.lang.String storeName, java.lang.String objectIdPrefix) remove all objects from the store with an ID starting with the given prefix.
void	removeStore(java.lang.String storeName) remove a store completely, if it exists.
StoreOutputStream	writeObject(java.lang.String storeName, java.lang.String objectId) open a stream for creating a data object and writing it.

Field Detail

KEY_STORE_NAME

static final java.lang.String KEY_STORE_NAME

key of store name of the store info.

See Also:

Constant Field Values

KEY_STORE_PROPERTIES

static final java.lang.String KEY_STORE_PROPERTIES

key of store properties of the store info.

See Also:

Constant Field Values

KEY_OBJECT_COUNT

static final java.lang.String KEY_OBJECT_COUNT

key of store object count of the store info.

See Also:

Constant Field Values

KEY_SIZE

static final java.lang.String KEY_SIZE

key of store size of the store info.

See Also:

Constant Field Values

KEY_OBJECTS

static final java.lang.String KEY_OBJECTS

key of store objects of the store info.

See Also:

Constant Field Values

Method Detail

getStoreNames

java.util.Collection<java.lang.String> getStoreNames()
                                                     throws ObjectStoreException

Returns:

the names of all currently existing stores.

Throws:

ObjectStoreException - on error.

createStore

void createStore(java.lang.String storeName,
                 AnyMap storeProperties)
                 throws ObjectStoreException

Creates a store with the given configuration properties. If properties are null, the service chooses default properties on its own.

Parameters:

storeName - name of store to create

storeProperties - store configuration, may be null.

Throws:

InvalidStoreNameException - if the store name is not valid.

StoreExistsException - if a store with this name exists already.

ObjectStoreException - other errors.

ensureStore

void ensureStore(java.lang.String storeName)
                 throws ObjectStoreException

Ensures that a store with the given name existing, regardless of the exact configuration properties. If the store does not exist yet, it is created with some default properties.

Throws:

InvalidStoreNameException - if the store name is not valid.

ObjectStoreException - other errors

isValidStoreName

boolean isValidStoreName(java.lang.String storeName)

Check if the argument is a valid store name for this service implementation.

Returns:

true if the string can be used as a store name, else false.

existsStore

boolean existsStore(java.lang.String storeName)
                    throws ObjectStoreException

Returns:

true if a store with this name exists, else false.

Throws:

InvalidStoreNameException - if the store name is not valid.

ObjectStoreException - some error.

removeStore

void removeStore(java.lang.String storeName)
                 throws ObjectStoreException

remove a store completely, if it exists. All objects in this store will be lost. No exception is thrown if the store does not exists currently.

Throws:

InvalidStoreNameException - if the store name is not valid.

ObjectStoreException - error deleting the store.

getStoreObjectInfos

java.util.Collection<StoreObject> getStoreObjectInfos(java.lang.String storeName)
                                                      throws ObjectStoreException

Get information about all current objects in the named store.

Returns:

list of StoreObjects

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - error determining the object info list.

getStoreObjectInfos

java.util.Collection<StoreObject> getStoreObjectInfos(java.lang.String storeName,
                                                      java.lang.String objectIdPrefix)
                                                      throws ObjectStoreException

Get information about all current objects in the named store that have an ID that starts with the given prefix. If recursive is true all objects within sub directories are returned, otherwise only the top level elements of the store.

Returns:

list of StoreObjects with IDs matching the prefix.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - error determining the object info list.

countStoreObjects

long countStoreObjects(java.lang.String storeName,
                       java.lang.String objectIdPrefix)
                       throws ObjectStoreException

Count all current objects in the named store that have an ID that starts with the given prefix. If recursive is true all objects within sub directories are returned, otherwise only the top level elements of the store.

Returns:

list of StoreObjects with IDs matching the prefix.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - error determining the object info list.

getPrefixes

java.util.Collection<java.lang.String> getPrefixes(java.lang.String storeName,
                                                   java.lang.String objectIdPrefix)
                                                   throws ObjectStoreException

Get all prefixes of objectIds (this can also include complete ObjectIds) in the named store that have an ID that starts with the given prefix until the next separator (/). The returned list contains the full qualified objectIds.

Returns:

list of Strings with IDs matching the prefix.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - error determining the object info list.

getStoreProperties

AnyMap getStoreProperties(java.lang.String storeName)
                          throws ObjectStoreException

get configuration properties of the named store.

Returns:

configuration properties.

Throws:

InvalidStoreNameException - if the store name is not valid.

ObjectStoreException - error reading store properties.

getStoreInfo

AnyMap getStoreInfo(java.lang.String storeName,
                    boolean includeObjectInfos)
                    throws ObjectStoreException

get a description of the current store state to be displayed in administration tools (e.g. by an Http handler). It should include the store properties and the complete object list, if includeObjectInfos == true. It can contain additional information.

Parameters:

includeObjectInfos - set to true to include the list of current object infos in the result.

Returns:

store state information

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - error reading store properties.

getObject

byte[] getObject(java.lang.String storeName,
                 java.lang.String objectId)
                 throws ObjectStoreException

get the complete content of an object. Use only if you are sure that the object is small enough to fit in memory.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

NoSuchObjectException - if the object does not exist

ObjectStoreException - other error reading the object

readObject

java.io.InputStream readObject(java.lang.String storeName,
                               java.lang.String objectId)
                               throws ObjectStoreException

get a stream for reading the object content.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

NoSuchObjectException - if the object does not exist

ObjectStoreException - other error reading the object

putObject

void putObject(java.lang.String storeName,
               java.lang.String objectId,
               byte[] data)
               throws ObjectStoreException

write the data to the given store and object. If the object exists already, it is overwritten.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - other error reading the object

appendToObject

void appendToObject(java.lang.String storeName,
                    java.lang.String objectId,
                    byte[] data)
                    throws ObjectStoreException

append the data to the given store and object. If the object exists already, the new data is appended at the end of the object. If the object does not exist already, it is created.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - other error reading the object

finishObject

void finishObject(java.lang.String storeName,
                  java.lang.String objectId)
                  throws ObjectStoreException

Prevent further append calls to this object. It does not prevent the object from being removed. It is irrelevant for objects that were not created using appendToObject(String, String, byte[]). The operation is optional: An implementation may choose not to support it, in this case it should just ignore the call and not throw an exception. However, in some pathological situations this may lead to data loss, because data could be appended for processing when the object is already considered as finished and the next processing steps have been started and miss the latest appends.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException

writeObject

StoreOutputStream writeObject(java.lang.String storeName,
                              java.lang.String objectId)
                              throws ObjectStoreException

open a stream for creating a data object and writing it. If the object exists already, it is overwritten. The object will not become visible in the store until the stream is closed. To prevent the object from becoming visible then (because some error has occurred and the object is invalid), call StoreOutputStream.abort() before closing the stream.

Returns:

stream for writing data to the object.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - error creating the object.

existsObject

boolean existsObject(java.lang.String storeName,
                     java.lang.String objectId)
                     throws ObjectStoreException

Returns:

true if object exists in store, else false.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - error checking object existence.

removeObject

void removeObject(java.lang.String storeName,
                  java.lang.String objectId)
                  throws ObjectStoreException

remove the object from the store. No exception is thrown if the object does not exist in the store currently (however, there is one if the store itself does not exist).

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - error removing the object.

removeObjects

void removeObjects(java.lang.String storeName,
                   java.lang.String objectIdPrefix)
                   throws ObjectStoreException

remove all objects from the store with an ID starting with the given prefix.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist

ObjectStoreException - error removing the object.

getObjectInfo

StoreObject getObjectInfo(java.lang.String storeName,
                          java.lang.String objectId)
                          throws ObjectStoreException

get information about a single object.

Returns:

information about the object.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist.

NoSuchObjectException - if the object does not exist in the store.

ObjectStoreException - error reading the object info.

removeAllStores

void removeAllStores()
                     throws ObjectStoreException

remove all stores from the service. All data will be lost, no store will exist anymore.

Throws:

ObjectStoreException - error removing the data.

clearStore

void clearStore(java.lang.String storeName)
                throws ObjectStoreException

Remove all objects from the named store. The store itself will continue to exist with the same properties as before, it will just be empty as if newly created.

Throws:

InvalidStoreNameException - if the store name is not valid.

NoSuchStoreException - if the store does not exist.

ObjectStoreException - error clearing the store.