org.deepfs.fsml
Class BufferedFileChannel

java.lang.Object
  extended by org.deepfs.fsml.BufferedFileChannel

public final class BufferedFileChannel
extends Object

Buffered FileChannel implementation.

This implementation is optimized for sequential reading of a file or a fragment of a file. An instance of this class can either represent a regular file on disk or a fragment of a file (the instance is a "subchannel").

Author:
Workgroup DBIS, University of Konstanz 2005-10, ISC License, Bastian Lemke

Field Summary
static int DEFAULT_BUFFER_SIZE
          The default buffer size.
 
Constructor Summary
BufferedFileChannel(File file)
          Standard constructor for creating a BufferedFileChannel from a complete file.
BufferedFileChannel(File file, ByteBuffer buffer)
          Creates a BufferedFileChannel from a complete file and uses the given buffer for caching the data.
BufferedFileChannel(File file, int bufferSize)
          Creates a BufferedFileChannel from a complete file with the given buffer size.
 
Method Summary
 long absolutePosition()
          Returns this channel's absolute position.
 boolean buffer(int n)
           Buffers n bytes, if the underlying buffer is large enough.
 void close()
           Closes the underlying FileChannel.
 void finish()
           Finishes reading from a channel created by subChannel(String, int) .
 int get()
           Relative get method.
 byte[] get(byte[] dst)
          Reads dst.length bytes from the BufferedFileChannel.
 void get(byte[] dst, int start, int length)
           Reads length bytes from the BufferedFileChannel.
 int getBufferSize()
          Returns the size of the buffer.
 ByteOrder getByteOrder()
          Returns this FileChannel's byte order.
 String getFileName()
          Returns the absolute file name of current file.
 int getInt()
           Relative get method.
 long getOffset()
          Returns the offset of this (sub)channel regarding to the regular file in the file system.
 int getShort()
           Relative get method.
 boolean isSubChannel()
          Checks if the current BufferedFileChannel instance is a sub-channel.
 long position()
          Returns this channel's position.
 void position(long newPosition)
          Sets this channel's position.
 String readLine(String inputEncoding)
          Reads a line of text.
 void reset()
          Resets the channel to its initial position.
 void setByteOrder(ByteOrder order)
          Modifies this channel's byte order.
 long size()
          Returns the size of the channel.
 void skip(long n)
          Skips n bytes in the ByteBuffer.
 BufferedFileChannel subChannel(String subfilename, int bytesToRead)
           Creates a "subChannel" view for this BufferedFileChannel instance that shares the underlying FileChannel and buffer.
 String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE
The default buffer size.

See Also:
Constant Field Values
Constructor Detail

BufferedFileChannel

public BufferedFileChannel(File file)
                    throws IOException
Standard constructor for creating a BufferedFileChannel from a complete file.

Parameters:
file - the file to read from
Throws:
IOException - if any error occurs while creating the BufferedFileChannel

BufferedFileChannel

public BufferedFileChannel(File file,
                           int bufferSize)
                    throws IOException
Creates a BufferedFileChannel from a complete file with the given buffer size.

Parameters:
file - the file to read from
bufferSize - the size of the buffer
Throws:
IOException - if any error occurs while creating the BufferedFileChannel

BufferedFileChannel

public BufferedFileChannel(File file,
                           ByteBuffer buffer)
                    throws IOException
Creates a BufferedFileChannel from a complete file and uses the given buffer for caching the data. This constructor can be used for creating many BufferedFileChannel instances (consecutively) with the same direct byte buffer to avoid the allocation- and garbage-collection-overhead for multiple direct byte buffers.

Parameters:
file - the file to read from
buffer - the ByteBuffer to use for caching the data
Throws:
IOException - if any error occurs while creating the BufferedFileChannel
Method Detail

subChannel

public BufferedFileChannel subChannel(String subfilename,
                                      int bytesToRead)
                               throws IOException

Creates a "subChannel" view for this BufferedFileChannel instance that shares the underlying FileChannel and buffer.

The content of the new channel will start at this channel's current position and it's size depends on the given parameter bytesToRead.

The original channel must not be used before finish() has been called on the BufferedFileChannel created by this method. After finishing the subChannel, the original channel's position is incremented by bytesToRead.

Parameters:
subfilename - the name of the subfile
bytesToRead - the maximum number of bytes to read
Returns:
the new "subChannel"
Throws:
IOException - if any error occurs while creating the channel

getBufferSize

public int getBufferSize()
Returns the size of the buffer.

Returns:
the size of the buffer

skip

public void skip(long n)
          throws IOException
Skips n bytes in the ByteBuffer.

Parameters:
n - number of bytes to skip. May be negative
Throws:
IOException - if any error occurs while reading the file

position

public long position()
              throws IOException
Returns this channel's position.

