org.entityfs.util
Class Files

java.lang.Object
  org.entityfs.util.Files

public final class Files
extends Object

This class contains static methods for working with EFile:s.

The Entities utility class contains utility methods that complement the methods in this class.

The methods in this class will use the locking strategy for utility classes described in EntityLock.

The StreamUtil class contains utility methods for working with streams.

Since:

1.0

Author:

Karl Gustafsson

See Also:

EFile, Entities

Method Summary

static <T extends WritableFile> T	appendFromChannel(T f, ReadableByteChannel c) Append binary data read from the provided ReadableByteChannel to the file.
static <T extends WritableFile> T	appendFromFile(T target, ReadableFile source) Append data from the source file to a file.
static <T extends WritableFile> T	appendFromInputStream(T f, InputStream is) Append binary data read from the provided InputStream to the file.
static <T extends WritableFile> T	appendFromReader(T f, Reader r) Append character data read from the provided Reader to the file.
static <T extends WritableFile> T	appendFromReader(T f, Reader r, Charset cs) Append character data read from the provided Reader to the file.
static <T extends WritableFile> T	appendText(T target, CharSequence source) Append text to a file.
static <T extends WritableFile> T	appendText(T target, CharSequence source, Charset cs) Append text to a file using a specified character encoding.
static <T extends WritableFile> T	copyContents(ReadableFile f1, T f2) Copy the contents of f1 to f2, replacing f2's previous contents.
static long	getDataSize(ReadableFile f) Get the size of the file's data in bytes.
static long	getSize(ReadableFile f) Get the size of the file in bytes.
static CloseableIterator<String>	lineIterator(ReadableFile f) Get an iterator over all lines in the supplied text file.
static CloseableIterator<String>	lineIterator(ReadableFile f, Charset cs) Get an iterator over all lines in the supplied text file.
static long	measureDataSize(ReadableFile f) Get the size of the file's data in bytes by counting them.
static WritableByteChannel	openChannelForAppend(WritableFile f) Open the file for writing and return a channel.
static WritableByteChannel	openChannelForAppend(WritableFile f, EntityLock writeLock) Open the file for writing and return a lock-aware channel.
static ReadableByteChannel	openChannelForRead(ReadableFile f) Open the file for reading and return a channel.
static ReadableByteChannel	openChannelForRead(ReadableFile f, EntityLock readLock) Open the file for reading and return a lock-aware channel.
static WritableByteChannel	openChannelForWrite(WritableFile f) Open the file for writing and return a channel.
static WritableByteChannel	openChannelForWrite(WritableFile f, EntityLock writeLock) Open the file for writing and return a lock-aware channel.
static OutputStream	openForAppend(WritableFile f) Open the file for writing and return an output stream.
static OutputStream	openForAppend(WritableFile f, EntityLock writeLock) Open the file for writing and return a lock-aware output stream.
static RandomAccess	openForRandomAccess(RandomlyAccessibleFile f, RandomAccessMode mode) Open the file for random access.
static RandomAccess	openForRandomAccess(RandomlyAccessibleFile f, RandomAccessMode mode, EntityLock lock) Open the file for random access.
static InputStream	openForRead(ReadableFile f) Open the file for reading and return an input stream.
static InputStream	openForRead(ReadableFile f, EntityLock readLock) Open the file for reading and return a lock-aware input stream.
static OutputStream	openForWrite(WritableFile f) Open the file for writing and return an output stream.
static OutputStream	openForWrite(WritableFile f, EntityLock writeLock) Open the file for writing and return a lock-aware output stream.
static byte[]	readBinaryFile(ReadableFile f) Read the contents of the file into a byte array and return the array.
static String	readTextFile(ReadableFile f) Read a text file and return the contents.
static String	readTextFile(ReadableFile f, Charset cs) Read a text file and return the contents.
static <T extends ReadWritableFile> T	replaceContents(T f1, ReadWritableFile f2) Replace the contents of file f1 with the contents of f2 and delete f2.
static <T extends WritableFile> T	writeData(T target, byte[] source) Write the contents of the byte array to the file.
static <T extends WritableFile> T	writeFromChannel(T f, ReadableByteChannel c) Write binary data read from the provided ReadableByteChannel to the file.
static <T extends WritableFile> T	writeFromFile(T target, ReadableFile source) Write data from the source file to a file.
static <T extends WritableFile> T	writeFromInputStream(T f, InputStream is) Write binary data read from the provided InputStream to the file.
static <T extends WritableFile> T	writeFromReader(T f, Reader r) Write character data read from the provided Reader to the file.
static <T extends WritableFile> T	writeFromReader(T f, Reader r, Charset cs) Write character data read from the provided Reader to the file.
static <T extends WritableFile> T	writeText(T target, CharSequence source) Write text to a file.
static <T extends WritableFile> T	writeText(T target, CharSequence source, Charset cs) Write text to a file encoding it with the supplied character encoding.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

