Skip to main content
Jump to: navigation, search

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

(New page: = org.eclipse.smila.objectstore = <b>since SMILA 0.9.0</b> == ObjectStoreService == === API === <source lang="java"> public interface ObjectStoreService { /** key of store name of the...)
 
(API)
Line 5: Line 5:
 
=== API ===
 
=== API ===
  
<source lang="java">
+
The API for the </tt>ObjectStoreService</tt> can be found in [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/ObjectStoreService.html org.eclipse.smila.objectstore.ObjectStoreService]
public interface ObjectStoreService {
+
 
+
  /** key of store name of the store info. */
+
  String KEY_STORE_NAME = "storeName";
+
 
+
  /** key of store properties of the store info. */
+
  String KEY_STORE_PROPERTIES = "storeProperties";
+
 
+
  /** key of store object count of the store info. */
+
  String KEY_OBJECT_COUNT = "objectCount";
+
 
+
  /** key of store size of the store info. */
+
  String KEY_SIZE = "size";
+
 
+
  /** key of store objects of the store info. */
+
  String KEY_OBJECTS = "objects";
+
 
+
  // store handling methods
+
 
+
  /**
+
  * @return the names of all currently existing stores.
+
  * @throws ObjectStoreException
+
  *          on error.
+
  */
+
  Collection<String> getStoreNames() throws ObjectStoreException;
+
 
+
  /**
+
  * Creates a store with the given configuration properties. If properties are <code>null</code>, the service chooses
+
  * default properties on its own.
+
  *
+
  * @param storeName
+
  *          name of store to create
+
  * @param storeProperties
+
  *          store configuration, may be null.
+
  *
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws StoreExistsException
+
  *          if a store with this name exists already.
+
  * @throws ObjectStoreException
+
  *          other errors.
+
  */
+
  void createStore(String storeName, AnyMap storeProperties) 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.
+
  * @throws ObjectStoreException
+
  *          other errors
+
  */
+
  void ensureStore(String storeName) throws ObjectStoreException;
+
 
+
  /**
+
  * Check if the argument is a valid store name for this service implementation.
+
  *
+
  * @return true if the string can be used as a store name, else false.
+
  */
+
  boolean isValidStoreName(String storeName);
+
 
+
  /**
+
  * @return true if a store with this name exists, else false.
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws ObjectStoreException
+
  *          some error.
+
  */
+
  boolean existsStore(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.
+
  * @throws ObjectStoreException
+
  *          error deleting the store.
+
  */
+
  void removeStore(String storeName) throws ObjectStoreException;
+
 
+
  /**
+
  * Get information about all current objects in the named store.
+
  *
+
  * @return list of {@link StoreObject}s
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  *          error determining the object info list.
+
  */
+
  Collection<StoreObject> getStoreObjectInfos(String storeName) throws ObjectStoreException;
+
 
+
  /**
+
  * Get information about all current objects in the named store that have an ID that starts with the given prefix.
+
  *
+
  * @return list of {@link StoreObject}s with IDs matching the prefix.
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  *          error determining the object info list.
+
  */
+
  Collection<StoreObject> getStoreObjectInfos(String storeName, String objectIdPrefix) throws ObjectStoreException;
+
 
+
  /**
+
  * get configuration properties of the named store.
+
  *
+
  * @return configuration properties.
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  *          error reading store properties.
+
  */
+
  AnyMap getStoreProperties(String storeName) 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 <code>includeObjectInfos == true</code>. It
+
  * can contain additional information.
+
  *
+
  * @param includeObjectInfos
+
  *          set to true to include the list of current object infos in the result.
+
  * @return store state information
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  *          error reading store properties.
+
  */
+
  AnyMap getStoreInfo(String storeName, boolean includeObjectInfos) throws ObjectStoreException;
+
 
+
  // object handling methods
+
 
+
  /**
+
  * 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.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws NoSuchObjectException
+
  *          if the object does not exist
+
  * @throws ObjectStoreException
+
  *          other error reading the object
+
  */
+
  byte[] getObject(String storeName, String objectId) throws ObjectStoreException;
+
 
+
  /**
+
  * get a stream for reading the object content.
+
  *
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws NoSuchObjectException
+
  *          if the object does not exist
+
  * @throws ObjectStoreException
+
  *          other error reading the object
+
  */
+
  InputStream readObject(String storeName, String objectId) 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.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  *          other error reading the object
+
  */
+
  void putObject(String storeName, 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.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  *          other error reading the object
+
  */
+
  void appendToObject(String storeName, String objectId, byte[] data) 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 {@link #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.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  */
+
  void finishObject(String storeName, 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 {@link StoreOutputStream#abort()} before
+
  * closing the stream.
+
  *
+
  * @return stream for writing data to the object.
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  *          error creating the object.
+
  */
+
  StoreOutputStream writeObject(String storeName, String objectId) throws ObjectStoreException;
+
 
+
  /**
+
  * @return true if object exists in store, else false.
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  *          error checking object existence.
+
  */
+
  boolean existsObject(String storeName, 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.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist
+
  * @throws ObjectStoreException
+
  *          error removing the object.
+
  */
+
  void removeObject(String storeName, String objectId) throws ObjectStoreException;
+
 
+
  /**
+
  * get information about a single object.
+
  *
+
  * @return information about the object.
+
  * @throws InvalidStoreNameException
+
  *          if the store name is not valid.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist.
+
  * @throws NoSuchObjectException
+
  *          if the object does not exist in the store.
+
  * @throws ObjectStoreException
+
  *          error reading the object info.
+
  */
+
  StoreObject getObjectInfo(String storeName, String objectId) throws ObjectStoreException;
+
 
+
  /**
+
  * remove all stores from the service. All data will be lost, no store will exist anymore.
+
  *
+
  * @throws ObjectStoreException
+
  *          error removing the data.
+
  */
+
  void removeAllStores() 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.
+
  * @throws NoSuchStoreException
+
  *          if the store does not exist.
+
  * @throws ObjectStoreException
+
  *          error clearing the store.
+
  */
+
  void clearStore(String storeName) throws ObjectStoreException;
+
 
+
}
+
</source>
+
  
 
=== Implementations ===
 
=== Implementations ===
 
A filesystem bases implementation can be found in the package [[SMILA/Documentation/ObjectStore/filesystem/SimpleObjectStoreService|org.eclipse.smila.objectstore.filesystem]].
 
A filesystem bases implementation can be found in the package [[SMILA/Documentation/ObjectStore/filesystem/SimpleObjectStoreService|org.eclipse.smila.objectstore.filesystem]].

Revision as of 03:14, 22 June 2011

org.eclipse.smila.objectstore

since SMILA 0.9.0

ObjectStoreService

API

The API for the </tt>ObjectStoreService</tt> can be found in org.eclipse.smila.objectstore.ObjectStoreService

Implementations

A filesystem bases implementation can be found in the package org.eclipse.smila.objectstore.filesystem.

Back to the top