Author: mduerig
Date: Fri Jun 10 16:45:16 2016
New Revision: 1747743
URL: http://svn.apache.org/viewvc?rev=1747743&view=rev
Log:
@Trivial: Javadoc for TarRevisions, MemoryStoreRevisions, HttpStoreRevisions,
HttpStoreRevisions
Modified:
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/TarRevisions.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/http/HttpStoreRevisions.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/memory/MemoryStoreRevisions.java
Modified:
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/TarRevisions.java
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/TarRevisions.java?rev=1747743&r1=1747742&r2=1747743&view=diff
==============================================================================
---
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/TarRevisions.java
(original)
+++
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/TarRevisions.java
Fri Jun 10 16:45:16 2016
@@ -47,17 +47,26 @@ import com.google.common.base.Supplier;
import org.apache.jackrabbit.oak.segment.RecordId;
import org.apache.jackrabbit.oak.segment.Revisions;
import org.apache.jackrabbit.oak.segment.SegmentStore;
+import org.apache.jackrabbit.oak.segment.file.FileStore.ReadOnlyStore;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * This implementation of {@code Revisions} is backed by a
+ * {@link #JOURNAL_FILE_NAME journal} file where the current head is persisted
+ * by calling {@link #flush(Callable)}.
+ * <p>
+ * The {@link #setHead(Function, Option...)} method supports a timeout
+ * {@link Option}, which can be retrieved through factory methods of this
class.
+ * <p>
+ * Instance of this class must be {@link #bind(SegmentStore, Supplier) bound}
to
+ * a {@code SegmentStore} otherwise its method throw {@code
IllegalStateException}s.
+ */
public class TarRevisions implements Revisions, Closeable {
private static final Logger LOG =
LoggerFactory.getLogger(TarRevisions.class);
public static final String JOURNAL_FILE_NAME = "journal.log";
- /**
- * The latest head state.
- */
@Nonnull
private final AtomicReference<RecordId> head;
@@ -100,12 +109,26 @@ public class TarRevisions implements Rev
}
}
+ /**
+ * Timeout option approximating no time out ({@code Long.MAX_VALUE} days).
+ */
public static final Option INFINITY = new TimeOutOption(MAX_VALUE, DAYS);
+ /**
+ * Factory method for creating a timeout option.
+ */
public static Option timeout(long time, TimeUnit unit) {
return new TimeOutOption(time, unit);
}
+ /**
+ * Create a new instance placing the journal log file into the passed
+ * {@code directory}.
+ * @param readOnly safeguard for {@link ReadOnlyStore}: open the
journal
+ * file in read only mode.
+ * @param directory directory of the journal file
+ * @throws IOException
+ */
public TarRevisions(boolean readOnly, @Nonnull File directory)
throws IOException {
this.directory = checkNotNull(directory);
@@ -116,6 +139,12 @@ public class TarRevisions implements Rev
this.persistedHead = new AtomicReference<>(null);
}
+ /**
+ * Bind this instance to a store.
+ * @param store store to bind to
+ * @param writeInitialNode provider for the initial node in case the
journal is empty.
+ * @throws IOException
+ */
synchronized void bind(@Nonnull SegmentStore store,
@Nonnull Supplier<RecordId> writeInitialNode)
throws IOException {
@@ -153,6 +182,15 @@ public class TarRevisions implements Rev
private final Lock flushLock = new ReentrantLock();
+ /**
+ * Flush the id of the current head to the journal after a call to
+ * {@code persisted}. This method does nothing and returns immediately if
+ * called concurrently and a call is already in progress.
+ * @param persisted call back for upstream dependencies to ensure
+ * the current head state is actually persisted before
+ * its id is written to the head state.
+ * @throws IOException
+ */
public void flush(@Nonnull Callable<Void> persisted) throws IOException {
checkBound();
if (flushLock.tryLock()) {
@@ -198,6 +236,16 @@ public class TarRevisions implements Rev
}
}
+ /**
+ * This implementation blocks if a concurrent call is already in progress.
+ * @param newHead function mapping an record id to the record id to which
+ * the current head id should be set.
+ * @param options zero or one timeout options specifying how long to block
+ * @return
+ * @throws InterruptedException
+ * @see #timeout(long, TimeUnit)
+ * @see #INFINITY
+ */
@Override
public boolean setHead(
@Nonnull Function<RecordId, RecordId> newHead,
@@ -233,6 +281,10 @@ public class TarRevisions implements Rev
}
}
+ /**
+ * Close the underlying journal file.
+ * @throws IOException
+ */
@Override
public void close() throws IOException {
journalFile.close();
Modified:
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/http/HttpStoreRevisions.java
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/http/HttpStoreRevisions.java?rev=1747743&r1=1747742&r2=1747743&view=diff
==============================================================================
---
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/http/HttpStoreRevisions.java
(original)
+++
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/http/HttpStoreRevisions.java
Fri Jun 10 16:45:16 2016
@@ -34,6 +34,11 @@ import com.google.common.base.Function;
import org.apache.jackrabbit.oak.segment.RecordId;
import org.apache.jackrabbit.oak.segment.Revisions;
+/**
+ * This {@code Revisions} implementation delegates via HTTP
+ * to its remote counterpart. It does not support setting
+ * the id of the head state.
+ */
public class HttpStoreRevisions implements Revisions {
@Nonnull
@@ -61,6 +66,10 @@ public class HttpStoreRevisions implemen
}
}
+ /**
+ * Not supported: throws {@code UnsupportedOperationException}
+ * @throws UnsupportedOperationException, always
+ */
@Override
public boolean setHead(
@Nonnull RecordId expected, @Nonnull RecordId head,
@@ -68,6 +77,10 @@ public class HttpStoreRevisions implemen
throw new UnsupportedOperationException();
}
+ /**
+ * Not supported: throws {@code UnsupportedOperationException}
+ * @throws UnsupportedOperationException, always
+ */
@Override
public boolean setHead(
@Nonnull Function<RecordId, RecordId> newHead,
Modified:
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/memory/MemoryStoreRevisions.java
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/memory/MemoryStoreRevisions.java?rev=1747743&r1=1747742&r2=1747743&view=diff
==============================================================================
---
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/memory/MemoryStoreRevisions.java
(original)
+++
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/memory/MemoryStoreRevisions.java
Fri Jun 10 16:45:16 2016
@@ -31,9 +31,16 @@ import org.apache.jackrabbit.oak.segment
import org.apache.jackrabbit.oak.segment.Revisions;
import org.apache.jackrabbit.oak.spi.state.NodeBuilder;
+/**
+ * This is a simple in memory {@code Revisions} implementation.
+ * It is non blocking and does not support any {@link Option}s.
+ */
public class MemoryStoreRevisions implements Revisions {
private RecordId head;
+ /**
+ * Bind this instance to a {@code store}.
+ */
public void bind(MemoryStore store) throws IOException {
if (head == null) {
NodeBuilder builder = EMPTY_NODE.builder();
@@ -67,6 +74,10 @@ public class MemoryStoreRevisions implem
}
}
+ /**
+ * Not supported: throws {@code UnsupportedOperationException}
+ * @throws UnsupportedOperationException, always
+ */
@Override
public boolean setHead(
@Nonnull Function<RecordId, RecordId> newHead,