openForRead

public static InputStream openForRead(ReadableFile f,
                                      EntityLock readLock)
                               throws AccessDeniedException

Open the file for reading and return a lock-aware input stream. The stream will close the supplied read lock when closed.

The returned stream will require the thread using it to have a read lock for the open file. If the stream is handed off to another thread, that thread has to acquire a read lock manually before using it.

In case of errors in this method, the read lock will be unlocked before the method exits.

Parameters:

f - The file to open for reading.

readLock - A locked read lock for the file.

Returns:

A lock-aware input stream.

Throws:

AccessDeniedException - If the calling thread does not have read access to the file.

See Also:

ReadableFile.openForRead(), openForRead(ReadableFile)

Permissions_required:

Read access.

openForRead

public static InputStream openForRead(ReadableFile f)
                               throws AccessDeniedException

Open the file for reading and return an input stream. This method will lock the file for reading. The lock is released when the input stream is closed.

The returned stream will require the thread using it to have a read lock for the open file. This method automatically acquires a read lock for the thread that calls it, but if the stream is handed off to another thread, that thread has to acquire a read lock manually before using it.

Parameters:

f - The file to open for reading.

Returns:

An open input stream. The read lock on the entity will be released when the stream is closed.

Throws:

AccessDeniedException - If the calling thread does not have read access to the file.

See Also:

ReadableFile.openForRead(), openForRead(ReadableFile, EntityLock)

Permissions_required:

Read access.

openChannelForRead

public static ReadableByteChannel openChannelForRead(ReadableFile f,
                                                     EntityLock readLock)
                                              throws AccessDeniedException

Open the file for reading and return a lock-aware channel. The channel will close the supplied read lock when closed.

The returned channel will require the thread using it to have a read lock for the open file. If the channel is handed off to another thread, that thread has to acquire a read lock manually before using it.

In case of errors in this method, the read lock will be unlocked before the method exits.

Parameters:

f - The file to open for reading.

readLock - A locked read lock for the file.

Returns:

A lock-aware channel.

Throws:

AccessDeniedException - If the calling thread does not have read access to the file.

See Also:

ReadableFile.openChannelForRead(), openChannelForRead(ReadableFile)

Permissions_required:

Read access.

openChannelForRead

public static ReadableByteChannel openChannelForRead(ReadableFile f)
                                              throws AccessDeniedException

Open the file for reading and return a channel. This method will lock the file for reading. The lock is released when the channel is closed.

The returned channel will require the thread using it to have a read lock for the open file. This method automatically acquires a read lock for the thread that calls it, but if the channel is handed off to another thread, that thread has to acquire a read lock manually before using it.

Parameters:

f - The file to open for reading.

Returns:

An open channel. The read lock on the entity will be released when the channel is closed.

Throws:

AccessDeniedException - If the calling thread does not have read access to the file.

See Also:

ReadableFile.openForRead(), openForRead(ReadableFile, EntityLock)

