org.entityfs.util.cap.entity
Class FCFileBackedUtil

java.lang.Object
  org.entityfs.util.cap.entity.FCFileBackedUtil

public final class FCFileBackedUtil
extends Object

A utility class with static methods for working with FCFileBacked file entity capabilities.

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

Since:

1.0

Author:

Karl Gustafsson

See Also:

FCFileBacked

In_jar:

entityfs-util

Method Summary

static FCFileBacked	getCapability(EFile f) Get the FCFileBacked capability for a file entity.
static FileChannel	openFileChannelForAppend(EFile f) Open the file for appending and return a FileChannel.
static FileChannel	openFileChannelForAppend(EFile f, EntityLock writeLock) Open the file for appending and return a FileChannel.
static FileChannel	openFileChannelForRandomAccess(EFile f, RandomAccessMode mode) Open the file for random access using the random access file factory RandomAccessFileFactoryImpl and return an open FileChannel.
static FileChannel	openFileChannelForRandomAccess(EFile f, RandomAccessMode mode, EntityLock lock) Open the file for random access using the random access file factory LockAwareRandomAccessFileFactoryImpl and return an open FileChannel.
static FileChannel	openFileChannelForRead(EFile f) Open the file for reading and return a FileChannel.
static FileChannel	openFileChannelForRead(EFile f, EntityLock readLock) Open the file for reading and return a FileChannel.
static FileChannel	openFileChannelForWrite(EFile f) Open the file for writing and return a FileChannel.
static FileChannel	openFileChannelForWrite(EFile f, EntityLock writeLock) Open the file for writing and return a FileChannel.
static FileOutputStream	openFileForAppend(EFile f) Open the file for appending and return a FileOutputStream.
static FileOutputStream	openFileForAppend(EFile f, EntityLock writeLock) Open the file for appending and return a FileOutputStream.
static RandomAccessFile	openFileForRandomAccess(EFile f, RandomAccessMode mode) Open the file for random access using the random access file factory RandomAccessFileFactoryImpl.
static RandomAccessFile	openFileForRandomAccess(EFile f, RandomAccessMode mode, EntityLock lock) Open the file for random access using the random access file factory LockAwareRandomAccessFileFactoryImpl.
static FileInputStream	openFileForRead(EFile f) Open the file for reading and return a FileInputStream.
static FileInputStream	openFileForRead(EFile f, EntityLock readLock) Open the file for reading and return a FileInputStream.
static FileOutputStream	openFileForWrite(EFile f) Open the file for writing and return a FileOutputStream.
static FileOutputStream	openFileForWrite(EFile f, EntityLock writeLock) Open the file for writing and return a FileOutputStream.
static boolean	supportsCapability(EFile f) Check if the supplied file entity supports the FCFileBacked capability.

Methods inherited from class java.lang.Object

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

Method Detail

getCapability

public static FCFileBacked getCapability(EFile f)
                                  throws UnsupportedCapabilityException

Get the FCFileBacked capability for a file entity.

Parameters:

f - The file entity to get the capability for.

Returns:

The capability object.

Throws:

UnsupportedCapabilityException - If the entity does not support the FCFileBacked capability.

supportsCapability

public static boolean supportsCapability(EFile f)

Check if the supplied file entity supports the FCFileBacked capability.

Parameters:

f - The file entity to investigate.

Returns:

true if the entity supports the capability, false if not.

openFileForRandomAccess

public static RandomAccessFile openFileForRandomAccess(EFile f,
                                                       RandomAccessMode mode)
                                                throws UnsupportedCapabilityException,
                                                       ReadOnlyException,
                                                       AccessDeniedException,
                                                       ReadLockRequiredException,
                                                       WriteLockRequiredException

Open the file for random access using the random access file factory RandomAccessFileFactoryImpl. The caller is responsible for closing the file. The caller is also responsible for having a locked entity lock for the file while it is open.

Parameters:

f - The file to open.

mode - The mode for opening.

Returns:

An open RandomAccessFile.

Throws:

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

ReadLockRequiredException - If the file is opened with mode r and the client does not have a read lock for the file.

