LMS-103

Storage: Javadoc added, IStorage contract modified, more tests in FileStorageTest

SVN: 2135

bds/source/java/ch/systemsx/cisd/bds/AbstractDataStructure.java

@@ -39,7 +39,7 @@ public abstract class AbstractDataStructure implements IHasVersion
 
     public void load()
     {
-        storage.load();
+        storage.mount();
         Version loadedVersion = Version.loadFrom(root);
         if (getVersion().isBackwardsCompatibleWith(loadedVersion) == false)
         {
@@ -51,6 +51,6 @@ public abstract class AbstractDataStructure implements IHasVersion
     public void save()
     {
         getVersion().saveTo(root);
-        storage.save();
+        storage.unmount();
     }
 }

bds/source/java/ch/systemsx/cisd/bds/Container.java

@@ -42,7 +42,7 @@ public class Container
     public AbstractDataStructure load(String name)
     {
         IStorage storage = createStorage(name);
-        storage.load();
+        storage.mount();
         Version version = Version.loadFrom(storage.getRoot());
         return DataStructureFactory.createDataStructure(storage, version);
     }

bds/source/java/ch/systemsx/cisd/bds/storage/IFile.java

@@ -17,7 +17,7 @@
 package ch.systemsx.cisd.bds.storage;
 
 /**
- * Role of a file with a value (content) of type <code>T</code>.
+ * Role of a leaf node representing a file with some content.
  *
  * @author Franz-Josef Elmer
  */

bds/source/java/ch/systemsx/cisd/bds/storage/ILink.java

@@ -17,11 +17,14 @@
 package ch.systemsx.cisd.bds.storage;
 
 /**
- * 
+ * Node representing a symbolic link.
  *
  * @author Franz-Josef Elmer
  */
 public interface ILink extends INode
 {
+    /**
+     * Returns the node referred by this node.
+     */
     public INode getReference();
 }

bds/source/java/ch/systemsx/cisd/bds/storage/IStorage.java

@@ -16,16 +16,29 @@
 
 package ch.systemsx.cisd.bds.storage;
 
+import ch.systemsx.cisd.common.exceptions.UserFailureException;
+
 /**
- * 
+ * Abstraction of a hierarchical storage.
  *
  * @author Franz-Josef Elmer
  */
 public interface IStorage
 {
-    public void load();
+    /**
+     * Mounts this storage. May perform some initializations. Should be called before calling {@link #getRoot()}.
+     */
+    public void mount();
     
-    public IDirectory getRoot();
+    /**
+     * Returns root directory of this storage. 
+     * 
+     * @throws UserFailureException if invoked before {@link #mount()} or after {@link #unmount()}.
+     */
+    public IDirectory getRoot() throws UserFailureException;
     
-    public void save();
+    /**
+     * Unmounts this storage. May perform some finalization (e.g. make cached data persistent).
+     */
+    public void unmount();
 }

bds/source/java/ch/systemsx/cisd/bds/storage/filesystem/AbstractNode.java

@@ -20,6 +20,7 @@ import java.io.File;
 
 import ch.systemsx.cisd.bds.storage.IDirectory;
 import ch.systemsx.cisd.bds.storage.INode;
+import ch.systemsx.cisd.common.exceptions.UserFailureException;
 
 /**
  * 
@@ -32,8 +33,14 @@ abstract class AbstractNode implements INode
 
     AbstractNode(File file)
     {
-        assert file != null : "Unspecified file";
-        assert file.exists() : "Non existing file " + file;
+        if (file == null)
+        {
+            throw new UserFailureException("Unspecified file");
+        }
+        if (file.exists() == false)
+        {
+            throw new UserFailureException("Non existing file " + file);
+        }
         this.nodeFile = file;
     }
     

bds/source/java/ch/systemsx/cisd/bds/storage/filesystem/Directory.java

@@ -34,7 +34,10 @@ class Directory extends AbstractNode implements IDirectory
     Directory(java.io.File directory)
     {
         super(directory);
-        assert directory.isDirectory() : "Not a directory: " + directory.getAbsolutePath();
+        if (directory.isDirectory() == false)
+        {
+            throw new UserFailureException("Not a directory: " + directory.getAbsolutePath());
+        }
     }
     
     public INode getNode(String name)

bds/source/java/ch/systemsx/cisd/bds/storage/filesystem/FileStorage.java

@@ -20,16 +20,24 @@ import java.io.File;
 
 import ch.systemsx.cisd.bds.storage.IDirectory;
 import ch.systemsx.cisd.bds.storage.IStorage;
+import ch.systemsx.cisd.common.exceptions.UserFailureException;
 
 /**
- * 
+ * Implementation of {@link IStorage} based on the file system.
  *
  * @author Franz-Josef Elmer
  */
 public class FileStorage implements IStorage
 {
-    private Directory root;
+    private final Directory root;
+    
+    private boolean mounted;
 
+    /**
+     * Creates an instance with the specified folder as the root directory.
+     * 
+     * @throws UserFailureException if <code>folder</code> does not exist or is not a directory in the file system.
+     */
     public FileStorage(File folder)
     {
         root = new Directory(folder);
@@ -37,15 +45,21 @@ public class FileStorage implements IStorage
     
     public IDirectory getRoot()
     {
+        if (mounted == false)
+        {
+            throw new UserFailureException("Can not get root of an unmounted storage.");
+        }
         return root;
     }
 
-    public void load()
+    public void mount()
     {
+        mounted = true;
     }
 
-    public void save()
+    public void unmount()
     {
+        mounted = false;
     }
 
 }

bds/source/java/ch/systemsx/cisd/bds/storage/hdf5/HDF5Storage.java

@@ -22,7 +22,7 @@ import ch.systemsx.cisd.bds.storage.IDirectory;
 import ch.systemsx.cisd.bds.storage.IStorage;
 
 /**
- * 
+ * Storage based on HDF5.
  *
  * @author Franz-Josef Elmer
  */
@@ -39,13 +39,13 @@ public class HDF5Storage implements IStorage
         return null;
     }
 
-    public void load()
+    public void mount()
     {
         // TODO Auto-generated method stub
 
     }
 
-    public void save()
+    public void unmount()
     {
         // TODO Auto-generated method stub
 

bds/sourceTest/java/ch/systemsx/cisd/bds/storage/filesystem/FileStorageTest.java

@@ -16,9 +16,13 @@
 
 package ch.systemsx.cisd.bds.storage.filesystem;
 
+import static org.testng.AssertJUnit.assertEquals;
+
 import org.testng.AssertJUnit;
 import org.testng.annotations.Test;
 
+import ch.systemsx.cisd.common.exceptions.UserFailureException;
+
 /**
  * 
  *
@@ -30,6 +34,37 @@ public class FileStorageTest extends StorageTestCase
     public void testGetRoot()
     {
         FileStorage fileStorage = new FileStorage(TEST_DIR);
-        AssertJUnit.assertEquals(TEST_DIR.getName(), fileStorage.getRoot().getName());
+        fileStorage.mount();
+        assertEquals(TEST_DIR.getName(), fileStorage.getRoot().getName());
+    }
+    
+    @Test
+    public void testGetRootOfNeverMountedStorage()
+    {
+        FileStorage fileStorage = new FileStorage(TEST_DIR);
+        try
+        {
+            fileStorage.getRoot();
+            AssertJUnit.fail("UserFailureException because storage isn't mounted.");
+        } catch (UserFailureException e)
+        {
+            assertEquals("Can not get root of an unmounted storage.", e.getMessage());
+        }
+    }
+    
+    @Test
+    public void testGetRootOfUnMountedStorage()
+    {
+        FileStorage fileStorage = new FileStorage(TEST_DIR);
+        fileStorage.mount();
+        fileStorage.unmount();
+        try
+        {
+            fileStorage.getRoot();
+            AssertJUnit.fail("UserFailureException because storage isn't mounted.");
+        } catch (UserFailureException e)
+        {
+            assertEquals("Can not get root of an unmounted storage.", e.getMessage());
+        }
     }
 }