SMILA/Documentation/ObjectStore/Bundle org.eclipse.smila.objectstore

org.eclipse.smila.objectstore

since SMILA 0.9.0

ObjectStoreService

API

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;
 
}

Implementations

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