Package org.apache.jackrabbit.oak.segment.spi.persistence

Interface SegmentArchiveWriter

All Known Implementing Classes:

AbstractRemoteSegmentArchiveWriter, AwsSegmentArchiveWriter, AzureSegmentArchiveWriter, AzureSegmentArchiveWriterV8, SegmentTarWriter

public interface SegmentArchiveWriter

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.

Caller will use the methods modifying the archive in the following order:

1. phase 1:
   • writeSegment(long, long, byte[], int, int, int, int, boolean)
   • flush()
   repeated in an unspecified order
2. writeBinaryReferences(byte[])
3. writeGraph(byte[]) (optionally)
4. close()

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.

Before the close(), all the non-modifying methods (eg. readSegment(long, long), getLength()} can be invoked at any time. They should be thread safe.

Method Summary

Modifier and Type	Method	Description
void	close()	Close the archive.
boolean	containsSegment(long msb, long lsb)	Check if the segment exists.
void	flush()	Flush all the data to the storage.
int	getEntryCount()	Get the number of entries currently contained in the archive.
long	getLength()	Get the current length of the archive.
int	getMaxEntryCount()	This method returns the maximum number of segments that can be supported by the underlying persistence implementation of the archive writer.
@NotNull String	getName()	Get the name of the archive.
boolean	isCreated()	Check if the archive has been created (eg.
boolean	isRemote()	This method returns true if the storage is accessed via a network protocol, not tied to the traditional storage technology, for example, HTTP.
@Nullable Buffer	readSegment(long msb, long lsb)	Read the segment.
void	writeBinaryReferences(@org.jetbrains.annotations.NotNull byte[] data)	Write the binary references data.
void	writeGraph(@org.jetbrains.annotations.NotNull byte[] data)	Write the graph data.
void	writeSegment(long msb, long lsb, @org.jetbrains.annotations.NotNull byte[] data, int offset, int size, int generation, int fullGeneration, boolean isCompacted)	Write the new segment to the archive.

Method Detail

writeSegment

@NotNull
void writeSegment(long msb,
                  long lsb,
                  @NotNull
                  @org.jetbrains.annotations.NotNull byte[] data,
                  int offset,
                  int size,
                  int generation,
                  int fullGeneration,
                  boolean isCompacted)
           throws IOException

Write the new segment to the archive.

Parameters:

msb - the most significant bits of the identifier of the segment

lsb - the least significant bits of the identifier of the segment

data - the data.

offset - the start offset in the data.

size - the number of bytes to write.

generation - the segment generation, see SegmentArchiveEntry.getGeneration()

fullGeneration - the segment full generation, see SegmentArchiveEntry.getFullGeneration()

isCompacted - the segment compaction property, see SegmentArchiveEntry.isCompacted()

Throws:

IOException - error writing segment

readSegment

@Nullable
@Nullable Buffer readSegment(long msb,
                             long lsb)
                      throws IOException

Read the segment.

Parameters:

msb - the most significant bits of the identifier of the segment

lsb - the least significant bits of the identifier of the segment

Returns:

byte buffer containing the segment data or null if segment doesn't exist

Throws:

IOException

containsSegment

boolean containsSegment(long msb,
                        long lsb)

Check if the segment exists.

Parameters:

msb - the most significant bits of the identifier of the segment

lsb - the least significant bits of the identifier of the segment

Returns:

true if the segment exists

writeGraph

void writeGraph(@NotNull
                @org.jetbrains.annotations.NotNull byte[] data)
         throws IOException

Write the graph data.

Parameters:

data - serialized segment graph data

Throws:

IOException

writeBinaryReferences

void writeBinaryReferences(@NotNull
                           @org.jetbrains.annotations.NotNull byte[] data)
                    throws IOException

Write the binary references data.

Parameters:

data - serialized binary references data

Throws:

IOException

getLength

long getLength()

Get the current length of the archive.

Returns:

length of the archive, in bytes

getEntryCount

int getEntryCount()

Get the number of entries currently contained in the archive.

Returns:

number of entries

close

void close()
    throws IOException

Close the archive.

Throws:

IOException

isCreated

boolean isCreated()

Check if the archive has been created (eg. something has been written).

Returns:

true if the archive has been created, false otherwise

flush

void flush()
    throws IOException

Flush all the data to the storage. After returning from this method successfully, all the segments written with the writeSegment(long, long, byte[], int, int, int, int, boolean) should be actually saved to the storage.

Throws:

IOException

getName

@NotNull
@NotNull String getName()

Get the name of the archive.

Returns:

archive name

isRemote

boolean isRemote()

This method returns true if the storage is accessed via a network protocol, not tied to the traditional storage technology, for example, HTTP. Based on that info, for instance, calling classes can decide to update archive metadata (graph, binary references, index) more frequently, and not only when the archive is being closed. With that multiple Oak processes can access the storage simultaneously, with one process in read-write mode and one or more processes in read-only mode.

Returns:

true if the storage is accessed via a network protocol, false otherwise

getMaxEntryCount

int getMaxEntryCount()

This method returns the maximum number of segments that can be supported by the underlying persistence implementation of the archive writer.

Returns:

maximum number of segments supported by the writer implementation