WriteLockRequiredException - If the file is opened for writing and the client does not have a write lock for the file.

AccessDeniedException - If the client does not have sufficient access rights to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A read lock for the file if it is opened for reading. A write lock if it is opened for reading and writing.

Permissions_required:

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

openFileForRandomAccess

public static RandomAccessFile openFileForRandomAccess(EFile f,
                                                       RandomAccessMode mode,
                                                       EntityLock lock)
                                                throws UnsupportedCapabilityException,
                                                       ReadOnlyException,
                                                       AccessDeniedException,
                                                       ReadLockRequiredException,
                                                       WriteLockRequiredException

Open the file for random access using the random access file factory LockAwareRandomAccessFileFactoryImpl. The caller is responsible for closing the file. When the file is closed, the supplied EntityLock is unlocked by the file.

Parameters:

f - The file to open.

mode - The mode for opening.

lock - A locked entity lock for the file. The lock will be unlocked when the file is closed. If this method fails, the lock is unlocked.

Returns:

An open RandomAccessFile.

Throws:

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

ReadLockRequiredException - If the file is opened with mode r and the client does not have a read lock for the file.

WriteLockRequiredException - If the file is opened for writing and the client does not have a write lock for the file.

AccessDeniedException - If the client does not have sufficient access rights to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A read lock for the file if it is opened for reading. A write lock if it is opened for reading and writing.

Permissions_required:

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

openFileChannelForRandomAccess

public static FileChannel openFileChannelForRandomAccess(EFile f,
                                                         RandomAccessMode mode)
                                                  throws UnsupportedCapabilityException,
                                                         ReadOnlyException,
                                                         AccessDeniedException,
                                                         ReadLockRequiredException,
                                                         WriteLockRequiredException

Open the file for random access using the random access file factory RandomAccessFileFactoryImpl and return an open FileChannel. The caller is responsible for closing the channel. The caller is also responsible for having a locked entity lock for the file while it is open.

Parameters:

f - The file to open.

mode - The mode for opening.

Returns:

An open FileChannel for random access to the file.

Throws:

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

ReadLockRequiredException - If the file is opened with mode r and the client does not have a read lock for the file.

WriteLockRequiredException - If the file is opened for writing and the client does not have a write lock for the file.

AccessDeniedException - If the client does not have sufficient access rights to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A read lock on the file if it is opened for reading, a write lock if it is opened for reading and writing.

Permissions_required:

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

openFileChannelForRandomAccess

public static FileChannel openFileChannelForRandomAccess(EFile f,
                                                         RandomAccessMode mode,
                                                         EntityLock lock)
                                                  throws UnsupportedCapabilityException,
                                                         ReadOnlyException,
                                                         AccessDeniedException,
                                                         ReadLockRequiredException,
                                                         WriteLockRequiredException

Open the file for random access using the random access file factory LockAwareRandomAccessFileFactoryImpl and return an open FileChannel. The caller is responsible for closing the channel. When the file is closed, the supplied EntityLock is unlocked by the file.

Parameters:

f - The file to open.

mode - The mode for opening.

lock - A locked entity lock for the file. The lock will be unlocked when the file is closed. If this method fails, the lock is unlocked.

Returns:

An open FileChannel for random access to the file.

Throws:

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

ReadLockRequiredException - If the file is opened with mode r and the client does not have a read lock for the file.

WriteLockRequiredException - If the file is opened for writing and the client does not have a write lock for the file.

AccessDeniedException - If the client does not have sufficient access rights to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A read lock on the file if it is opened for reading, a write lock if it is opened for reading and writing.

Permissions_required:

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

openFileForWrite

public static FileOutputStream openFileForWrite(EFile f)
                                         throws UnsupportedCapabilityException,
                                                ReadOnlyException,
                                                AccessDeniedException,
                                                WriteLockRequiredException

Open the file for writing and return a FileOutputStream. The previous contents of the file will be discarded.

The caller is responsible for closing the stream. The caller is also responsible for having a locked write lock on the opened file entity while it is open.

Parameters:

f - The file to open for writing.