Permissions_required:

Read access.

openForWrite

public static OutputStream openForWrite(WritableFile f,
                                        EntityLock writeLock)
                                 throws ReadOnlyException,
                                        AccessDeniedException

Open the file for writing and return a lock-aware output stream. The previous contents of the file is discarded. The returned stream will close the supplied write lock when closed.

The returned stream will require the thread using it to have a write lock for the open file. If the stream is handed off to another thread, that thread has to acquire a write lock manually before using it.

In case of errors in this method, the write lock will be unlocked before the method exits.

Parameters:

f - The file to open for writing.

writeLock - A locked write lock for the file.

Returns:

A lock-aware output stream.

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

See Also:

WritableFile.openForWrite(), openForWrite(WritableFile)

Permissions_required:

Write access.

openForWrite

public static OutputStream openForWrite(WritableFile f)
                                 throws ReadOnlyException,
                                        AccessDeniedException

Open the file for writing and return an output stream. This method will lock the file for writing. The lock is released when the output stream is closed.

The returned stream will require the thread using it to have a write lock for the open file. This method automatically acquires a write lock for the thread that calls it, but if the stream is handed off to another thread, that thread has to acquire a write lock manually before using it.

Parameters:

f - The file to open for writing.

Returns:

An open output stream. The write lock on the entity will be released when the stream is closed.

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

See Also:

WritableFile.openForWrite(), openForWrite(WritableFile, EntityLock)

Permissions_required:

Write access.

openChannelForWrite

public static WritableByteChannel openChannelForWrite(WritableFile f,
                                                      EntityLock writeLock)
                                               throws ReadOnlyException,
                                                      AccessDeniedException

Open the file for writing and return a lock-aware channel. The previous contents of the file is discarded. The returned channel will close the supplied write lock when closed.

The returned channel will require the thread using it to have a write lock for the open file. If the channel is handed off to another thread, that thread has to acquire a write lock manually before using it.

In case of errors in this method, the write lock will be unlocked before the method exits.

Parameters:

f - The file to open for writing.

writeLock - A locked write lock for the file.

Returns:

A lock-aware channel.

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

See Also:

WritableFile.openForWrite(), openForWrite(WritableFile)

Permissions_required:

Write access.

openChannelForWrite

public static WritableByteChannel openChannelForWrite(WritableFile f)
                                               throws ReadOnlyException,
                                                      AccessDeniedException

Open the file for writing and return a channel. This method will lock the file for writing. The lock is released when the channel is closed.

The returned channel will require the thread using it to have a write lock for the open file. This method automatically acquires a write lock for the thread that calls it, but if the channel is handed off to another thread, that thread has to acquire a write lock manually before using it.

Parameters:

f - The file to open for writing.

Returns:

An open channel. The write lock on the entity will be released when the channel is closed.

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

See Also:

WritableFile.openForWrite(), openForWrite(WritableFile, EntityLock)

Permissions_required:

Write access.

openForAppend

public static OutputStream openForAppend(WritableFile f,
                                         EntityLock writeLock)
                                  throws ReadOnlyException,
                                         AccessDeniedException

Open the file for writing and return a lock-aware output stream. The data written to the file will be appended its the previous contents. The returned stream will close the supplied write lock when closed.

The returned stream will require the thread using it to have a write lock for the open file. If the stream is handed off to another thread, that thread has to acquire a write lock manually before using it.

In case of errors in this method, the write lock will be unlocked before the method exits.

Parameters:

f - The file to open for writing.

writeLock - A locked write lock for the file.

Returns:

A lock-aware output stream.

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

See Also:

WritableFile.openForAppend(), openForAppend(WritableFile)

Permissions_required:

Write access.

openForAppend

public static OutputStream openForAppend(WritableFile f)
                                  throws ReadOnlyException,
                                         AccessDeniedException

Open the file for writing and return an output stream. The data written to the file will be appended its the previous contents. This method will lock the file for writing. The lock is released when the output stream is closed.

