Package org.aksw.commons.io.seekable.api

Interface Seekable

All Superinterfaces:

AutoCloseable, Channel, Closeable, ReadableByteChannel

All Known Implementing Classes:

PageNavigator, SeekableFromBlock

public interface Seekable
extends ReadableByteChannel

Interface that enables relative navigation over data of fixed finite but possibly initially unknown size. Start and end positions can be 'discovered' when a relative operation causes. A Seekable is a ReadableByteChannel but in addition it includes methods for relative seeks and pattern matching methods. The rationale is, that certain operations can be carried out faster if they are pushed to underlying implementation. For example, consider comparing a fixed sequence of bytes to a Seekable: Instead of repeatedly requesting a copies of bytes from the channel, the comparision can be pushed to the seekable which may find out it can delegate the request to an internal buffer. Or it may detect that the operation crosses internal buffer boundaries and handle this case accordingly. The other aspect is, that for relative seeks it is assumed that checking the resources associated with the most recent position first is most likely to generate lookup hits. So with this we can skip a check for whether a global position change should be translated into a relative one. A seekable is backed by a data supplying entity such as a byte array, a ByteBuffer, a FileChannel or a composite thereof. There are two related main features of this interface / trait: One is is that it common matching methods are part of the interface - with emphasis on binary search. The other is, that due to this integrated functionality, internal structures can be abstracted: A matcher can thus transparently run over a sequence of internal blocks without exposing these details. Implementation can provide their own optimized overrides of these matchers, thus significantly speeding up lookups. Methods that perform matching can move the position one byte before or after the backing data region by means of reducing the amount of copying of byte arrays.

Author:

raven

Method Summary

Modifier and Type	Method	Description
default long	binarySearch(long min, long max, byte delimiter, byte[] prefix)	Delimiter-based binary search.
int	checkNext(int len, boolean changePos)	Attempt to advance the position by the given number of bytes.
int	checkPrev(int len, boolean changePos)
Seekable	clone()
default Seekable	cloneObject()	Default method to work around scala bug https://github.com/scala/bug/issues/10501
void	close()
static int	compareArrays(byte[] a, byte[] b)
default int	compareToPrefix(byte[] prefix)	Compare the bytes at the current position to a given sequence of bytes If there are fewer bytes available in the seekable than provide for comparison, then only that many are compared.
default boolean	deltaPos(int delta)	Relative positioning.
default byte	get()	Read a byte at the current position
default byte	get(int relPos)	Get one byte relative to the current position
long	getPos()	Optional operation.
boolean	isPosAfterEnd()	The state of a seekable may be one unit beyond the end.
boolean	isPosBeforeStart()	The state of a seekable may be one unit before the start.
default boolean	nextPos(int len)	Attempt to advance the position by the given number of bytes.
default int	peekNextBytes(byte[] dst, int offset, int len)	Attempt to read bytes at the current position without altering the position
void	posToEnd()	Optional operation.
default boolean	posToNext(byte delimiter)	Move the position to the next delimiter if it exists.
default int	posToNext(byte delimiter, boolean changePos)	0: match but 0 bytes moved negative values indicate no match.
default boolean	posToPrev(byte delimiter)	Move the position to the previous delimiter if it exists, or one element past the end of data such that isPosBeforeStart() yields true.
void	posToStart()	Optional operation.
default boolean	prevPos(int len)	Attempt to step back the position by the given number of bytes.
default int	read(ByteBuffer dst)
String	readString(int len)
void	setPos(long pos)	Optional operation.
default long	size()	The currently known size (of the underlying entity)

Methods inherited from interface java.nio.channels.Channel

isOpen

Method Details

clone

Seekable clone()

cloneObject

default Seekable cloneObject()

Default method to work around scala bug https://github.com/scala/bug/issues/10501

Returns:

getPos

long getPos()
     throws IOException

Optional operation. Get the position in this seekable

Returns:

Throws:

IOException

setPos

void setPos(long pos)
     throws IOException

Optional operation. Get the position in this seekable

Throws:

IOException

posToStart

void posToStart()
         throws IOException

Optional operation. Move one unit before the start of the seekable; raises an exception on infinite seekables

Throws:

IOException

posToEnd

void posToEnd()
       throws IOException

Optional operation. Move to one unit beyond the end of the seekable; raises an exception on infinite seekables

Throws:

IOException

get

default byte get(int relPos)
          throws IOException

Get one byte relative to the current position

Parameters:

relPos -

Returns:

Throws:

IOException

get

default byte get()
          throws IOException

Read a byte at the current position

Returns:

The byte at the current position if the position is valid

Throws:

IOException

isPosBeforeStart

boolean isPosBeforeStart()
                  throws IOException

