Interface Seekable
-
- All Known Implementing Classes:
FileCacheSeekableStream
,FileSeekableStream
,MemoryCacheSeekableStream
,RandomAccessStream
,SeekableInputStream
,SeekableOutputStream
public interface Seekable
Interface for seekable streams.- Version:
- $Id: //depot/branches/personal/haraldk/twelvemonkeys/release-2/twelvemonkeys-core/src/main/java/com/twelvemonkeys/io/Seekable.java#1 $
- Author:
- Harald Kuhr
- See Also:
SeekableInputStream
,SeekableOutputStream
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
close()
Closes the stream.void
flush()
Discards the initial position of the stream prior to the current stream position.void
flushBefore(long pPosition)
Discards the initial portion of the stream prior to the indicated postion.long
getFlushedPosition()
Returns the earliest position in the stream to which seeking may be performed.long
getStreamPosition()
Returns the current byte position of the stream.boolean
isCached()
Returns true if thisSeekable
stream caches data itself in order to allow seeking backwards.boolean
isCachedFile()
Returns true if thisSeekable
stream caches data itself in order to allow seeking backwards, and the cache is kept in a temporary file.boolean
isCachedMemory()
Returns true if thisSeekable
stream caches data itself in order to allow seeking backwards, and the cache is kept in main memory.void
mark()
Marks a position in the stream to be returned to by a subsequent call to reset.void
reset()
Returns the file pointer to its previous position, at the time of the most recent unmatched call to mark.void
seek(long pPosition)
Sets the current stream position to the desired location.
-
-
-
Method Detail
-
getStreamPosition
long getStreamPosition() throws java.io.IOException
Returns the current byte position of the stream. The next read will take place starting at this offset.- Returns:
- a
long
containing the position of the stream. - Throws:
java.io.IOException
- if an I/O error occurs.
-
seek
void seek(long pPosition) throws java.io.IOException
Sets the current stream position to the desired location. The next read will occur at this location.An
IndexOutOfBoundsException
will be thrown if pPosition is smaller than the flushed position (as returned bygetFlushedPosition()
).It is legal to seek past the end of the file; an
EOFException
will be thrown only if a read is performed.- Parameters:
pPosition
- a long containing the desired file pointer position.- Throws:
java.lang.IndexOutOfBoundsException
- ifpPosition
is smaller than the flushed position.java.io.IOException
- if any other I/O error occurs.
-
mark
void mark()
Marks a position in the stream to be returned to by a subsequent call to reset. Unlike a standardInputStream
, allSeekable
streams upport marking. Additionally, calls tomark
andreset
may be nested arbitrarily.Unlike the
mark
methods declared by theReader
orInputStream
interfaces, noreadLimit
parameter is used. An arbitrary amount of data may be read following the call tomark
.
-
reset
void reset() throws java.io.IOException
Returns the file pointer to its previous position, at the time of the most recent unmatched call to mark.Calls to reset without a corresponding call to mark will either:
- throw an
IOException
- or, reset to the beginning of the stream.
An
IOException
will be thrown if the previous marked position lies in the discarded portion of the stream.- Throws:
java.io.IOException
- if an I/O error occurs.- See Also:
InputStream.reset()
- throw an
-
flushBefore
void flushBefore(long pPosition) throws java.io.IOException
Discards the initial portion of the stream prior to the indicated postion. Attempting to seek to an offset within the flushed portion of the stream will result in anIndexOutOfBoundsException
.Calling
flushBefore
may allow classes implementing this interface to free up resources such as memory or disk space that are being used to store data from the stream.- Parameters:
pPosition
- a long containing the length of the file prefix that may be flushed.- Throws:
java.lang.IndexOutOfBoundsException
- ifpPosition
lies in the flushed portion of the stream or past the current stream position.java.io.IOException
- if an I/O error occurs.
-
flush
void flush() throws java.io.IOException
Discards the initial position of the stream prior to the current stream position. Equivalent toflushBefore(getStreamPosition())
.- Throws:
java.io.IOException
- if an I/O error occurs.
-
getFlushedPosition
long getFlushedPosition() throws java.io.IOException
Returns the earliest position in the stream to which seeking may be performed. The returned value will be the maximum of all values passed into previous calls toflushBefore
.- Returns:
- the earliest legal position for seeking, as a
long
. - Throws:
java.io.IOException
- if an I/O error occurs.
-
isCached
boolean isCached()
Returns true if thisSeekable
stream caches data itself in order to allow seeking backwards. Applications may consult this in order to decide how frequently, or whether, to flush in order to conserve cache resources.- Returns:
true
if thisSeekable
caches data.- See Also:
isCachedMemory()
,isCachedFile()
-
isCachedMemory
boolean isCachedMemory()
Returns true if thisSeekable
stream caches data itself in order to allow seeking backwards, and the cache is kept in main memory. Applications may consult this in order to decide how frequently, or whether, to flush in order to conserve cache resources.- Returns:
true
if thisSeekable
caches data in main memory.- See Also:
isCached()
,isCachedFile()
-
isCachedFile
boolean isCachedFile()
Returns true if thisSeekable
stream caches data itself in order to allow seeking backwards, and the cache is kept in a temporary file. Applications may consult this in order to decide how frequently, or whether, to flush in order to conserve cache resources.- Returns:
true
if thisSeekable
caches data in a temporary file.- See Also:
isCached()
,isCachedMemory()
-
close
void close() throws java.io.IOException
Closes the stream.- Throws:
java.io.IOException
- if the stream can't be closed.
-
-