Returns:

An open FileOutputStream.

Throws:

ReadOnlyException - If the file is read only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A write lock on the file.

Permissions_required:

Write access.

openFileForWrite

public static FileOutputStream openFileForWrite(EFile f,
                                                EntityLock writeLock)
                                         throws UnsupportedCapabilityException,
                                                ReadOnlyException,
                                                WriteLockRequiredException,
                                                AccessDeniedException

Open the file for writing and return a FileOutputStream. The previous contents of the file will be discarded.

The caller is responsible for closing the stream. When the stream is closed, the supplied EntityLock is unlocked by the stream.

Parameters:

f - The file to open for writing.

writeLock - A locked write lock for the file entity. The lock will be unlocked when the stream is closed. If this method fails, the lock is unlocked.

Returns:

An open FileOutputStream.

Throws:

ReadOnlyException - If the file is read only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A write lock on the file. The locked lock is supplied in the writeLock argument.

Permissions_required:

Write access.

openFileChannelForWrite

public static FileChannel openFileChannelForWrite(EFile f)
                                           throws UnsupportedCapabilityException,
                                                  ReadOnlyException,
                                                  AccessDeniedException,
                                                  WriteLockRequiredException

Open the file for writing and return a FileChannel. The previous contents of the file will be discarded.

The caller is responsible for closing the channel. The caller is also responsible for having a locked write lock on the opened file entity while it is open.

Parameters:

f - The file to open for writing.

Returns:

An open FileChannel.

Throws:

ReadOnlyException - If the file is read only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A write lock on the file.

Permissions_required:

Write access.

openFileChannelForWrite

public static FileChannel openFileChannelForWrite(EFile f,
                                                  EntityLock writeLock)
                                           throws UnsupportedCapabilityException,
                                                  ReadOnlyException,
                                                  WriteLockRequiredException,
                                                  AccessDeniedException

Open the file for writing and return a FileChannel. The previous contents of the file will be discarded.

The caller is responsible for closing the channel. When it is closed, the supplied EntityLock is unlocked by the stream.

Parameters:

f - The file to open for writing.

writeLock - A locked write lock for the file entity. The lock will be unlocked when the stream is closed. If this method fails, the lock is unlocked.

Returns:

An open FileOutputStream.

Throws:

ReadOnlyException - If the file is read only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A write lock on the file. The locked lock is supplied to the method as the writeLock argument.

Permissions_required:

Write access.

openFileForAppend

public static FileOutputStream openFileForAppend(EFile f)
                                          throws UnsupportedCapabilityException,
                                                 ReadOnlyException,
                                                 WriteLockRequiredException,
                                                 AccessDeniedException

Open the file for appending and return a FileOutputStream. Data written to the returned stream will be added at the end of the file.

The caller is responsible for closing the stream. The caller is also responsible for having a locked write lock on the opened file entity while it is open.

Parameters:

f - The file to open for appending.

Returns:

An open FileOutputStream.

Throws:

ReadOnlyException - If the file is read only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A write lock on the file.

Permissions_required:

Write access.

openFileForAppend

public static FileOutputStream openFileForAppend(EFile f,
                                                 EntityLock writeLock)
                                          throws UnsupportedCapabilityException,
                                                 ReadOnlyException,
                                                 WriteLockRequiredException,
                                                 AccessDeniedException

Open the file for appending and return a FileOutputStream. Data written to the returned stream will be added at the end of the file.

The caller is responsible for closing the stream. When the stream is closed, the supplied EntityLock is unlocked by the stream.

Parameters:

f - The file to open for appending.

writeLock - A locked write lock for the file entity. The lock will be unlocked when the stream is closed. If this method fails, the lock is unlocked.

Returns:

An open FileOutputStream.

Throws:

ReadOnlyException - If the file is read only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A write lock on the file. The locked lock is supplied to the method in the writeLock argument.

Permissions_required:

Write access.

openFileChannelForAppend

public static FileChannel openFileChannelForAppend(EFile f)
                                            throws UnsupportedCapabilityException,
                                                   ReadOnlyException,
                                                   WriteLockRequiredException,
                                                   AccessDeniedException