The returned stream will require the thread using it to have a write lock for the open file. This method automatically acquires a write lock for the thread that calls it, but if the stream is handed off to another thread, that thread has to acquire a write lock manually before using it.

Parameters:

f - The file to open for writing.

Returns:

A lock-aware output stream.

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

See Also:

WritableFile.openForAppend(), openForAppend(WritableFile, EntityLock)

Permissions_required:

Write access.

openChannelForAppend

public static WritableByteChannel openChannelForAppend(WritableFile f,
                                                       EntityLock writeLock)
                                                throws ReadOnlyException,
                                                       AccessDeniedException

Open the file for writing and return a lock-aware channel. The data written to the file will be appended its the previous contents. The returned channel will close the supplied write lock when closed.

The returned channel will require the thread using it to have a write lock for the open file. If the channel is handed off to another thread, that thread has to acquire a write lock manually before using it.

In case of errors in this method, the write lock will be unlocked before the method exits.

Parameters:

f - The file to open for writing.

writeLock - A locked write lock for the file.

Returns:

A lock-aware channel.

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

Permissions_required:

Write access.

openChannelForAppend

public static WritableByteChannel openChannelForAppend(WritableFile f)
                                                throws ReadOnlyException,
                                                       AccessDeniedException

Open the file for writing and return a channel. The data written to the file will be appended its the previous contents. This method will lock the file for writing. The lock is released when the channel is closed.

The returned channel will require the thread using it to have a write lock for the open file. This method automatically acquires a write lock for the thread that calls it, but if the channel is handed off to another thread, that thread has to acquire a write lock manually before using it.

Parameters:

f - The file to open for writing.

Returns:

A lock-aware channel.

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

See Also:

WritableFile.openForAppend(), openForAppend(WritableFile, EntityLock)

Permissions_required:

Write access.

openForRandomAccess

public static RandomAccess openForRandomAccess(RandomlyAccessibleFile f,
                                               RandomAccessMode mode,
                                               EntityLock lock)
                                        throws ReadOnlyException,
                                               AccessDeniedException,
                                               UnsupportedCapabilityException

Open the file for random access. The supplied lock is released when the returned RandomAccess is closed.

The returned random access will require the thread using it to have a read or write lock for the open file, depending on the random access mode. If the channel is handed off to another thread, that thread has to acquire a lock manually before using it.

Parameters:

f - The file to open.

mode - The mode to open the file in.

lock - A locked read or write lock for the entity.

Returns:

A lock-aware RandomAccess.

Throws:

ReadOnlyException - If a read only file is open for writing.

AccessDeniedException - If the calling thread does not have sufficient access to the file.

UnsupportedCapabilityException - If the file system does not support the FSCRandomAccessFiles capability.

Permissions_required:

Read access if the file is opened for reading. Read and write access if it is opened for reading and writing.

openForRandomAccess

public static RandomAccess openForRandomAccess(RandomlyAccessibleFile f,
                                               RandomAccessMode mode)
                                        throws ReadOnlyException,
                                               AccessDeniedException,
                                               UnsupportedCapabilityException

Open the file for random access. This method locks the file for reading (if opened read only) or for writing. The lock is released when the returned RandomAccess is closed.

The returned random access will require the thread using it to have a read or write lock for the open file, depending on the random access mode. This method automatically acquires a lock for the thread that calls it, but if the channel is handed off to another thread, that thread has to acquire a lock manually before using it.

Parameters:

f - The file to open.

mode - The mode to open the file in.

Returns:

A lock-aware RandomAccess.

Throws:

ReadOnlyException - If a read only file is open for writing.

AccessDeniedException - If the calling thread does not have sufficient access to the file.

UnsupportedCapabilityException - If the file system does not support the FSCRandomAccessFiles capability.

Permissions_required:

Read access if the file is opened for reading. Read and write access if it is opened for reading and writing.

getSize