Returns:
This channel's position, a non-negative integer counting the number of bytes from the beginning of the channel to the current position
Throws:
IOException - if any error occurs while reading from the channel

absolutePosition

public long absolutePosition()
                      throws IOException
Returns this channel's absolute position.

Returns:
this channel's absolute position
Throws:
IOException - if any error occurs while reading from the channel

position

public void position(long newPosition)
              throws IOException
Sets this channel's position.

Parameters:
newPosition - the new position, a non-negative integer counting the number of bytes from the beginning of the channel
Throws:
IOException - if any error occurs while reading from the channel

size

public long size()
          throws IOException
Returns the size of the channel.

Returns:
the size of the channel
Throws:
IOException - if any error occurs while calculating the size

isSubChannel

public boolean isSubChannel()
                     throws IOException
Checks if the current BufferedFileChannel instance is a sub-channel.

Returns:
true if the current instance is a sub-channel
Throws:
IOException - if any i/o error occurs

reset

public void reset()
           throws IOException
Resets the channel to its initial position.

Throws:
IOException - if any error occurs while reading from the channel

get

public byte[] get(byte[] dst)
           throws IOException
Reads dst.length bytes from the BufferedFileChannel.

Parameters:
dst - the arrray to write the data to
Returns:
the filled byte array
Throws:
IOException - if there are less than dst.length bytes available or any error occurs while reading from the channel

get

public void get(byte[] dst,
                int start,
                int length)
         throws IOException

Reads length bytes from the BufferedFileChannel.

Assure that that the buffer is large enough and that enough bytes are buffered (via buffer(int)). Otherwise, a BufferUnderflowException may be thrown.

Parameters:
dst - the arrray to write the data to
start - the first position to write the data to
length - the number of bytes to read
Throws:
IOException - if the channel is locked

get

public int get()
        throws IOException

Relative get method. Reads the byte at this channel's current position, and then increments the position.

Assure that enough at least one byte is buffered via #buffer(1). Otherwise, a BufferUnderflowException may be thrown.

Returns:
The byte at the channel's current position
Throws:
IOException - if the channel is locked

getShort

public int getShort()
             throws IOException

Relative get method. Reads two bytes at this channel's current position, and then increments the position by two.

Assure that enough at least two bytes are buffered via #buffer(2). Otherwise, a BufferUnderflowException may be thrown.

Returns:
The next two bytes at the channel's current position as integer
Throws:
IOException - if the channel is locked

getInt

public int getInt()
           throws IOException

Relative get method. Reads four bytes at this channel's current position, and then increments the position by four.

Assure that enough at least four bytes are buffered via #buffer(4). Otherwise, a BufferUnderflowException may be thrown.

Returns:
The next four bytes at the channel's current position as integer
Throws:
IOException - if the channel is locked

finish

public void finish()
            throws IOException

Finishes reading from a channel created by subChannel(String, int) . Any subsequent read from this BufferedFileChannel will fail.

This method must be called for every BufferedFileChannel that was created by subChannel(String, int) instead of calling close() .

Throws:
IOException - if any error occurs while finishing the channel
See Also:
close()

close

public void close()
           throws IOException

Closes the underlying FileChannel.

This method must not be called for BufferedFileChannel instances that were created by subChannel(String, int).

Throws:
IOException - if any error occurs while closing the FileChannel
See Also:
finish()

buffer

public boolean buffer(int n)
               throws IOException

Buffers n bytes, if the underlying buffer is large enough. Does nothing, if the buffer is too small.

Parameters:
n - the number of bytes to buffer
Returns:
true if the buffer is large enough to contain all n bytes, false if it is too small
Throws:
IOException - if any error occurs while reading the file

getFileName

public String getFileName()
Returns the absolute file name of current file.

Returns:
the file name

getOffset

public long getOffset()
Returns the offset of this (sub)channel regarding to the regular file in the file system.

Returns:
the offset of the current subchannel inside the regular file or zero if this file channel is not a subchannel

setByteOrder

public void setByteOrder(ByteOrder order)
Modifies this channel's byte order. The byte order is only relevant for the getShort() and getInt() methods.

Parameters:
order - The new byte order, either BIG_ENDIAN or LITTLE_ENDIAN

getByteOrder

public ByteOrder getByteOrder()
Returns this FileChannel's byte order.

Returns:
the ByteOrder

readLine

public String readLine(String inputEncoding)
                throws IOException
Reads a line of text. A line is considered to be terminated by any one of a line feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately by a line feed.

Parameters:
inputEncoding - the input encoding
Returns:
A (UTF-8-)String containing the contents of the line, not including any line-termination characters, or null if the end of the stream has been reached
Throws:
IOException - if an I/O error occurs

toString

public String toString()
Overrides:
toString in class Object