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 to...@apache.org on 2018/03/22 11:24:21 UTC
svn commit: r1827478 - in
/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi:
monitor/ persistence/
Author: tomekr
Date: Thu Mar 22 11:24:20 2018
New Revision: 1827478
URL: http://svn.apache.org/viewvc?rev=1827478&view=rev
Log:
OAK-7338: Javadocs for the org.apache.jackrabbit.oak.segment.spi
Modified:
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/FileStoreMonitorAdapter.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/IOMonitorAdapter.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/GCJournalFile.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFile.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileReader.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileWriter.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/ManifestFile.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/RepositoryLock.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveEntry.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveManager.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveReader.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveWriter.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentNodeStorePersistence.java
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/FileStoreMonitorAdapter.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/FileStoreMonitorAdapter.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/FileStoreMonitorAdapter.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/FileStoreMonitorAdapter.java Thu Mar 22 11:24:20 2018
@@ -17,6 +17,10 @@
package org.apache.jackrabbit.oak.segment.spi.monitor;
+/**
+ * A void implementation of the {@link FileStoreMonitor}. Can be used for the
+ * testing purposes or for the extension.
+ */
public class FileStoreMonitorAdapter implements FileStoreMonitor {
@Override
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/IOMonitorAdapter.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/IOMonitorAdapter.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/IOMonitorAdapter.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/monitor/IOMonitorAdapter.java Thu Mar 22 11:24:20 2018
@@ -19,6 +19,10 @@ package org.apache.jackrabbit.oak.segmen
import java.io.File;
+/**
+ * A void implementation of the {@link IOMonitor}. Can be used for the
+ * testing purposes or for the extension.
+ */
public class IOMonitorAdapter implements IOMonitor {
@Override
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/GCJournalFile.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/GCJournalFile.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/GCJournalFile.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/GCJournalFile.java Thu Mar 22 11:24:20 2018
@@ -21,10 +21,30 @@ package org.apache.jackrabbit.oak.segmen
import java.io.IOException;
import java.util.List;
+/**
+ * This type abstracts the {@code gc.log} file, used to save information about
+ * the segment garbage collection. Each record is represented by a single string.
+ * <br><br>
+ * The implementation <b>doesn't need to be</b> thread-safe.
+ */
public interface GCJournalFile {
+ /**
+ * Write the new line to the GC journal file.
+ *
+ * @param line the line to write. It should contain neither special characters
+ * nor the newline {@code \n}.
+ * @throws IOException
+ */
void writeLine(String line) throws IOException;
+ /**
+ * Return the list of all written records in the same order as they were
+ * written.
+ *
+ * @return the list of all written lines
+ * @throws IOException
+ */
List<String> readLines() throws IOException;
}
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFile.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFile.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFile.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFile.java Thu Mar 22 11:24:20 2018
@@ -20,13 +20,42 @@ package org.apache.jackrabbit.oak.segmen
import java.io.IOException;
+/**
+ * The journal is a special, atomically updated file that records the state of
+ * the repository as a sequence of references to successive root node records.
+ * See <a href="https://jackrabbit.apache.org/oak/docs/nodestore/segment/overview.html">
+ * oak-segment-tar</a> documentation for more details.
+ */
public interface JournalFile {
+ /**
+ * Opens the journal file for reading. The returned object will represent
+ * the current state of the journal. Subsequent writes made by the
+ * {@link JournalFileWriter} won't be visible until a new
+ * {@link JournalFileReader} is opened.
+ *
+ * @return the reader representing the current state of the journal
+ * @throws IOException
+ */
JournalFileReader openJournalReader() throws IOException;
+ /**
+ * Opens the journal file for writing.
+ * @return
+ * @throws IOException
+ */
JournalFileWriter openJournalWriter() throws IOException;
+ /**
+ * Return the name representing the journal file.
+ * @return name (eg. file name) representing the journal
+ */
String getName();
+ /**
+ * Check if the journal already exists.
+ * @return {@code true} if the journal has been already created by the
+ * {@link JournalFileWriter}
+ */
boolean exists();
}
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileReader.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileReader.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileReader.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileReader.java Thu Mar 22 11:24:20 2018
@@ -21,8 +21,19 @@ package org.apache.jackrabbit.oak.segmen
import java.io.Closeable;
import java.io.IOException;
+/**
+ * The {@link JournalFile} reader. It reads the journal file backwards, starting
+ * from the last written line.
+ * <p>
+ * The implementation doesn't need to be thread-safe.
+ */
public interface JournalFileReader extends Closeable {
+ /**
+ * Read the line from the journal, using LIFO strategy (last in, first out).
+ * @return the journal record
+ * @throws IOException
+ */
String readLine() throws IOException;
}
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileWriter.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileWriter.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileWriter.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/JournalFileWriter.java Thu Mar 22 11:24:20 2018
@@ -21,10 +21,42 @@ package org.apache.jackrabbit.oak.segmen
import java.io.Closeable;
import java.io.IOException;
+/**
+ * The {@link JournalFile} writer. It allows to append a record to the journal file
+ * (or create a new one, if it doesn't exist).
+ * <p>
+ * The implementation doesn't need to be thread-safe (eg. the caller has to take
+ * care of synchronizing the {@link #writeLine(String)} method calls), but the method
+ * should be:
+ * <ul>
+ * <li>atomic with regards to the {@link JournalFileReader},</li>
+ * <li><b>flushed to the storage</b>.</li>
+ * </ul>
+ */
public interface JournalFileWriter extends Closeable {
+ /**
+ * Truncates the journal file. This is a maintenance operation, which may
+ * break existing {@link JournalFileReader} and shouldn't be used in the
+ * concurrent environment.
+ *
+ * @throws IOException
+ */
void truncate() throws IOException;
+ /**
+ * Write a new line to the journal file. This operation should be atomic,
+ * eg. it's should be possible to open a new reader using
+ * {@link JournalFile#openJournalReader()} in the way that it'll have access
+ * to an incomplete record line.
+ * <p>
+ * If this method returns successfully it means that the line was persisted
+ * on the non-volatile storage. For instance, on the local disk the
+ * {@code flush()} should be called by the implementation.
+ *
+ * @param line the journal record to be written
+ * @throws IOException
+ */
void writeLine(String line) throws IOException;
}
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/ManifestFile.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/ManifestFile.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/ManifestFile.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/ManifestFile.java Thu Mar 22 11:24:20 2018
@@ -21,12 +21,32 @@ package org.apache.jackrabbit.oak.segmen
import java.io.IOException;
import java.util.Properties;
+/**
+ * Manifest is a properties files, providing the information about the segment
+ * store (eg. the schema version number).
+ * <p>
+ * The implementation <b>doesn't need to be</b> thread-safe.
+ */
public interface ManifestFile {
+ /**
+ * Check if the manifest already exists.
+ * @return {@code true} if the manifest exists
+ */
boolean exists();
+ /**
+ * Load the properties from the manifest file.
+ * @return properties describing the segmentstore
+ * @throws IOException
+ */
Properties load() throws IOException;
+ /**
+ * Store the properties to the manifest file.
+ * @param properties describing the segmentstore
+ * @throws IOException
+ */
void save(Properties properties) throws IOException;
}
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/RepositoryLock.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/RepositoryLock.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/RepositoryLock.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/RepositoryLock.java Thu Mar 22 11:24:20 2018
@@ -20,8 +20,18 @@ package org.apache.jackrabbit.oak.segmen
import java.io.IOException;
+/**
+ * This type represents the lock that has been already acquired on the segment
+ * store. The lock should prevent local and remote processes from accessing the
+ * same segment store.
+ */
public interface RepositoryLock {
+ /**
+ * Unlocks the repository, so that it can be used by another SegmentNodeStore.
+ *
+ * @throws IOException
+ */
void unlock() throws IOException;
}
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveEntry.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveEntry.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveEntry.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveEntry.java Thu Mar 22 11:24:20 2018
@@ -18,6 +18,13 @@
*/
package org.apache.jackrabbit.oak.segment.spi.persistence;
+/**
+ * Represents a single entry (segment) in the segment archive. The segment is
+ * identified by the {@link java.util.UUID}, which can be split into two
+ * {@link Long} integers. The entry also has its length and 3 properties related
+ * to the garbage collection process: generation, full generation and compacted
+ * status.
+ */
public interface SegmentArchiveEntry {
/**
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveManager.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveManager.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveManager.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveManager.java Thu Mar 22 11:24:20 2018
@@ -30,6 +30,8 @@ import java.util.UUID;
* stored in the .tar). It allows to perform a few FS-like operations (delete,
* rename, copy, etc.) and also opens the segment archives either for reading
* or reading and writing.
+ * <p>
+ * The implementation doesn't need to be thread-safe.
*/
public interface SegmentArchiveManager {
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveReader.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveReader.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveReader.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveReader.java Thu Mar 22 11:24:20 2018
@@ -24,14 +24,18 @@ import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.List;
+/**
+ * This interface represents a read-only segment archive. Since the underlying
+ * data structure is immutable, the implementation <b>should be</b> thread safe.
+ */
public interface SegmentArchiveReader {
/**
* Read the segment.
*
- * @param msb
- * @param lsb
- * @return byte buffer containing the segment data or null if segment doesn't exist
+ * @param msb the most significant bits of the identifier of the segment
+ * @param lsb the least significant bits of the identifier of the segment
+ * @return byte buffer containing the segment data or null if the segment doesn't exist
*/
@Nullable
ByteBuffer readSegment(long msb, long lsb) throws IOException;
@@ -39,9 +43,9 @@ public interface SegmentArchiveReader {
/**
* Check if the segment exists.
*
- * @param msb
- * @param lsb
- * @return true if the segment exists
+ * @param msb the most significant bits of the identifier of the segment
+ * @param lsb the least significant bits of the identifier of the segment
+ * @return {@code true} if the segment exists
*/
boolean containsSegment(long msb, long lsb);
@@ -53,24 +57,25 @@ public interface SegmentArchiveReader {
List<SegmentArchiveEntry> listSegments();
/**
- * Loads and returns the graph.
+ * Load the segment graph.
*
- * @return the segment graph or null if the persisted graph doesn't exist.
+ * @return byte buffer representing the graph or null if the graph hasn't been
+ * persisted.
*/
@Nullable
ByteBuffer getGraph() throws IOException;
/**
- * Check if the persisted graph exists.
+ * Check if the segment graph has been persisted for this archive.
*
- * @return true if the graph exists, false otherwise
+ * @return {@code true} if the graph exists, false otherwise
*/
boolean hasGraph();
/**
- * Loads and returns the binary references.
+ * Load binary references.
*
- * @return binary references
+ * @return byte buffer representing the binary references structure.
*/
@Nonnull
ByteBuffer getBinaryReferences() throws IOException;
@@ -96,9 +101,12 @@ public interface SegmentArchiveReader {
void close() throws IOException;
/**
- * Returns the size of the entry
- * @param size
- * @return
+ * Transforms the segment size in bytes into the effective size on disk for
+ * the given entry (eg. by adding the number of padding bytes, header, etc.)
+ *
+ * @param size the segment size in bytes
+ * @return the number of bytes effectively used on the storage to save the
+ * segment
*/
int getEntrySize(int size);
}
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveWriter.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveWriter.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveWriter.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentArchiveWriter.java Thu Mar 22 11:24:20 2018
@@ -24,22 +24,44 @@ import java.io.IOException;
import java.nio.ByteBuffer;
/**
- * Allows to write in the new archive.
+ * Represents a write-enabled, append-only archive. It allows to append segments
+ * and other data structures (segment graph, serialized binary references) to the
+ * archive and also to read the already persisted segments.<p>
+ * Caller will use the methods modifying the archive in the following order:
+ * <ol>
+ * <li>phase 1:
+ * <ul>
+ * <li>{@link #writeSegment(long, long, byte[], int, int, int, int, boolean)}</li>
+ * <li>{@link #flush()}</li>
+ * </ul>
+ * repeated in an unspecified order</li>
+ * <li>{@link #writeBinaryReferences(byte[])}</li>
+ * <li>{@link #writeGraph(byte[])} (optionally)</li>
+ * <li>{@link #close()}</li>
+ * </ol>
+ * All the calls above are synchronized by the caller.
+ * In the first phase of the writer lifecycle, the
+ * write() and the flush() will be called many times, in an unspecified order. At
+ * the end of the writer life cycle, the rest of the methods (2-4) will be called.
+ * <p>
+ * Before the {@link #close()}, all the non-modifying methods
+ * (eg. {@link #readSegment(long, long)}, {@link #getLength()}} can be invoked at
+ * any time. They <b>should be thread safe</b>.
*/
public interface SegmentArchiveWriter {
/**
* Write the new segment to the archive.
*
- * @param msb
- * @param lsb
- * @param data
- * @param offset
- * @param size
- * @param generation
- * @param fullGeneration
- * @param isCompacted
- * @return the entry representing the new segment. Can be later used for the {@link #readSegment(long, long)} method.
+ * @param msb the most significant bits of the identifier of the segment
+ * @param lsb the least significant bits of the identifier of the segment
+ * @param data the data.
+ * @param offset the start offset in the data.
+ * @param size the number of bytes to write.
+ * @param generation the segment generation, see {@link SegmentArchiveEntry#getGeneration()}
+ * @param fullGeneration the segment full generation, see {@link SegmentArchiveEntry#getFullGeneration()}
+ * @param isCompacted the segment compaction property, see {@link SegmentArchiveEntry#isCompacted()}
+ * @throws IOException
*/
@Nonnull
void writeSegment(long msb, long lsb, @Nonnull byte[] data, int offset, int size, int generation, int fullGeneration, boolean isCompacted) throws IOException;
@@ -47,8 +69,8 @@ public interface SegmentArchiveWriter {
/**
* Read the segment.
*
- * @param msb
- * @param lsb
+ * @param msb the most significant bits of the identifier of the segment
+ * @param lsb the least significant bits of the identifier of the segment
* @return byte buffer containing the segment data or null if segment doesn't exist
*/
@Nullable
@@ -57,8 +79,8 @@ public interface SegmentArchiveWriter {
/**
* Check if the segment exists.
*
- * @param msb
- * @param lsb
+ * @param msb the most significant bits of the identifier of the segment
+ * @param lsb the least significant bits of the identifier of the segment
* @return true if the segment exists
*/
boolean containsSegment(long msb, long lsb);
@@ -66,14 +88,14 @@ public interface SegmentArchiveWriter {
/**
* Write the graph data.
*
- * @param data
+ * @param data serialized segment graph data
*/
void writeGraph(@Nonnull byte[] data) throws IOException;
/**
* Write the binary references data.
*
- * @param data
+ * @param data serialized binary references data
*/
void writeBinaryReferences(@Nonnull byte[] data) throws IOException;
@@ -97,7 +119,9 @@ public interface SegmentArchiveWriter {
boolean isCreated();
/**
- * Flush all the data to the storage.
+ * Flush all the data to the storage. After returning from this method
+ * successfully, all the segments written with the {@link #writeSegment(long, long, byte[], int, int, int, int, boolean)}
+ * should be actually saved to the storage.
*/
void flush() throws IOException;
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentNodeStorePersistence.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentNodeStorePersistence.java?rev=1827478&r1=1827477&r2=1827478&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentNodeStorePersistence.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/spi/persistence/SegmentNodeStorePersistence.java Thu Mar 22 11:24:20 2018
@@ -23,18 +23,64 @@ import org.apache.jackrabbit.oak.segment
import java.io.IOException;
+/**
+ * This type is a main entry point for the segment node store persistence. It's
+ * used every time the access to the underlying storage (eg. tar files) is required.
+ */
public interface SegmentNodeStorePersistence {
+ /**
+ * Opens a new archive manager. It'll be used to access the archives containing
+ * segments.
+ *
+ * @param memoryMapping whether the memory mapping should be used (if the given
+ * persistence supports it)
+ * @param ioMonitor object used to monitor segment-related IO access. The
+ * implementation should call the appropriate methods when
+ * accessing segments.
+ * @param fileStoreMonitor object used to monitor the general IO usage.
+ * @return segment archive manager
+ * @throws IOException
+ */
SegmentArchiveManager createArchiveManager(boolean memoryMapping, IOMonitor ioMonitor, FileStoreMonitor fileStoreMonitor) throws IOException;
+ /**
+ * Check if the segment store already contains any segments
+ * @return {@code true} is some segments are available for reading
+ */
boolean segmentFilesExist();
+ /**
+ * Create the {@link JournalFile}.
+ * @return object representing the segment journal file
+ */
JournalFile getJournalFile();
+ /**
+ * Create the {@link GCJournalFile}.
+ * @return object representing the GC journal file
+ * @throws IOException
+ */
GCJournalFile getGCJournalFile() throws IOException;
+ /**
+ * Create the {@link ManifestFile}.
+ * @return object representing the manifest file
+ * @throws IOException
+ */
ManifestFile getManifestFile() throws IOException;
+ /**
+ * Acquire the lock on the repository. During the lock lifetime it shouldn't
+ * be possible to acquire it again, either by a local or by a remote process.
+ * <p>
+ * The lock can be released manually by calling {@link RepositoryLock#unlock()}.
+ * If the segment node store is shut down uncleanly (eg. the process crashes),
+ * it should be released automatically, so no extra maintenance tasks are
+ * required to run the process again.
+ * @return the acquired repository lock
+ * @throws IOException
+ */
RepositoryLock lockRepository() throws IOException;
}