View source for SMILA/Documentation/ObjectStore/Bundle org.eclipse.smila.objectstore.filesystem

= org.eclipse.smila.objectstore.filesystem =

== Description ==
This package provides a file system based implementation of the <tt>ObjectStoreService</tt> (<tt>org.eclipse.smila.objectstore</tt> package).

The objects are temporarily written to a shadow store, so they will not be visible until they have been committed (an exception to this is the append operation, that will append to the ''live'' object).

The storage is divided into two parts: <tt>Stores</tt> and <tt>Objects</tt>.

The following rules apply to this file system based implementation:
*Store
**A store is represented by a plain directory in the base store path. 
**A store can include plain files or a hierarchy of files that can be listed with <tt>getStoreObjectInfos(String, String)</tt>.
**A valid store name may contain up to 256 characters and no other characters than a-z, A-Z, 0-9, and '-' (hyphen). Expressed as a regular expression this is equal to: "[a-zA-Z0-9-]{0,256}"). 
*Object 
**An object represents a file in a store. 
**An object will be invisible until the corresponding <tt>SimpleStoreOutputStream</tt> is closed or an invocation of <tt>writeObject(String, String)</tt> method succeeded
***Exception: A invocation of the <tt>appendToObject(String, String, byte[])</tt> method will append directly to the visible object.

Hierarchies within the store can be created by using object ids that contain a path, e.g. creating an object <tt>path/to/the/object</tt> in a store with the name <tt>storename</tt> will result in the following file system hierarchy (starting with the store-base file system):
<tt>storename/path/to/the/object</tt>

== JavaDoc ==
JavaDoc can be found at [http://build.eclipse.org/rt/smila/javadoc/current/index.html?org/eclipse/smila/objectstore/filesystem/package-summary.html org.eclipse.smila.objectstore.filesystem].

For the interfaces implemented and the exceptions used, see [http://build.eclipse.org/rt/smila/javadoc/current/index.html?org/eclipse/smila/objectstore/package-summary.html org.eclipse.smila.objectstore].

== SimpleObjectStoreService ==
=== API ===

<tt>SimpleObjectStoreService</tt> implements the [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/objectstore/ObjectStoreService.html org.eclipse.smila.objectstore.ObjectStoreService API] of the <tt>ObjectStoreService</tt>.

This implementation does not support the method <tt>void finishObject(final String storeName, final String objectId)</tt>, that is meant to prevent further append calls for the object. Any call to this method is ignored.

You can find information of the <tt>ObjectStoreService</tt> in [[SMILA/Documentation/ObjectStore/Bundle org.eclipse.smila.objectstore|bundle org.eclipse.smila.objectstore]].

=== Configuration ===
The only configuration that can be provided (but is not necessary) is a configuration property file located at <tt>configuration/org.eclipse.smila.objectstore.filesystem/objectstoreservice.properties</tt>.

In this file you can specify the following settings:
*<tt>root.path</tt>
**Defines the path to the root directory of the object store. In this directory, the store root folder <tt>objectstore</tt> and shadow directory <tt>.objectstore</tt> will be created to hold the stores and the visible (resp. temporary) objects of the stores.
**Default: If the property is not set, a default directory for the bundle is created in the SMILA workspace.
*<tt>file.locking</tt>
**This option is experimental!
**If set to <tt>true</tt>, access to the file will be accompanied by a files system lock to prohibit parallel access by other programs. Whether or not the operating system or the file system used will honor this lock cannot be guaranteed, so it is not recommended.
**Default: <tt>false</tt>.