Cleanup documentation.

core/common/src/main/java/alluxio/util/URIUtils.java

@@ -11,9 +11,13 @@
 
 package alluxio.util;
 
+import alluxio.util.io.PathUtils;
+
 import com.google.common.base.Joiner;
 
 import java.io.UnsupportedEncodingException;
+import java.net.URI;
+import java.net.URISyntaxException;
 import java.net.URLDecoder;
 import java.net.URLEncoder;
 import java.util.ArrayList;
@@ -23,7 +27,7 @@
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
- * Utility methods for working with {@link alluxio.AlluxioURI}.
+ * Utility methods for working with URIs.
  */
 @ThreadSafe
 public final class URIUtils {
@@ -32,6 +36,19 @@ public final class URIUtils {
 
   private URIUtils() {} // prevent instantiation
 
+  /**
+   * Appends the given path to the given base URI.
+   *
+   * @param base the base URI
+   * @param path the path to append
+   * @return the URI resulting from appending the base and the path
+   * @throws URISyntaxException if URI syntax error is encountered
+   */
+  public static URI appendPath(URI base, String path) throws URISyntaxException {
+    return new URI(base.getScheme(), base.getHost(), PathUtils.concatPath(base.getPath(), path),
+        null);
+  }
+
   /**
    * Generates a query string from a {@link Map <String, String>} of key/value pairs.
    *

core/server/common/src/main/java/alluxio/master/journal/CheckpointManager.java

@@ -11,8 +11,13 @@
 
 package alluxio.master.journal;
 
-import java.net.URL;
+import java.net.URI;
 
+/**
+ * Interface for managing the checkpoint for a journal. The {@link #update(URI)} method will
+ * update the journal's checkpoint to the specified location, and
+ * {@link #recover()} will recover from any failures that may occur during {@link #update(URI)}.
+ */
 public interface CheckpointManager {
 
   /**
@@ -21,9 +26,9 @@ public interface CheckpointManager {
   void recover();
 
   /**
-   * Updates the checkpoint to the specified URL.
+   * Updates the checkpoint to the specified URI.
    *
-   * @param newCheckpoint the URL to the new checkpoint
+   * @param location the location of the new checkpoint
    */
-  void update(URL newCheckpoint);
+  void update(URI location);
 }

core/server/common/src/main/java/alluxio/master/journal/Journal.java

@@ -11,24 +11,18 @@
 
 package alluxio.master.journal;
 
-import java.net.URL;
+import java.net.URI;
 
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
- * This class encapsulates the journal for a master. The journal is made up of 2 components:
- * - The checkpoint: the full state of the master
- * - The entries: incremental entries to apply to the checkpoint.
- *
- * To construct the full state of the master, all the entries must be applied to the checkpoint in
- * order. The entry file most recently being written to is in the base journal folder, where the
- * completed entry files are in the "completed/" sub-directory.
+ * This class represents a journal.
  */
 @ThreadSafe
 public interface Journal {
 
   /**
-   * @return the location for this journal
+   * @return the journal location
    */
-  URL getLocation();
+  URI getLocation();
 }

core/server/common/src/main/java/alluxio/master/journal/JournalFactory.java

@@ -13,13 +13,13 @@
 
 import alluxio.master.journal.ufs.ReadOnlyUfsJournal;
 import alluxio.master.journal.ufs.ReadWriteUfsJournal;
-import alluxio.master.journal.ufs.UfsJournal;
+import alluxio.util.URIUtils;
 
-import java.net.MalformedURLException;
-import java.net.URL;
+import java.net.URI;
+import java.net.URISyntaxException;
 
 /**
- * Interface for factories which create {@link UfsJournal}s.
+ * Interface for factories which create {@link Journal}s.
  */
 public interface JournalFactory {
   /**
@@ -32,7 +32,7 @@ public interface JournalFactory {
    * A factory which creates read-write journals.
    */
   final class ReadWrite implements JournalFactory {
-    private final URL mBaseLocation;
+    private final URI mBaseLocation;
 
     /**
      * Creates a journal factory with the specified base location. When journals are
@@ -42,16 +42,16 @@ final class ReadWrite implements JournalFactory {
      *
      * @param baseLocation the base location for journals created by this factory
      */
-    public ReadWrite(URL baseLocation) {
+    public ReadWrite(URI baseLocation) {
       mBaseLocation = baseLocation;
     }
 
     @Override
-    public UfsJournal get(String name) {
+    public Journal get(String name) {
       try {
-        return new ReadWriteUfsJournal(new URL(mBaseLocation, name));
-      } catch (MalformedURLException e) {
-        throw new RuntimeException(e.getMessage());
+        return new ReadWriteUfsJournal(URIUtils.appendPath(mBaseLocation, name));
+      } catch (URISyntaxException e) {
+        throw new RuntimeException(e);
       }
     }
   }
@@ -60,26 +60,26 @@ public UfsJournal get(String name) {
    * A factory which creates read-only journals.
    */
   final class ReadOnly implements JournalFactory {
-    private final URL mBaseLocation;
+    private final URI mBaseLocation;
 
     /**
      * Creates a journal factory with the specified base location. When journals are
      * created, their names are appended to the base path.
      *
-     * Journals created by this factory only support reads.
+     * Journals created by this factory only support reading.
      *
      * @param baseLocation the base location for journals created by this factory
      */
-    public ReadOnly(URL baseLocation) {
+    public ReadOnly(URI baseLocation) {
       mBaseLocation = baseLocation;
     }
 
     @Override
-    public UfsJournal get(String name) {
+    public Journal get(String name) {
       try {
-        return new ReadOnlyUfsJournal(new URL(mBaseLocation, name));
-      } catch (MalformedURLException e) {
-        throw new RuntimeException(e.getMessage());
+        return new ReadOnlyUfsJournal(URIUtils.appendPath(mBaseLocation, name));
+      } catch (URISyntaxException e) {
+        throw new RuntimeException(e);
       }
     }
   }

core/server/common/src/main/java/alluxio/master/journal/JournalInputStream.java

@@ -16,8 +16,7 @@
 import java.io.IOException;
 
 /**
- * This input stream retrieves {@link JournalEntry} from journal checkpoint files and journal log
- * files.
+ * This input stream retrieves {@link JournalEntry} from journal checkpoints and journal logs.
  */
 public interface JournalInputStream {
   /**

core/server/common/src/main/java/alluxio/master/journal/JournalOutputStream.java

@@ -17,7 +17,7 @@
 
 /**
  * This output stream writes {@link JournalEntry} objects to the journal. This output stream can
- * write to both the journal checkpoint file, or the journal log files.
+ * write to both the journal checkpoint and the journal logs.
  */
 public interface JournalOutputStream {
   /**

core/server/common/src/main/java/alluxio/master/journal/JournalReader.java

@@ -20,8 +20,8 @@
  *
  * 1. First, the checkpoint must be read.
  *
- * 2. Afterwards, completed entries are read in order. Only completed logs are read, so the last log
- * currently being written is not read until it is marked as complete.
+ * 2. Afterwards, logs are read in order they were created. Only completed logs are read, so the
+ * last log currently being written is not read until it is marked as complete.
  */
 @NotThreadSafe
 public interface JournalReader {
@@ -38,21 +38,21 @@ public interface JournalReader {
    * Gets the {@link JournalInputStream} for the journal checkpoint. This must be called before
    * calling {@link #getNextInputStream()}.
    *
-   * @return the {@link JournalInputStream} for the journal checkpoint file
-   * @throws IOException if the checkpoint file cannot be read, or was already read
+   * @return the {@link JournalInputStream} for the journal checkpoint
+   * @throws IOException if the checkpoint cannot be read, or was already read
    */
   JournalInputStream getCheckpointInputStream() throws IOException;
 
   /**
-   * @return the input stream for the next completed log file. Will return null if the next
-   *         completed log file does not exist yet.
+   * @return the input stream for the next completed log. Will return null if the next
+   *         completed log does not exist yet.
    * @throws IOException if the reader is no longer valid or when trying to get an input stream
    *                     before a checkpoint was read
    */
   JournalInputStream getNextInputStream() throws IOException;
 
   /**
-   * @return the last modified time of the checkpoint file in ms
+   * @return the last modified time of the checkpoint in ms
    * @throws IOException if the checkpoint does not exist
    */
   long getCheckpointLastModifiedTimeMs() throws IOException;

core/server/common/src/main/java/alluxio/master/journal/JournalTailer.java

@@ -33,8 +33,6 @@ public final class JournalTailer {
 
   /** The master to apply all the journal entries to. */
   private final Master mMaster;
-  /** The journal to tail. */
-  private final Journal mJournal;
   /** The journal reader to read journal entries. */
   private final JournalReader mReader;
   /** This keeps track of the latest sequence number seen in the journal entries. */
@@ -48,8 +46,7 @@ public final class JournalTailer {
    */
   public JournalTailer(Master master, Journal journal) {
     mMaster = Preconditions.checkNotNull(master);
-    mJournal = Preconditions.checkNotNull(journal);
-    mReader = ((ReadOnlyUfsJournal) mJournal).getNewReader();
+    mReader = ((ReadOnlyUfsJournal) journal).getNewReader();
   }
 
   /**

core/server/common/src/main/java/alluxio/master/journal/JournalWriter.java

@@ -18,14 +18,13 @@
 /**
  * This class manages all the writes to the journal. Journal writes happen in two phases:
  *
- * 1. First the checkpoint file is written. The checkpoint file contains entries reflecting the
+ * 1. First the checkpoint is written. The checkpoint contains entries reflecting the
  * state of the master with all of the completed logs applied.
  *
- * 2. Afterwards, entries are appended to log files. The checkpoint file must be written before the
- * log files.
+ * 2. Afterwards, entries are appended to log. The checkpoint must be written before the logs.
  *
- * The latest state can be reconstructed by reading the checkpoint file, and applying all the
- * completed logs and then the remaining log in progress.
+ * The latest state can be reconstructed by reading the checkpoint, and applying all the
+ * completed logs and finally the current log.
  */
 public interface JournalWriter {
 
@@ -77,7 +76,7 @@ public interface JournalWriter {
   void close() throws IOException;
 
   /**
-   * Recovers the checkpoint file in case the master crashed while updating it previously.
+   * Recovers the checkpoint in case the master crashed while updating it previously.
    */
   void recover();
 
@@ -89,8 +88,8 @@ public interface JournalWriter {
   void deleteCompletedLogs() throws IOException;
 
   /**
-   * Moves the current log file to the completed folder, marking it as complete. If successful, the
-   * current log file will no longer exist. The current log must already be closed before this call.
+   * Marks the current log as completed. If successful, the current log will no longer exist. The
+   * current log must be closed before this call.
    *
    * @throws IOException if an I/O error occurs
    */

core/server/common/src/main/java/alluxio/master/journal/ufs/ReadOnlyUfsJournal.java

@@ -14,19 +14,19 @@
 import alluxio.master.journal.JournalReader;
 import alluxio.master.journal.ReadOnlyJournal;
 
-import java.net.URL;
+import java.net.URI;
 
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
- * The read-only journal. It prevents access to a {@link UfsJournalWriter}.
+ * Implementation of {@link ReadOnlyJournal} based on UFS.
  */
 @ThreadSafe
 public class ReadOnlyUfsJournal extends UfsJournal implements ReadOnlyJournal {
   /**
    * @param location the location for the journal
    */
-  public ReadOnlyUfsJournal(URL location) {
+  public ReadOnlyUfsJournal(URI location) {
     super(location);
   }
 

core/server/common/src/main/java/alluxio/master/journal/ufs/ReadWriteUfsJournal.java

@@ -14,19 +14,19 @@
 import alluxio.master.journal.JournalWriter;
 import alluxio.master.journal.ReadWriteJournal;
 
-import java.net.URL;
+import java.net.URI;
 
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
- * The read-write journal. This allows both reads and writes to the journal.
+ * Implementation of {@link ReadWriteJournal} based on UFS.
  */
 @ThreadSafe
 public class ReadWriteUfsJournal extends ReadOnlyUfsJournal implements ReadWriteJournal {
   /**
    * @param location the location for the journal
    */
-  public ReadWriteUfsJournal(URL location) {
+  public ReadWriteUfsJournal(URI location) {
     super(location);
   }