Author: mduerig
Date: Fri Jun 10 15:03:50 2016
New Revision: 1747726
URL: http://svn.apache.org/viewvc?rev=1747726&view=rev
Log:
@Trivial: Javadoc for Revisions interface and rename of method arguments
Modified:
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Revisions.java
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/Revisions.java
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Revisions.java?rev=1747726&r1=1747725&r2=1747726&view=diff
==============================================================================
---
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Revisions.java
(original)
+++
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Revisions.java
Fri Jun 10 15:03:50 2016
@@ -23,20 +23,63 @@ import javax.annotation.Nonnull;
import com.google.common.base.Function;
+/**
+ * {@code Revisions} instances provide read and write access to
+ * the current head state. Implementations are thread safe
+ * and all setters act atomically.
+ * <p>
+ * This is a low level API and it is the callers and implementors
+ * responsibility to ensure all record id passed to or returned
+ * from methods of this interface are the ids of node states.
+ */
public interface Revisions {
+ /**
+ * Implementation specific options for the {@code setHead} methods.
+ * These options can e.g. be used to specify priority, timeout, etc.
+ * for individual method calls.
+ */
interface Option {}
/**
- * Returns the record id of the head state.
- * @return od of the head state
+ * Returns the record id of the head state. The returned id
+ * is a valid id for a {@code SegmentNodeState}.
+ * @return id of the head state
*/
@Nonnull
RecordId getHead();
- boolean setHead(@Nonnull RecordId base,
+ /**
+ * Atomically set the record id of the current head state to the
+ * given {@code head} state if the current head state matches
+ * the {@code expected} value.
+ * All record ids must be valid ids for {@code SegmentNodeState}s.
+ *
+ * @param expected the expected head for the update to take place
+ * @param head the new head to update to
+ * @param options implementation specific options
+ * @return {@code true} if the current head was successfully
+ * updated, {@code false} otherwise.
+ */
+ boolean setHead(@Nonnull RecordId expected,
@Nonnull RecordId head,
@Nonnull Option... options);
+ /**
+ * Atomically set the record id of the current head state to the value
+ * returned from the {@code newHead} function when called with the record
+ * id of the current head.
+ * The behaviour of this function regarding locking and handling
+ * {@code null}s returned by {@code newHead} is implementation specific.
+ *
+ * @param newHead function mapping an record id to the record id to which
+ * the current head id should be set.
+ * @param options implementation specific options
+ * @return {@code true} if the current head was successfully
+ * updated, {@code false} otherwise.
+ * @throws InterruptedException
+ * Blocking implementations may throw this exception whe
+ * interrupted.
+ */
boolean setHead(@Nonnull Function<RecordId, RecordId> newHead,
@Nonnull Option... options)
throws InterruptedException;
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=1747726&r1=1747725&r2=1747726&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 15:03:50 2016
@@ -190,14 +190,14 @@ public class TarRevisions implements Rev
@Override
public boolean setHead(
- @Nonnull RecordId base,
+ @Nonnull RecordId expected,
@Nonnull RecordId head,
@Nonnull Option... options) {
checkBound();
rwLock.readLock().lock();
try {
RecordId id = this.head.get();
- return id.equals(base) && this.head.compareAndSet(id, head);
+ return id.equals(expected) && this.head.compareAndSet(id, head);
} finally {
rwLock.readLock().unlock();
}
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=1747726&r1=1747725&r2=1747726&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 15:03:50 2016
@@ -63,7 +63,7 @@ public class HttpStoreRevisions implemen
@Override
public boolean setHead(
- @Nonnull RecordId base, @Nonnull RecordId head,
+ @Nonnull RecordId expected, @Nonnull RecordId head,
@Nonnull Option... options) {
throw new UnsupportedOperationException();
}
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=1747726&r1=1747725&r2=1747726&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 15:03:50 2016
@@ -56,10 +56,10 @@ public class MemoryStoreRevisions implem
@Override
public synchronized boolean setHead(
- @Nonnull RecordId base, @Nonnull RecordId head,
+ @Nonnull RecordId expected, @Nonnull RecordId head,
@Nonnull Option... options) {
checkBound();
- if (this.head.equals(base)) {
+ if (this.head.equals(expected)) {
this.head = head;
return true;
} else {
