|
|
| 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]]. |
