org.jdtaus.core.io
Interface FileOperations

public interface FileOperations

Elementary I/O operations.

Version:

$Id: FileOperations.java 8044 2009-07-02 01:29:05Z schulte2005 $

Author:

Christian Schulte

Field Summary

static int

EOF Constant returned by the read(byte[],int,int) method if the end of the file has been reached.

Method Summary

void	close() Releases any system resources associated with an instance.
long	getFilePointer() Returns the current offset in the file.
long	getLength() Gets the length of the file.
int	read(byte[] buf, int off, int len) Reads up to len bytes of data from the file into an array of bytes.
void	read(OutputStream out) Reads all data from the file to some OutputStream.
void	setFilePointer(long pos) Sets the file-pointer offset, measured from the beginning of the file, at which the next read or write occurs.
void	setLength(long newLength) Sets the length of the file.
void	write(byte[] buf, int off, int len) Writes len bytes from the specified byte array starting at offset off to the file.
void	write(InputStream in) Writes all data available from some InputStream.

Field Detail

EOF

static final int EOF

Constant returned by the read(byte[],int,int) method if the end of the file has been reached.

See Also:

Constant Field Values

Method Detail

close

void close()
           throws IOException

Releases any system resources associated with an instance. A closed instance cannot perform input or output operations and cannot be reopened.

Throws:

IOException - if releasing system resources fails.

getFilePointer

long getFilePointer()
                    throws IOException

Returns the current offset in the file.

Returns:

the offset from the beginning of the file, in bytes, at which the next read or write occurs.

Throws:

IOException - if getting the current offset in the file fails.

getLength

long getLength()
               throws IOException

Gets the length of the file.

Returns:

the length measured in bytes.

Throws:

IOException - if getting the length fails.

read

int read(byte[] buf,
         int off,
         int len)
         throws IOException

Reads up to len bytes of data from the file into an array of bytes. An attempt is made to read as many as len bytes, but a smaller number may be read.

Parameters:

buf - the buffer into which the data is read.

off - the start offset of the data.

len - the maximum number of bytes read.

Returns:

the total number of bytes read into the buffer, or EOF if there is no more data because the end of the file has been reached.

Throws:

NullPointerException - if buf is null.

IndexOutOfBoundsException - if either off or len is negative or off + len is greater than the length of buf.

IOException - if reading fails.

read

void read(OutputStream out)
          throws IOException

Reads all data from the file to some OutputStream. The stream will not get closed after all data has been written.

Parameters:

out - an output stream to stream to.

Throws:

NullPointerException - if out is null.

IOException - if reading fails.

setFilePointer

void setFilePointer(long pos)
                    throws IOException

Sets the file-pointer offset, measured from the beginning of the file, at which the next read or write occurs. The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change the file length. The file length will change only by writing after the offset has been set beyond the end of the file.

Parameters:

pos - the offset position, measured in bytes from the beginning of the file, at which to set the file pointer.

Throws:

IllegalArgumentException - if pos is negative.

IOException - if setting the file-pointer offset fails.

setLength

void setLength(long newLength)
               throws IOException

Sets the length of the file.

If the present length of the file as returned by the getLength() method is greater than the newLength argument then the file will be truncated. In this case, if the file offset as returned by the getFilePointer() method is greater than newLength then after this method returns the offset will be equal to newLength.

If the present length of the file as returned by the getLength() method is smaller than the newLength argument then the file will be extended. In this case, the contents of the extended portion of the file are not defined.

Parameters:

newLength - The desired length of the file.

Throws:

IllegalArgumentException - if newLength is negative.

IOException - if setting the length fails.

write

void write(byte[] buf,
           int off,
           int len)
           throws IOException

Writes len bytes from the specified byte array starting at offset off to the file.

Parameters:

buf - the data.

off - the start offset in the data.

len - the number of bytes to write.

Throws:

IndexOutOfBoundsException - if either off or len is negative or off + len is greater than the length of buf.

IOException - if writing fails.

write

void write(InputStream in)
           throws IOException

Writes all data available from some InputStream. The stream will not get closed after all data has been read.

Parameters:

in - an input stream providing the data to be written.

Throws:

NullPointerException - if in is null.

IOException - if writing fails.