The state of a seekable may be one unit before the start. In this state, if the seekable is non-empty, nextPos(1) must be a valid position

Returns:

Throws:

IOException

isPosAfterEnd

boolean isPosAfterEnd()
               throws IOException

The state of a seekable may be one unit beyond the end. In this state, if the seekable is non-empty, prevPos(1) must be a valid position

Returns:

Throws:

IOException

nextPos

default boolean nextPos(int len)
                 throws IOException

Attempt to advance the position by the given number of bytes. If the position is valid before the call it will always be valid when the call returns - i.e. in that case isPosBeforeStart and isPosAfterEnd will always be false. Argument must not be negative.

Parameters:

len -

Returns:

True if the position was changed by the requested amount of bytes. False means that the position was unchanged.

Throws:

IOException

checkNext

int checkNext(int len,
 boolean changePos)
       throws IOException

Attempt to advance the position by the given number of bytes. Return the number of bytes by which the position was changed. Returning less bytes than requested implies that a end position was reached which cannot be passed. This method cannot pass beyond the end - i.e. isPosAfterEnd cannot change from false to true by calling this method.

Parameters:

len -

Returns:

Throws:

IOException

prevPos

default boolean prevPos(int len)
                 throws IOException

Attempt to step back the position by the given number of bytes. Argument must not be negative.

Parameters:

len -

Returns:

True if the position was changed by the *requested* amount of bytes. False means that the position was unchanged.

Throws:

IOException

checkPrev

int checkPrev(int len,
 boolean changePos)
       throws IOException

Throws:

IOException

deltaPos

default boolean deltaPos(int delta)
                  throws IOException

Relative positioning. Delegates to nextPos or prevPos based on sign of delta.

Parameters:

delta -

Returns:

Throws:

IOException

peekNextBytes

default int peekNextBytes(byte[] dst,
 int offset,
 int len)
                   throws IOException

Attempt to read bytes at the current position without altering the position

Parameters:

dst -

offset -

len -

Returns:

Throws:

IOException

posToNext

default boolean posToNext(byte delimiter)
                   throws IOException

Move the position to the next delimiter if it exists. Positive result is the number of bytes the position was advanced by this invocation. Negative result indicates that the number of bytes until the end of the seekable - i.e. within that number of bytes no match was found. Move the position to the next delimiter if it exists, or one element past the end of data such that isPosAfterEnd() yields true. Position is unchanged if already at a delimiter

Parameters:

delimiter -

Returns:

true if the position was changed, false otherwise

Throws:

IOException

posToNext

default int posToNext(byte delimiter,
 boolean changePos)
               throws IOException

0: match but 0 bytes moved negative values indicate no match. add +1 to get the number of bytes moved: -1: no match and 0 bytes moved -10: no match and 9 bytes moved

Parameters:

delimiter -

changePos - If no delimiter is found, move the pos to the end

Returns:

Throws:

IOException

posToPrev

default boolean posToPrev(byte delimiter)
                   throws IOException

Move the position to the previous delimiter if it exists, or one element past the end of data such that isPosBeforeStart() yields true. Position is unchanged if already at delimiter

Parameters:

delimiter -

Returns:

true if the position was changed, false otherwise

Throws:

IOException

read

default int read(ByteBuffer dst)
          throws IOException

Specified by:

read in interface ReadableByteChannel

Throws:

IOException

readString

String readString(int len)
           throws IOException

Throws:

IOException

compareToPrefix

default int compareToPrefix(byte[] prefix)
                     throws IOException

Compare the bytes at the current position to a given sequence of bytes If there are fewer bytes available in the seekable than provide for comparison, then only that many are compared. This default implementation uses read(ByteBuffer). Other implementations may override this behavior to compare the given prefix directly against their internal data structures without the intermediate buffer copy due to read.

Parameters:

prefix -

Returns:

Throws:

IOException

compareArrays

static int compareArrays(byte[] a,
 byte[] b)

binarySearch

default long binarySearch(long min,
 long max,
 byte delimiter,
 byte[] prefix)
                   throws IOException

Delimiter-based binary search. delimiter must not appear in prefix Result is the position of the match or -1 if no match was found. Position is set to the first match. TODO Position is undefined if there was no match - which is not optimal - we might want to reset it in that case To reiterate: For fwd / bwd searches, the contract is to move to the next match or beyond the start/end of the stream We might want to change it that if there is a match, then move to it and return true, otherwise leave the position unchanged and return false

Parameters:

min -

max -

delimiter -

prefix -

Returns:

Throws:

IOException

close

void close()
    throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Channel

Specified by:

close in interface Closeable

Throws:

IOException

size

default long size()
           throws IOException

The currently known size (of the underlying entity)

Throws:

IOException