public static long getSize(ReadableFile f)
                    throws AccessDeniedException

Get the size of the file in bytes. This is the size of the file in the file system. If data in the file is compressed, the size of the file's data (as returned from getDataSize(ReadableFile) is greater than this size.

Parameters:

f - The file.

Returns:

The size of the file in bytes.

Throws:

AccessDeniedException - If the calling thread does not have read access to the file.

See Also:

getDataSize(ReadableFile), measureDataSize(ReadableFile)

Permissions_required:

Read access.

getDataSize

public static long getDataSize(ReadableFile f)
                        throws AccessDeniedException

Get the size of the file's data in bytes. This may be larger than the result returned from getSize(ReadableFile) if the file is compressed.

Warning: Calculating the file's data size may be really slow, depending on the file implementation. The entire file might have to be read.

Parameters:

f - The file.

Returns:

The size of the file's data in bytes.

Throws:

AccessDeniedException - If the calling thread does not have read access to the file.

See Also:

getSize(ReadableFile), measureDataSize(ReadableFile)

Permissions_required:

Read access.

measureDataSize

public static long measureDataSize(ReadableFile f)
                            throws AccessDeniedException,
                                   WrappedIOException

Get the size of the file's data in bytes by counting them. This may be really slow, depending on the size of the file, etc.

Parameters:

f - The file.

Returns:

The size of the file's data in bytes.

Throws:

AccessDeniedException - If the calling thread does not have read access to the file.

WrappedIOException - On I/O errors.

See Also:

getSize(ReadableFile), getDataSize(ReadableFile)

Permissions_required:

Read access.

readTextFile

public static String readTextFile(ReadableFile f,
                                  Charset cs)
                           throws AccessDeniedException

Read a text file and return the contents. The file contents is converted to a String using the provided Charset.

Parameters:

f - The text file.

cs - The java.nio.charset.Charset to use to decode the file contents.

Returns:

The file contents. If the file is empty, a zero-length string is returned.

Throws:

AccessDeniedException - If the calling thread does not have read access to the file.

Permissions_required:

Read access.

readTextFile

public static String readTextFile(ReadableFile f)
                           throws AccessDeniedException

Read a text file and return the contents. The file contents is converted to a string using the platform's default Charset.

Parameters:

f - The text file.

Returns:

The file contents.

Throws:

AccessDeniedException - If the calling thread does not have read access to the file.

Permissions_required:

Read access.

readBinaryFile

public static byte[] readBinaryFile(ReadableFile f)

Read the contents of the file into a byte array and return the array.

Parameters:

f - The file.

Returns:

The file contents, as a byte array. If the file is empty, an array of length 0 is returned.

Permissions_required:

Read access.

writeFromInputStream

public static <T extends WritableFile> T writeFromInputStream(T f,
                                                              InputStream is)
                                                   throws ReadOnlyException,
                                                          AccessDeniedException,
                                                          WrappedIOException

Write binary data read from the provided InputStream to the file. The previous contents of the file is discarded. The file is locked for write during the operation.

Parameters:

f - The file to write to.

is - The InputStream to read binary data from. The stream is not closed by this method.

Returns:

f

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On any read or write errors.

See Also:

appendFromReader(WritableFile, Reader), writeFromInputStream(WritableFile, InputStream), appendFromFile(WritableFile, ReadableFile)

Permissions_required:

Write access.

writeFromReader

public static <T extends WritableFile> T writeFromReader(T f,
                                                         Reader r,
                                                         Charset cs)
                                              throws ReadOnlyException,
                                                     AccessDeniedException,
                                                     WrappedIOException

Write character data read from the provided Reader to the file. The previous contents of the file is discarded. The data is written using the provided Charset. The file is locked for writing during the operation.

Parameters:

f - The file to write to.

r - The Reader to read character data from. The reader is not closed by this method.

cs - The Charset of the character data.

Returns:

f

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On any read or write errors.

See Also:

writeFromReader(WritableFile, Reader), appendFromReader(WritableFile, Reader), writeFromInputStream(WritableFile, InputStream)

Permissions_required:

Write access.

writeFromReader

public static <T extends WritableFile> T writeFromReader(T f,
                                                         Reader r)
                                              throws ReadOnlyException,
                                                     AccessDeniedException,
                                                     WrappedIOException

Write character data read from the provided Reader to the file. The previous contents of the file is discarded. The data is written using the platform's default Charset. The file is locked for writing during the operation.

Parameters:

f - The file to write to.

r - The Reader to read character data from. The reader is not closed by this method.

Returns:

f

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On any read or write errors.

See Also:

writeFromReader(WritableFile, Reader, Charset), appendFromReader(WritableFile, Reader), writeFromInputStream(WritableFile, InputStream)

Permissions_required:

Write access.

writeFromChannel

public static <T extends WritableFile> T writeFromChannel(T f,
                                                          ReadableByteChannel c)
                                               throws ReadOnlyException,
                                                      AccessDeniedException,
                                                      WrappedIOException

Write binary data read from the provided ReadableByteChannel to the file. The previous contents of the file is discarded. The file is locked for writing during the operation.

Parameters:

f - The file to write to.

c - The ReadableByteChannel to read binary data from. The channel is not closed by this method.

Returns:

f

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On any read or write errors.

Permissions_required:

Write access.

appendFromInputStream

public static <T extends WritableFile> T appendFromInputStream(T f,
                                                               InputStream is)
                                                    throws ReadOnlyException,
                                                           AccessDeniedException,
                                                           WrappedIOException

Append binary data read from the provided InputStream to the file. The file is locked for writing during the operation.

Parameters:

f - The file to write to.

is - The InputStream to read binary data from. The stream is not closed by this method.

Returns:

f

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On any read or write errors.

See Also:

appendFromReader(WritableFile, Reader), writeFromInputStream(WritableFile, InputStream), appendFromFile(WritableFile, ReadableFile)

Permissions_required:

Write access.

appendFromReader

public static <T extends WritableFile> T appendFromReader(T f,
                                                          Reader r,
                                                          Charset cs)
                                               throws ReadOnlyException,
                                                      AccessDeniedException,
                                                      WrappedIOException

Append character data read from the provided Reader to the file. The data is written using the provided Charset. The file is locked for writing during the operation.

Parameters:

f - The file to write to.

r - The Reader to read character data from. The reader is not closed by this method.

cs - The Charset to use when writing to the target file.

Returns:

f

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On any read or write errors.

See Also:

appendFromReader(WritableFile, Reader), writeFromReader(WritableFile, Reader), appendFromInputStream(WritableFile, InputStream), appendFromFile(WritableFile, ReadableFile)

Permissions_required:

Write access.

appendFromReader

public static <T extends WritableFile> T appendFromReader(T f,
                                                          Reader r)
                                               throws ReadOnlyException,
                                                      AccessDeniedException,
                                                      WrappedIOException

Append character data read from the provided Reader to the file. The data is written using the platform's default Charset. The file is locked for writing during the operation.

Parameters:

f - The file to write to.

r - The Reader to read character data from.

Returns:

f

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On any read or write errors.

See Also:

appendFromReader(WritableFile, Reader, Charset), writeFromReader(WritableFile, Reader), appendFromInputStream(WritableFile, InputStream), appendFromFile(WritableFile, ReadableFile)

Permissions_required:

Write access.

appendFromChannel

public static <T extends WritableFile> T appendFromChannel(T f,
                                                           ReadableByteChannel c)
                                                throws ReadOnlyException,
                                                       AccessDeniedException,
                                                       WrappedIOException

Append binary data read from the provided ReadableByteChannel to the file. The file is locked for writing during the operation.

Parameters:

f - The file to write to.

c - The ReadableByteChannel to read binary data from. The channel is not closed by this method.

Returns:

f

Throws:

ReadOnlyException - If the file is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On any read or write errors.

Permissions_required:

Write access.

appendFromFile

public static <T extends WritableFile> T appendFromFile(T target,
                                                        ReadableFile source)
                                             throws ReadOnlyException,
                                                    AccessDeniedException,
                                                    WrappedIOException

Append data from the source file to a file. The source file is first locked for reading and then the target file is locked for writing.

Parameters:

target - The target file to append data to.

source - The source file to read from.

Returns:

target

Throws:

ReadOnlyException - If the file system is read only.

AccessDeniedException - If the calling thread does not have sufficient access rights.

WrappedIOException - On read or write errors.

See Also:

writeFromFile(WritableFile, ReadableFile), appendFromInputStream(WritableFile, InputStream), appendFromReader(WritableFile, Reader), ReadWritableFile.copy(OutputStream)

Permissions_required:

Read access to the source file. Write access to the target file.

writeFromFile

public static <T extends WritableFile> T writeFromFile(T target,
                                                       ReadableFile source)
                                            throws ReadOnlyException,
                                                   AccessDeniedException,
                                                   WrappedIOException

Write data from the source file to a file. The previous contents of the file is discarded. The source file is first locked for reading and then the target file is locked for writing.

Parameters:

target - The target file to write data to.

source - The source file to read from.

Returns:

target

Throws:

ReadOnlyException - If the file system is read only.

AccessDeniedException - If the calling thread does not have sufficient access rights.

WrappedIOException - On read or write errors.

See Also:

writeFromFile(WritableFile, ReadableFile), appendFromInputStream(WritableFile, InputStream), appendFromReader(WritableFile, Reader), ReadWritableFile.copy(OutputStream)

Permissions_required:

Read access to the source file. Write access to the target file.

appendText

public static <T extends WritableFile> T appendText(T target,
                                                    CharSequence source)
                                         throws ReadOnlyException,
                                                AccessDeniedException,
                                                WrappedIOException

Append text to a file. The target file is locked for writing while appending to it.

This method appends text using the platform's default character encoding. Use appendText(WritableFile, CharSequence, Charset) if you want another character encoding.

Parameters:

target - The target file to append text to.

source - The text to append.

Returns:

target

Throws:

ReadOnlyException - If the file system is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On read or write errors.

See Also:

appendText(WritableFile, CharSequence, Charset), writeText(WritableFile, CharSequence)

Permissions_required:

Write access.

appendText

public static <T extends WritableFile> T appendText(T target,
                                                    CharSequence source,
                                                    Charset cs)
                                         throws ReadOnlyException,
                                                AccessDeniedException,
                                                WrappedIOException

Append text to a file using a specified character encoding. The target file is locked for writing while appending to it.

Parameters:

target - The target file to append text to.

source - The text to append.

cs - The character encoding to use for the appended text.

Returns:

target

Throws:

ReadOnlyException - If the file system is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On read or write errors.

See Also:

appendText(WritableFile, CharSequence), writeText(WritableFile, CharSequence, Charset)

Permissions_required:

Write access.

writeText

public static <T extends WritableFile> T writeText(T target,
                                                   CharSequence source)
                                        throws ReadOnlyException,
                                               AccessDeniedException,
                                               WrappedIOException

Write text to a file. The previous contents of the file is discarded. The target file is locked for writing while writing to it.

This method writes text using the platform's default character encoding. Use writeText(WritableFile, CharSequence, Charset) if you want another character encoding.

Parameters:

target - The target file to write text to.

source - The text to write.

Returns:

target

Throws:

ReadOnlyException - If the file system is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On read or write errors.

See Also:

writeText(WritableFile, CharSequence, Charset), appendText(WritableFile, CharSequence)

Permissions_required:

Write access.

writeText

public static <T extends WritableFile> T writeText(T target,
                                                   CharSequence source,
                                                   Charset cs)