Open the file for appending and return a FileChannel. Data written to the returned channel will be added at the end of the file.

The caller is responsible for closing the channel. The caller is also responsible for having a locked write lock on the opened file entity while it is open.

Parameters:

f - The file to open for appending.

Returns:

An open FileChannel.

Throws:

ReadOnlyException - If the file is read only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A write lock on the file.

Permissions_required:

Write access.

openFileChannelForAppend

public static FileChannel openFileChannelForAppend(EFile f,
                                                   EntityLock writeLock)
                                            throws UnsupportedCapabilityException,
                                                   ReadOnlyException,
                                                   WriteLockRequiredException,
                                                   AccessDeniedException

Open the file for appending and return a FileChannel. Data written to the returned channel will be added at the end of the file.

The caller is responsible for closing the channel. When the stream is closed, the supplied EntityLock is unlocked by the stream.

Parameters:

f - The file to open for appending.

writeLock - A locked write lock for the file entity. The lock will be unlocked when the stream is closed. If this method fails, the lock is unlocked.

Returns:

An open FileChannel.

Throws:

ReadOnlyException - If the file is read only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the entity.

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A write lock on the file. The locked lock is supplied to the method in the writeLock argument.

Permissions_required:

Write access.

openFileForRead

public static FileInputStream openFileForRead(EFile f)
                                       throws UnsupportedCapabilityException,
                                              ReadLockRequiredException,
                                              AccessDeniedException

Open the file for reading and return a FileInputStream.

The caller is responsible for closing the stream. The caller is also responsible for having a locked read lock on the opened file entity while it is open.

Parameters:

f - The file to open for reading.

Returns:

An open FileInputStream.

Throws:

ReadLockRequiredException - If the client does not have a read lock for the file.

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

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A read lock on the file.

Permissions_required:

Read access.

openFileForRead

public static FileInputStream openFileForRead(EFile f,
                                              EntityLock readLock)
                                       throws UnsupportedCapabilityException,
                                              ReadLockRequiredException,
                                              AccessDeniedException

Open the file for reading and return a FileInputStream.

The caller is responsible for closing the stream. When the stream is closed, the supplied EntityLock is unlocked by the stream.

Parameters:

f - The file to open for reading.

readLock - A locked read lock for the file entity. The lock will be unlocked when the stream is closed. If this method fails, the lock is unlocked.

Returns:

An open FileInputStream.

Throws:

ReadLockRequiredException - If the client does not have a read lock for the file.

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

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A read lock on the file. The locked lock is supplied to the method in the readLock argument.

Permissions_required:

Read access.

openFileChannelForRead

public static FileChannel openFileChannelForRead(EFile f)
                                          throws UnsupportedCapabilityException,
                                                 ReadLockRequiredException,
                                                 AccessDeniedException

Open the file for reading and return a FileChannel.

The caller is responsible for closing the channel. The caller is also responsible for having a locked read lock on the opened file entity while it is open.

Parameters:

f - The file to open for reading.

Returns:

An open FileChannel.

Throws:

ReadLockRequiredException - If the client does not have a read lock for the file.

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

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A read lock on the file.

Permissions_required:

Read access.

openFileChannelForRead

public static FileChannel openFileChannelForRead(EFile f,
                                                 EntityLock readLock)
                                          throws UnsupportedCapabilityException,
                                                 ReadLockRequiredException,
                                                 AccessDeniedException

Open the file for reading and return a FileChannel.

The caller is responsible for closing the channel. When it is closed, the supplied EntityLock is also unlocked.

Parameters:

f - The file to open for reading.

readLock - A locked read lock for the file entity. The lock will be unlocked when the stream is closed. If this method fails, the lock is unlocked.

Returns:

An open FileChannel.

Throws:

ReadLockRequiredException - If the client does not have a read lock for the file.

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

UnsupportedCapabilityException - If the file entity does not support the FCFileBacked capability.

Locks_required:

A read lock on the file. The locked lock is supplied to the method in the readLock argument.

Permissions_required:

Read access.