You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by md...@apache.org on 2016/06/14 09:52:16 UTC
svn commit: r1748373 - in
/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment:
CachingSegmentReader.java SegmentNodeStoreBuilders.java SegmentReader.java
Author: mduerig
Date: Tue Jun 14 09:52:16 2016
New Revision: 1748373
URL: http://svn.apache.org/viewvc?rev=1748373&view=rev
Log:
@Trivial: Javadoc improvements
Modified:
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/CachingSegmentReader.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentNodeStoreBuilders.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentReader.java
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/CachingSegmentReader.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/CachingSegmentReader.java?rev=1748373&r1=1748372&r2=1748373&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/CachingSegmentReader.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/CachingSegmentReader.java Tue Jun 14 09:52:16 2016
@@ -30,9 +30,15 @@ import com.google.common.base.Function;
import com.google.common.base.Supplier;
import org.apache.jackrabbit.oak.cache.CacheStats;
import org.apache.jackrabbit.oak.spi.blob.BlobStore;
+import org.apache.jackrabbit.oak.spi.state.NodeState;
// FIXME OAK-4451: Implement a proper template cache
// - move the template cache into this class, implement monitoring, management, logging, tests
+
+/**
+ * This {@code SegmentReader} implementation implements caching for
+ * strings and templates. It can also optionally rely on a {@link BlobStore} for resolving blobs.
+ */
public class CachingSegmentReader implements SegmentReader {
public static final int DEFAULT_STRING_CACHE_MB = 256;
@@ -53,6 +59,16 @@ public class CachingSegmentReader implem
@Nonnull
private final StringCache stringCache;
+ /**
+ * Create a new instance based on the supplied arguments.
+ * @param writer A {@code Supplier} for a the {@code SegmentWriter} used by the segment
+ * builders returned from {@link NodeState#builder()} to write ahead changes.
+ * {@code writer.get()} must not return {@code null}.
+ * @param revisions {@code Revisions} instance of the underlying {@link SegmentStore}.
+ * @param blobStore {@code BlobStore} instance of the underlying {@link SegmentStore}, or
+ * {@code null} if none.
+ * @param stringCacheMB the size of the string cache in MBs or {@code 0} for no cache.
+ */
public CachingSegmentReader(
@Nonnull Supplier<SegmentWriter> writer,
@Nonnull Revisions revisions,
@@ -64,6 +80,9 @@ public class CachingSegmentReader implem
stringCache = new StringCache(getLong(STRING_CACHE_MB, stringCacheMB) * 1024 * 1024);
}
+ /**
+ * Cached reading of a string.
+ */
@Nonnull
@Override
public String readString(@Nonnull RecordId id) {
@@ -85,6 +104,9 @@ public class CachingSegmentReader implem
return new MapRecord(this, id);
}
+ /**
+ * Cached reading of a template.
+ */
@Nonnull
@Override
public Template readTemplate(@Nonnull RecordId id) {
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentNodeStoreBuilders.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentNodeStoreBuilders.java?rev=1748373&r1=1748372&r2=1748373&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentNodeStoreBuilders.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentNodeStoreBuilders.java Tue Jun 14 09:52:16 2016
@@ -26,21 +26,34 @@ import org.apache.jackrabbit.oak.segment
import org.apache.jackrabbit.oak.segment.http.HttpStore;
import org.apache.jackrabbit.oak.segment.memory.MemoryStore;
+/**
+ * Static factories for creating {@link SegmentNodeBuilder} instances
+ * pertaining to specific {@link SegmentStore} instances.
+ */
public final class SegmentNodeStoreBuilders {
private SegmentNodeStoreBuilders() {}
+ /**
+ * Create a {@code SegmentNodeStoreBuilder} based on a {@code FileStore}.
+ */
@Nonnull
public static SegmentNodeStoreBuilder builder(@Nonnull FileStore store) {
return SegmentNodeStore.builder(store.getRevisions(),
store.getReader(), store.getWriter(), store.getBlobStore());
}
+ /**
+ * Create a {@code SegmentNodeStoreBuilder} based on a {@code MemoryStore}.
+ */
@Nonnull
public static SegmentNodeStoreBuilder builder(@Nonnull MemoryStore store) {
return SegmentNodeStore.builder(store.getRevisions(),
store.getReader(), store.getWriter(), store.getBlobStore());
}
+ /**
+ * Create a {@code SegmentNodeStoreBuilder} based on a {@code HttpStore}.
+ */
@Nonnull
public static SegmentNodeStoreBuilder builder(@Nonnull HttpStore store) {
return SegmentNodeStore.builder(store.getRevisions(),
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentReader.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentReader.java?rev=1748373&r1=1748372&r2=1748373&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentReader.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentReader.java Tue Jun 14 09:52:16 2016
@@ -21,28 +21,67 @@ package org.apache.jackrabbit.oak.segmen
import javax.annotation.Nonnull;
+/**
+ * Instances of {@code SegmentReader} are responsible for reading records from segments.
+ * <p>
+ * Passing a record id that cannot be resolved to any of the read methods will eventually
+ * result in a {@link SegmentNotFoundException}. Implementations are however free to choose
+ * to defer such an exception. For example by returning cached data or a thunk to a specific
+ * record such that the exception is only thrown when actually accessing the returned record.
+ * <p>
+ * The behaviour of the read methods is implementation specific when passing a record id
+ * that does not match the type of the expected record.
+ */
public interface SegmentReader {
+
+ /**
+ * Read the string identified by {@code id}.
+ * @throws SegmentNotFoundException see class comment for exception semantics
+ */
@Nonnull
String readString(@Nonnull RecordId id);
+ /**
+ * Read the map identified by {@code id}.
+ * @throws SegmentNotFoundException see class comment for exception semantics
+ */
@Nonnull
MapRecord readMap(@Nonnull RecordId id);
+ /**
+ * Read the template identified by {@code id}.
+ * @throws SegmentNotFoundException see class comment for exception semantics
+ */
@Nonnull
Template readTemplate(@Nonnull RecordId id);
+ /**
+ * Read the node identified by {@code id}.
+ * @throws SegmentNotFoundException see class comment for exception semantics
+ */
@Nonnull
SegmentNodeState readNode(@Nonnull RecordId id);
+ /**
+ * Read the current head state
+ * @throws SegmentNotFoundException see class comment for exception semantics
+ */
@Nonnull
SegmentNodeState readHeadState();
+ /**
+ * Read the property identified by {@code id} and {@code template}
+ * @throws SegmentNotFoundException see class comment for exception semantics
+ */
@Nonnull
SegmentPropertyState readProperty(
@Nonnull RecordId id,
@Nonnull PropertyTemplate template);
+ /**
+ * Read the blob identified by {@code id}.
+ * @throws SegmentNotFoundException see class comment for exception semantics
+ */
@Nonnull
SegmentBlob readBlob(@Nonnull RecordId id);
-
}