Write text to a file encoding it with the supplied character encoding. The previous contents of the file is discarded. The target file is locked for writing while writing to it.

Parameters:

target - The target file to write text to.

source - The text to write.

cs - The character encoding to use when writing the text.

Returns:

target

Throws:

ReadOnlyException - If the file system is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On read or write errors.

See Also:

writeText(WritableFile, CharSequence), appendText(WritableFile, CharSequence, Charset)

Permissions_required:

Write access.

writeData

public static <T extends WritableFile> T writeData(T target,
                                                   byte[] source)
                                        throws ReadOnlyException,
                                               AccessDeniedException,
                                               WrappedIOException

Write the contents of the byte array to the file. The previous contents of the file is discarded. The target file is locked for writing while it is being written to.

Parameters:

target - The file to write to.

source - The byte array to read from.

Returns:

target

Throws:

ReadOnlyException - If the file system is read only.

AccessDeniedException - If the calling thread does not have write access to the file.

WrappedIOException - On read or write errors.

See Also:

writeText(WritableFile, CharSequence), appendText(WritableFile, CharSequence, Charset)

Permissions_required:

Write access.

replaceContents

public static <T extends ReadWritableFile> T replaceContents(T f1,
                                                             ReadWritableFile f2)
                                                  throws ReadOnlyException,
                                                         AccessDeniedException,
                                                         WrappedIOException,
                                                         IllegalArgumentException

Replace the contents of file f1 with the contents of f2 and delete f2.

Note the order of the file arguments!

Parameters:

f1 - The file whose contents should be replaced.

f2 - The file containing f1's new content. This file is deleted by this method.

Returns:

f1

Throws:

ReadOnlyException - If any of the files are read only.

AccessDeniedException - If the client does not have write access to f1, f2 or their parent directories.

WrappedIOException - On I/O errors.

IllegalArgumentException - If f1 and f2 do not belong to the same file system.

See Also:

ReadWritableFile.replaceContents(ReadWritableFile)

Permissions_required:

Write access to f1, f2 and their parent directories.

copyContents

public static <T extends WritableFile> T copyContents(ReadableFile f1,
                                                      T f2)
                                           throws ReadOnlyException,
                                                  AccessDeniedException,
                                                  WrappedIOException

Copy the contents of f1 to f2, replacing f2's previous contents.

Parameters:

f1 - The file to copy from.

f2 - The file to copy to.

Returns:

f2

Throws:

ReadOnlyException - If any of the files are read only.

AccessDeniedException - If the client does not have write access to f1, f2 or their parent directories.

WrappedIOException - On I/O errors.

lineIterator

public static CloseableIterator<String> lineIterator(ReadableFile f,
                                                     Charset cs)
                                              throws AccessDeniedException,
                                                     WrappedIOException

Get an iterator over all lines in the supplied text file. 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 linefeed. (Just like BufferedReader.readLine().

Empty lines are returned as empty strings from the iterator.

Parameters:

f - The text file. The file will be locked for reading as long as the iterator is open.

cs - The charset that the text file is encoded in.

Returns:

An iterator over all lines in the text file. The iterator should be closed when it is no longer needed.

Throws:

AccessDeniedException - If the client does not have read access to f.

WrappedIOException - On I/O errors.

See Also:

lineIterator(ReadableFile)

lineIterator

public static CloseableIterator<String> lineIterator(ReadableFile f)
                                              throws AccessDeniedException,
                                                     WrappedIOException

Get an iterator over all lines in the supplied text file. The file should be encoded in the platform's default charset. 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 linefeed. (Just like BufferedReader.readLine().

Empty lines are returned as empty strings from the iterator.

Parameters:

f - The text file. The file will be locked for reading as long as the iterator is open.

Returns:

An iterator over all lines in the text file. The iterator should be closed when it is no longer needed.

Throws:

AccessDeniedException - If the client does not have read access to f.

WrappedIOException - On I/O errors.

See Also:

lineIterator(ReadableFile, Charset)