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 fr...@apache.org on 2017/08/07 12:59:43 UTC
svn commit: r1804330 - in
/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index:
Index.java IndexEntry.java IndexLoader.java IndexWriter.java
InvalidIndexException.java ReaderAtEnd.java
Author: frm
Date: Mon Aug 7 12:59:43 2017
New Revision: 1804330
URL: http://svn.apache.org/viewvc?rev=1804330&view=rev
Log:
OAK-6518 - Add Javadoc for the org.apache.jackrabbit.oak.segment.file.tar.index package
Modified:
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/Index.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexEntry.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexLoader.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexWriter.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/InvalidIndexException.java
jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/ReaderAtEnd.java
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/Index.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/Index.java?rev=1804330&r1=1804329&r2=1804330&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/Index.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/Index.java Mon Aug 7 12:59:43 2017
@@ -20,16 +20,48 @@ package org.apache.jackrabbit.oak.segmen
import java.util.Set;
import java.util.UUID;
+/**
+ * An index for the entries in a TAR file.
+ */
public interface Index {
+ /**
+ * Returns the identifiers of every entry in this index.
+ *
+ * @return A set of {@link UUID}.
+ */
Set<UUID> getUUIDs();
+ /**
+ * Find an entry by its identifier.
+ *
+ * @param msb The most significant bits of the identifier.
+ * @param lsb The least significant bits of the identifier.
+ * @return The index of the entry in this index, or {@code -1} if the entry
+ * was not found.
+ */
int findEntry(long msb, long lsb);
+ /**
+ * Return the size of this index in bytes.
+ *
+ * @return The size of this index in bytes.
+ */
int size();
+ /**
+ * Return the number of entries in this index.
+ *
+ * @return The number of entries in this index.
+ */
int count();
+ /**
+ * Return the entry at a specified index.
+ *
+ * @param i The index of the entry.
+ * @return An instance of {@link IndexEntry}.
+ */
IndexEntry entry(int i);
}
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexEntry.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexEntry.java?rev=1804330&r1=1804329&r2=1804330&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexEntry.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexEntry.java Mon Aug 7 12:59:43 2017
@@ -17,20 +17,60 @@
package org.apache.jackrabbit.oak.segment.file.tar.index;
+/**
+ * An entry in the index of entries of a TAR file.
+ */
public interface IndexEntry {
+ /**
+ * Return the most significant bits of the identifier of this entry.
+ *
+ * @return the most significant bits of the identifier of this entry.
+ */
long getMsb();
+ /**
+ * Return the least significant bits of the identifier of this entry.
+ *
+ * @return the least significant bits of the identifier of this entry.
+ */
long getLsb();
+ /**
+ * Return the position of this entry in the TAR file.
+ *
+ * @return the position of this entry in the TAR file.
+ */
int getPosition();
+ /**
+ * Return the length of this entry in the TAR file.
+ *
+ * @return the length of this entry in the TAR file.
+ */
int getLength();
+ /**
+ * Return the full generation of this entry.
+ *
+ * @return the full generation of this entry.
+ */
int getFullGeneration();
+ /**
+ * Return the tail generation of this entry.
+ *
+ * @return the tail generation of this entry.
+ */
int getTailGeneration();
+ /**
+ * Return {@code true} if this entry was generated as part of a tail
+ * commit.
+ *
+ * @return {@code true} if this entry was generated as part of a tail
+ * commit.
+ */
boolean isTail();
}
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexLoader.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexLoader.java?rev=1804330&r1=1804329&r2=1804330&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexLoader.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexLoader.java Mon Aug 7 12:59:43 2017
@@ -20,11 +20,19 @@ package org.apache.jackrabbit.oak.segmen
import static com.google.common.base.Preconditions.checkArgument;
import java.io.IOException;
-import java.io.RandomAccessFile;
-import java.nio.ByteBuffer;
+/**
+ * Load and validate the index of a TAR file.
+ */
public class IndexLoader {
+ /**
+ * Create a new {@link IndexLoader} for the specified block size. The block
+ * size is used to validate different data items in the index.
+ *
+ * @param blockSize The block size. It msut be strictly positive.
+ * @return An instance of {@link IndexLoader}.
+ */
public static IndexLoader newIndexLoader(int blockSize) {
checkArgument(blockSize > 0, "Invalid block size");
return new IndexLoader(blockSize);
@@ -43,6 +51,18 @@ public class IndexLoader {
return reader.readAtEnd(Integer.BYTES, Integer.BYTES).getInt();
}
+ /**
+ * Load and validate the index. The index is loaded by looking backwards at
+ * a TAR file. This method relies on an instance of {@link ReaderAtEnd}
+ * which is positioned at the end of the index in the TAR file.
+ *
+ * @param reader an instance of {@link ReaderAtEnd}.
+ * @return An instance of {@link Index}.
+ * @throws IOException If an I/O error occurs while reading the
+ * index.
+ * @throws InvalidIndexException If a validation error occurs while checking
+ * the index.
+ */
public Index loadIndex(ReaderAtEnd reader) throws IOException, InvalidIndexException {
switch (readMagic(reader)) {
case IndexLoaderV1.MAGIC:
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexWriter.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexWriter.java?rev=1804330&r1=1804329&r2=1804330&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexWriter.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/IndexWriter.java Mon Aug 7 12:59:43 2017
@@ -24,6 +24,10 @@ import java.util.ArrayList;
import java.util.List;
import java.util.zip.CRC32;
+/**
+ * Builds an index incrementally in memory, and serializes its contents into a
+ * sequence of bytes.
+ */
public class IndexWriter {
private static class Entry {
@@ -44,6 +48,15 @@ public class IndexWriter {
}
+ /**
+ * Create a new {@link IndexWriter} for the specified block size. The block
+ * size is needed to ensure that the data produced by the returned {@link
+ * IndexWriter} is aligned to a specified boundary, i.e. is a multiple of
+ * the block size.
+ *
+ * @param blockSize The block size. It must be strictly positive.
+ * @return An index of {@link IndexWriter}.
+ */
public static IndexWriter newIndexWriter(int blockSize) {
checkArgument(blockSize > 0, "Invalid block size");
return new IndexWriter(blockSize);
@@ -57,6 +70,19 @@ public class IndexWriter {
this.blockSize = blockSize;
}
+ /**
+ * Add an entry to this index.
+ *
+ * @param msb The most significant bits of the entry identifier.
+ * @param lsb The least significant bits of the entry
+ * identifier.
+ * @param offset The position of the entry in the file.
+ * @param size The size of the entry.
+ * @param fullGeneration The full generation of the entry.
+ * @param tailGeneration The tail generation of the entry.
+ * @param isTail Whether the entry is generated as part of a tail
+ * commit.
+ */
public void addEntry(long msb, long lsb, int offset, int size, int fullGeneration, int tailGeneration, boolean isTail) {
Entry entry = new Entry();
entry.msb = msb;
@@ -69,6 +95,13 @@ public class IndexWriter {
entries.add(entry);
}
+ /**
+ * Serializes the content of the index. The returned array of bytes is
+ * always a multiple of the block size specified when this {@link
+ * IndexWriter} was created.
+ *
+ * @return the serialized content of the index.
+ */
public byte[] write() {
int dataSize = entries.size() * IndexEntryV2.SIZE + IndexV2.FOOTER_SIZE;
int totalSize = ((dataSize + blockSize - 1) / blockSize) * blockSize;
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/InvalidIndexException.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/InvalidIndexException.java?rev=1804330&r1=1804329&r2=1804330&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/InvalidIndexException.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/InvalidIndexException.java Mon Aug 7 12:59:43 2017
@@ -17,6 +17,10 @@
package org.apache.jackrabbit.oak.segment.file.tar.index;
+/**
+ * Thrown to indicate that invalid or malformed data is encountered while
+ * validating an index.
+ */
public class InvalidIndexException extends Exception {
InvalidIndexException(String message) {
Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/ReaderAtEnd.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/ReaderAtEnd.java?rev=1804330&r1=1804329&r2=1804330&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/ReaderAtEnd.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/file/tar/index/ReaderAtEnd.java Mon Aug 7 12:59:43 2017
@@ -20,8 +20,24 @@ package org.apache.jackrabbit.oak.segmen
import java.io.IOException;
import java.nio.ByteBuffer;
+/**
+ * Read raw data from the end of an underlying data source. The data source is
+ * usually a file, but any data source for which the concept of "end" makes
+ * sense can be used. For example, a byte buffer could be used as the underlying
+ * data source, e.g. for testing purposes.
+ */
public interface ReaderAtEnd {
+ /**
+ * Read {@code amount} bytes from the underlying data source, starting at
+ * {@code whence} bytes from the end of the data source.
+ *
+ * @param whence The offset from the end of the data source.
+ * @param amount The amount of data to read, in bytes.
+ * @return An instance of {@link ByteBuffer}.
+ * @throws IOException if an error occurs while reading from the underlying
+ * data source.
+ */
ByteBuffer readAtEnd(int whence, int amount) throws IOException;
}