Merge branch 0.7 and resolve conflicts.

docs/Tiered-Storage-on-Tachyon.md

@@ -1,6 +1,8 @@
 ---
 layout: global
 title: Tiered Storage on Tachyon (Beta)
+nickname: Tiered Storage
+group: More
 ---
 
 Tachyon supports tiered storage, which allows Tachyon to manage other storage types besides memory.

servers/src/main/java/tachyon/worker/block/BlockMetadataManager.java

@@ -28,6 +28,10 @@
 
 import tachyon.Constants;
 import tachyon.conf.TachyonConf;
+import tachyon.exception.AlreadyExistsException;
+import tachyon.exception.InvalidStateException;
+import tachyon.exception.NotFoundException;
+import tachyon.exception.OutOfSpaceException;
 import tachyon.worker.block.meta.BlockMeta;
 import tachyon.worker.block.meta.BlockMetaBase;
 import tachyon.worker.block.meta.StorageDir;
@@ -52,7 +56,8 @@ public class BlockMetadataManager {
 
   private BlockMetadataManager() {}
 
-  private void initBlockMetadataManager(TachyonConf tachyonConf) throws IOException {
+  private void initBlockMetadataManager(TachyonConf tachyonConf) throws AlreadyExistsException,
+      IOException, OutOfSpaceException {
     // Initialize storage tiers
     int totalTiers = tachyonConf.getInt(Constants.WORKER_MAX_TIERED_STORAGE_LEVEL, 1);
     mAliasToTiers = new HashMap<Integer, StorageTier>(totalTiers);
@@ -64,20 +69,30 @@ private void initBlockMetadataManager(TachyonConf tachyonConf) throws IOExceptio
     }
   }
 
-  public static BlockMetadataManager newBlockMetadataManager(TachyonConf tachyonConf)
-      throws IOException {
+  public static BlockMetadataManager newBlockMetadataManager(TachyonConf tachyonConf) {
     BlockMetadataManager ret = new BlockMetadataManager();
-    ret.initBlockMetadataManager(tachyonConf);
+    try {
+      ret.initBlockMetadataManager(tachyonConf);
+      // caller of newBlockMetadataManager should not be forced to catch and handle these exceptions
+      // since it is the responsibility of BlockMetadataManager.
+    } catch (AlreadyExistsException aee) {
+      throw new RuntimeException(aee);
+    } catch (IOException ioe) {
+      throw new RuntimeException(ioe);
+    } catch (OutOfSpaceException ooe) {
+      throw new RuntimeException(ooe);
+    }
     return ret;
   }
 
   /**
    * Aborts a temp block.
    *
    * @param tempBlockMeta the meta data of the temp block to add
-   * @throws IOException
+   * @throws NotFoundException when block can not be found
    */
-  public synchronized void abortTempBlockMeta(TempBlockMeta tempBlockMeta) throws IOException {
+  public synchronized void abortTempBlockMeta(TempBlockMeta tempBlockMeta)
+      throws NotFoundException {
     StorageDir dir = tempBlockMeta.getParentDir();
     dir.removeTempBlockMeta(tempBlockMeta);
   }
@@ -86,8 +101,11 @@ public synchronized void abortTempBlockMeta(TempBlockMeta tempBlockMeta) throws
    * Adds a temp block.
    *
    * @param tempBlockMeta the meta data of the temp block to add
+   * @throws OutOfSpaceException when no more space left to hold the block
+   * @throws AlreadyExistsException when the block already exists
    */
-  public synchronized void addTempBlockMeta(TempBlockMeta tempBlockMeta) throws IOException {
+  public synchronized void addTempBlockMeta(TempBlockMeta tempBlockMeta)
+      throws OutOfSpaceException, AlreadyExistsException {
     StorageDir dir = tempBlockMeta.getParentDir();
     dir.addTempBlockMeta(tempBlockMeta);
   }
@@ -96,9 +114,12 @@ public synchronized void addTempBlockMeta(TempBlockMeta tempBlockMeta) throws IO
    * Commits a temp block.
    *
    * @param tempBlockMeta the meta data of the temp block to commit
-   * @throws IOException
+   * @throws OutOfSpaceException when no more space left to hold the block
+   * @throws AlreadyExistsException when the block already exists in committed blocks
+   * @throws NotFoundException when temp block can not be found
    */
-  public synchronized void commitTempBlockMeta(TempBlockMeta tempBlockMeta) throws IOException {
+  public synchronized void commitTempBlockMeta(TempBlockMeta tempBlockMeta)
+      throws OutOfSpaceException, AlreadyExistsException, NotFoundException {
     BlockMeta block = new BlockMeta(Preconditions.checkNotNull(tempBlockMeta));
     StorageDir dir = tempBlockMeta.getParentDir();
     dir.removeTempBlockMeta(tempBlockMeta);
@@ -127,8 +148,9 @@ public synchronized void cleanupUserTempBlocks(long userId, List<Long> tempBlock
    *
    * @param location location the check available bytes
    * @return available bytes
+   * @throws IllegalArgumentException when location does not belong to tiered storage
    */
-  public synchronized long getAvailableBytes(BlockStoreLocation location) throws IOException {
+  public synchronized long getAvailableBytes(BlockStoreLocation location) {
     long spaceAvailable = 0;
 
     if (location.equals(BlockStoreLocation.anyTier())) {
@@ -151,21 +173,21 @@ public synchronized long getAvailableBytes(BlockStoreLocation location) throws I
   }
 
   /**
-   * Gets the metadata of a block given its blockId or throws IOException.
+   * Gets the metadata of a block given its blockId.
    *
    * @param blockId the block ID
    * @return metadata of the block
-   * @throws IOException if no BlockMeta for this blockId is found
+   * @throws NotFoundException if no BlockMeta for this blockId is found
    */
-  public synchronized BlockMeta getBlockMeta(long blockId) throws IOException {
+  public synchronized BlockMeta getBlockMeta(long blockId) throws NotFoundException {
     for (StorageTier tier : mTiers) {
       for (StorageDir dir : tier.getStorageDirs()) {
         if (dir.hasBlockMeta(blockId)) {
           return dir.getBlockMeta(blockId);
         }
       }
     }
-    throw new IOException("Failed to get BlockMeta: blockId " + blockId + " not found");
+    throw new NotFoundException("Failed to get BlockMeta: blockId " + blockId + " not found");
   }
 
   /**
@@ -175,10 +197,9 @@ public synchronized BlockMeta getBlockMeta(long blockId) throws IOException {
    * @param blockId the ID of the block
    * @param location location of a particular StorageDir to store this block
    * @return the path of this block in this location
-   * @throws IOException if location is not a specific StorageDir
+   * @throws IllegalArgumentException if location is not a specific StorageDir
    */
-  public synchronized String getBlockPath(long blockId, BlockStoreLocation location)
-      throws IOException {
+  public synchronized String getBlockPath(long blockId, BlockStoreLocation location) {
     return BlockMetaBase.commitPath(getDir(location), blockId);
   }
 
@@ -197,12 +218,13 @@ public synchronized BlockStoreMeta getBlockStoreMeta() {
    *
    * @param location Location of the dir
    * @return the StorageDir object
-   * @throws IOException if location is not a specific dir or the location is invalid
+   * @throws IllegalArgumentException if location is not a specific dir or the location is invalid
    */
-  public synchronized StorageDir getDir(BlockStoreLocation location) throws IOException {
+  public synchronized StorageDir getDir(BlockStoreLocation location) {
     if (location.equals(BlockStoreLocation.anyTier())
         || location.equals(BlockStoreLocation.anyDirInTier(location.tierAlias()))) {
-      throw new IOException("Failed to get block path: " + location + " is not a specific dir.");
+      throw new IllegalArgumentException("Failed to get block path: " + location
+          + " is not a specific dir.");
     }
     return getTier(location.tierAlias()).getDir(location.dir());
   }
@@ -212,30 +234,31 @@ public synchronized StorageDir getDir(BlockStoreLocation location) throws IOExce
    *
    * @param blockId the ID of the temp block
    * @return metadata of the block or null
-   * @throws IOException
+   * @throws NotFoundException when blockId can not be found
    */
-  public synchronized TempBlockMeta getTempBlockMeta(long blockId) throws IOException {
+  public synchronized TempBlockMeta getTempBlockMeta(long blockId) throws NotFoundException {
     for (StorageTier tier : mTiers) {
       for (StorageDir dir : tier.getStorageDirs()) {
         if (dir.hasTempBlockMeta(blockId)) {
           return dir.getTempBlockMeta(blockId);
         }
       }
     }
-    throw new IOException("Failed to get TempBlockMeta: temp blockId " + blockId + " not found");
+    throw new NotFoundException("Failed to get TempBlockMeta: temp blockId " + blockId
+        + " not found");
   }
 
   /**
    * Gets the StorageTier given its tierAlias.
    *
    * @param tierAlias the alias of this tier
    * @return the StorageTier object associated with the alias
-   * @throws IOException if tierAlias is not found
+   * @throws IllegalArgumentException if tierAlias is not found
    */
-  public synchronized StorageTier getTier(int tierAlias) throws IOException {
+  public synchronized StorageTier getTier(int tierAlias) {
     StorageTier tier = mAliasToTiers.get(tierAlias);
     if (tier == null) {
-      throw new IOException("Cannot find tier with alias " + tierAlias);
+      throw new IllegalArgumentException("Cannot find tier with alias " + tierAlias);
     }
     return tier;
   }
@@ -254,16 +277,16 @@ public synchronized List<StorageTier> getTiers() {
    *
    * @param tierAlias the alias of a tier
    * @return the list of StorageTier
-   * @throws IOException if tierAlias is not found
+   * @throws IllegalArgumentException if tierAlias is not found
    */
-  public synchronized List<StorageTier> getTiersBelow(int tierAlias) throws IOException {
+  public synchronized List<StorageTier> getTiersBelow(int tierAlias) {
     int level = getTier(tierAlias).getTierLevel();
     return mTiers.subList(level + 1, mTiers.size());
   }
 
   /**
-   * Gets all the temporary blocks associated with a user, empty list is returned if the user has
-   * no temporary blocks.
+   * Gets all the temporary blocks associated with a user, empty list is returned if the user has no
+   * temporary blocks.
    *
    * @param userId the ID of the user
    * @return A list of temp blocks associated with the user
@@ -318,41 +341,46 @@ public synchronized boolean hasTempBlockMeta(long blockId) {
    * @param blockMeta the meta data of the block to move
    * @param newLocation new location of the block
    * @return the new block metadata if success, absent otherwise
-   * @throws IOException if this block is not found
+   * @throws IllegalArgumentException when the newLocation is not in the tiered storage
+   * @throws NotFoundException when the block to move is not found
+   * @throws AlreadyExistsException when the block to move already exists in the destination
+   * @throws OutOfSpaceException when destination have no extra space to hold the block to move
    */
   public synchronized BlockMeta moveBlockMeta(BlockMeta blockMeta, BlockStoreLocation newLocation)
-      throws IOException {
+      throws NotFoundException, AlreadyExistsException, OutOfSpaceException {
     // If existing location belongs to the target location, simply return the current block meta.
     BlockStoreLocation oldLocation = blockMeta.getBlockLocation();
     if (oldLocation.belongTo(newLocation)) {
       LOG.info("moveBlockMeta: moving {} to {} is a noop", oldLocation, newLocation);
       return blockMeta;
     }
 
+    long blockSize = blockMeta.getBlockSize();
     int newTierAlias = newLocation.tierAlias();
     StorageTier newTier = getTier(newTierAlias);
     StorageDir newDir = null;
     if (newLocation.equals(BlockStoreLocation.anyDirInTier(newTierAlias))) {
       for (StorageDir dir : newTier.getStorageDirs()) {
-        if (dir.getAvailableBytes() >= blockMeta.getBlockSize()) {
+        if (dir.getAvailableBytes() >= blockSize) {
           newDir = dir;
+          break;
         }
       }
     } else {
       StorageDir dir = newTier.getDir(newLocation.dir());
-      if (dir.getAvailableBytes() >= blockMeta.getBlockSize()) {
+      if (dir.getAvailableBytes() >= blockSize) {
         newDir = dir;
       }
     }
 
     if (newDir == null) {
-      throw new IOException("Failed to move BlockMeta: newLocation " + newLocation
-          + " does not have enough space for " + blockMeta.getBlockSize() + " bytes");
+      throw new OutOfSpaceException("Failed to move BlockMeta: newLocation " + newLocation
+          + " does not have enough space for " + blockSize + " bytes");
     }
     StorageDir oldDir = blockMeta.getParentDir();
     oldDir.removeBlockMeta(blockMeta);
     BlockMeta newBlockMeta =
-        new BlockMeta(blockMeta.getBlockId(), blockMeta.getBlockSize(), newDir);
+        new BlockMeta(blockMeta.getBlockId(), blockSize, newDir);
     newDir.addBlockMeta(newBlockMeta);
     return newBlockMeta;
   }
@@ -361,9 +389,9 @@ public synchronized BlockMeta moveBlockMeta(BlockMeta blockMeta, BlockStoreLocat
    * Remove the metadata of a specific block.
    *
    * @param block the meta data of the block to remove
-   * @throws IOException
+   * @throws NotFoundException when block is not found
    */
-  public synchronized void removeBlockMeta(BlockMeta block) throws IOException {
+  public synchronized void removeBlockMeta(BlockMeta block) throws NotFoundException {
     StorageDir dir = block.getParentDir();
     dir.removeBlockMeta(block);
   }
@@ -373,9 +401,10 @@ public synchronized void removeBlockMeta(BlockMeta block) throws IOException {
    *
    * @param tempBlockMeta the temp block to modify
    * @param newSize new size in bytes
+   * @throws InvalidStateException when newSize is smaller than current size
    */
   public synchronized void resizeTempBlockMeta(TempBlockMeta tempBlockMeta, long newSize)
-      throws IOException {
+      throws InvalidStateException {
     StorageDir dir = tempBlockMeta.getParentDir();
     dir.resizeTempBlockMeta(tempBlockMeta, newSize);
   }