Package org.eclipse.osgi.storagemanager

Class StorageManager

java.lang.Object
org.eclipse.osgi.storagemanager.StorageManager
public final class StorageManager extends Object
Storage managers provide a facility for tracking the state of a group of files having relationship with each others and being updated by several entities at the same time. The typical usecase is in shared configuration data areas.

The facilities provided here are cooperative. That is, all participants must agree to the conventions and to calling the given API. There is no capacity to enforce these conventions or prohibit corruption.

Clients can not extend this class

Example:

 //Open the storage manager
 org.eclipse.osgi.storagemanager.StorageManager cacheStorageManager = new StorageManager("d:/sharedFolder/bar/", false); //$NON-NLS-1$
 try {
         cacheStorageManager.open(true);
 } catch (IOException e) {
 // Ignore the exception. The registry will be rebuilt from source.
 }

 //To read from a file
 java.io.File fileA = cacheStorageManager.lookup("fileA", false));
 java.io.File fileB = cacheStorageManager.lookup("fileB", false));
 //Do the reading code
 new java.io.FileOutputStream(fileA);

 //To write in files
 cacheStorageManager.add("fileC"); //add the file to the filemanager (in this case we assume it is not already here)
 cacheStorageManager.add("fileD");

 // The file is never written directly into the file name, so we create some temporary file
 java.io.File fileC = cacheStorageManager.createTempFile("fileC");
 java.io.File fileD = cacheStorageManager.createTempFile("fileD");

 //Do the actual writing here...

 //Finally update the storagemanager with the actual file to manage.
 cacheStorageManager.update(new String[] {"fileC", "fileD"}, new String[] {fileC.getName(), fileD.getName()};

 //Close the file manager at the end
 cacheStorageManager.close();

Implementation details
The following implementation details are provided to help with understanding the behavior of this class. The general principle is to maintain a table which maps user-level file names onto an actual disk files. If a file needs to be modified, it is stored into a new file. The old content is not removed from disk until all entities have closed there instance of the storage manager. Once the instance has been created, open() must be called before performing any other operation. On open the storage manager obtains a snapshot of the current managed files contents. If an entity updates a managed file, the storage manager will save the content for that instance of the storage manager, all other storage manager instances will still have access to that managed file's content as it was when the instance was first opened.

Since:
3.2

  • Constructor Summary

    Constructors
    Constructor
    Description
    StorageManager(File base, String lockMode)
    Returns a new storage manager for the area identified by the given base directory.
    StorageManager(File base, String lockMode, boolean readOnly)
    Returns a new storage manager for the area identified by the given base directory.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(String managedFile)
    Add the given managed file name to the list of files managed by this manager.
    void
    close()
    This method declares the storage manager as closed.
    File
    createTempFile(String file)
    Creates a new unique empty temporary-file in the storage manager base directory.
    File
    getBase()
    Returns the directory containing the files being managed by this storage manager.
    int
    getId(String managedFile)
    Returns the current numeric id (appendage) of the given managed file.
    InputStream
    getInputStream(String managedFile)
    Returns a managed InputStream for a managed file.
    InputStream[]
    getInputStreamSet(String[] managedFiles)
    Returns a managed input stream set for the managed file names.
    String[]
    getManagedFiles()
    Returns a list of all the managed files currently being managed.
    ManagedOutputStream
    getOutputStream(String managedFile)
    Returns a ManagedOutputStream for a managed file.
    ManagedOutputStream[]
    getOutputStreamSet(String[] managedFiles)
    Returns an array of ManagedOutputStream for a set of managed files.
    boolean
    isReadOnly()
    Returns if readOnly state this storage manager is using.
    File
    lookup(String managedFile, boolean add)
    Returns the actual file location to use when reading the given managed file.
    void
    open(boolean wait)
    This methods opens the storage manager.
    void
    remove(String managedFile)
    Removes the given managed file from management by this storage manager.
    void
    update(String[] managedFiles, String[] sources)
    Update the given managed files with the content in the given source files.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • StorageManager

      public StorageManager(File base, String lockMode)
      Returns a new storage manager for the area identified by the given base directory.
      Parameters:
      base - the directory holding the files to be managed
      lockMode - the lockMode to use for the storage manager. It can have one the 3 values: none, java.io, java.nio and also supports null in which case the lock strategy will be the global one.

    • StorageManager

      public StorageManager(File base, String lockMode, boolean readOnly)
      Returns a new storage manager for the area identified by the given base directory.
      Parameters:
      base - the directory holding the files to be managed
      lockMode - the lockMode to use for the storage manager. It can have one the 3 values: none, java.io, java.nio and also supports null in which case the lock strategy will be the global one.
      readOnly - true if the managed files are read-only

  • Method Details

    • add

      public void add(String managedFile) throws IOException
      Add the given managed file name to the list of files managed by this manager.
      Parameters:
      managedFile - name of the file to manage
      Throws:
      IOException - if there are any problems adding the given file name to the manager

    • update

      public void update(String[] managedFiles, String[] sources) throws IOException
      Update the given managed files with the content in the given source files. The managedFiles is a list of managed file names which are currently managed. If a managed file name is not currently managed it will be added as a managed file for this storage manager. The sources are absolute (or relative to the current working directory) file paths containing the new content for the corresponding managed files.
      Parameters:
      managedFiles - the managed files to update
      sources - the new content for the managed files
      Throws:
      IOException - if there are any problems updating the given managed files

    • getManagedFiles

      public String[] getManagedFiles()
      Returns a list of all the managed files currently being managed.
      Returns:
      the names of the managed files

    • getBase

      public File getBase()
      Returns the directory containing the files being managed by this storage manager.
      Returns:
      the directory containing the managed files

    • getId

      public int getId(String managedFile)
      Returns the current numeric id (appendage) of the given managed file. managedFile + "." + getId(target). A value of -1 is returned if the given name is not managed.
      Parameters:
      managedFile - the name of the managed file
      Returns:
      the id of the managed file

    • isReadOnly

      public boolean isReadOnly()
      Returns if readOnly state this storage manager is using.
      Returns:
      if this storage manager update state is read-only.

    • lookup

      public File lookup(String managedFile, boolean add) throws IOException
      Returns the actual file location to use when reading the given managed file. A value of null can be returned if the given managed file name is not managed and add is set to false.

      The returned file should be considered read-only. Any updates to the content of this file should be done using update(String[], String[]).

      Parameters:
      managedFile - the managed file to lookup
      add - indicate whether the managed file name should be added to the manager if it is not already managed.
      Returns:
      the absolute file location to use for the given managed file or null if the given managed file is not managed
      Throws:
      IOException - if the add flag is set to true and the addition of the managed file failed

    • remove

      public void remove(String managedFile) throws IOException
      Removes the given managed file from management by this storage manager.
      Parameters:
      managedFile - the managed file to remove
      Throws:
      IOException - if an error occured removing the managed file

    • close

      public void close()
      This method declares the storage manager as closed. From thereon, the instance can no longer be used. It is important to close the manager as it also cleans up old copies of the managed files.

    • open

      public void open(boolean wait) throws IOException
      This methods opens the storage manager. This method must be called before any operation on the storage manager.
      Parameters:
      wait - indicates if the open operation must wait in case of contention on the lock file.
      Throws:
      IOException - if an error occurred opening the storage manager

    • createTempFile

      public File createTempFile(String file) throws IOException
      Creates a new unique empty temporary-file in the storage manager base directory. The file name must be at least 3 characters. This file can later be used to update a managed file.

      Note that File.deleteOnExit() is not called on the returned file.

      Parameters:
      file - the file name to create temporary file from.
      Returns:
      the newly-created empty file.
      Throws:
      IOException - if the file can not be created.
      See Also:

    • getInputStream

      public InputStream getInputStream(String managedFile) throws IOException
      Returns a managed InputStream for a managed file. null can be returned if the given name is not managed.
      Parameters:
      managedFile - the name of the managed file to open.
      Returns:
      an input stream to the managed file or null if the given name is not managed.
      Throws:
      IOException - if the content is missing, corrupt or an error occurs.

    • getInputStreamSet

      public InputStream[] getInputStreamSet(String[] managedFiles) throws IOException
      Returns a managed input stream set for the managed file names. Elements of the returned set may be null if a given name is not managed. This method should be used for managed file sets which use the output streams returned by the getOutputStreamSet(String[]) to save data.
      Parameters:
      managedFiles - the names of the managed files to open.
      Returns:
      a set input streams to the given managed files.
      Throws:
      IOException - if the content of one of the managed files is missing, corrupt or an error occurs.

    • getOutputStream

      public ManagedOutputStream getOutputStream(String managedFile) throws IOException
      Returns a ManagedOutputStream for a managed file. Closing the ouput stream will update the storage manager with the new content of the managed file.
      Parameters:
      managedFile - the name of the managed file to write.
      Returns:
      a managed output stream for the managed file.
      Throws:
      IOException - if an error occurs opening the managed file.

    • getOutputStreamSet

      public ManagedOutputStream[] getOutputStreamSet(String[] managedFiles) throws IOException
      Returns an array of ManagedOutputStream for a set of managed files. When all managed output streams in the set have been closed, the storage manager will be updated with the new content of the managed files. Aborting any one of the streams will cause the entire content of the set to abort and be discarded.
      Parameters:
      managedFiles - list of names of the managed file to write.
      Returns:
      an array of managed output streams respectively of managed files.
      Throws:
      IOException - if an error occurs opening the managed files.