org.entityfs
Interface ReadableFile

All Superinterfaces:

Lockable, ReadLockable

All Known Subinterfaces:

ECMetadata, EFile, EFileImplementation, NamedReadableFile, ReadWritableFile

All Known Implementing Classes:

AbstractReadableFile, AbstractReadWritableFile, ByteArrayReadableFile, CharSequenceReadableFile, ClasspathNamedReadableFile, ECMetadataImpl, FileDelegateReadWritableFileAdapter, FileImpl, FileReadableFile, GZipReadableFile, ManualNamedReadableFile, MetadataFileAdapter, NamedReadableFileAdapter, ReadWritableFileAdapter, UrlReadableFile

public interface ReadableFile
extends ReadLockable

This interface is implemented by objects that behave as readable files, EFile:s for instance.

Use this interface instead of EFile wherever possible to make mocking and testing easier.

Since:

1.0

Author:

Karl Gustafsson

See Also:

WritableFile, RandomlyAccessibleFile

In_jar:

entityfs-core

Method Summary

long	getDataSize() Get the size of the data in the file.
long	getSize() Get the size of the file (in bytes).
ReadableByteChannel	openChannelForRead() Open a ReadableByteChannel for reading from the file.
InputStream	openForRead() Opens the file for reading.

Methods inherited from interface org.entityfs.lock.ReadLockable

getReadLock, isReadLockedByCurrentThread, lockForReading

Method Detail

openForRead

InputStream openForRead()
                        throws ReadLockRequiredException,
                               AccessDeniedException

Opens the file for reading. The caller is responsible for closing the returned stream.

Although a read lock on the file is required for the execution thread opening the stream, the stream itself is not protected from access by other threads. It can be protected by wrapping it in a LockAwareInputStream.

Returns:

An InputStream on the file. The stream must be closed by the caller.

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 file.

Locks_required:

A read lock on the file.

Permissions_required:

Read access.

openChannelForRead

ReadableByteChannel openChannelForRead()
                                       throws ReadLockRequiredException,
                                              AccessDeniedException

Open a ReadableByteChannel for reading from the file. The semantics of this method is the same as for openForRead().

Although a read lock on the file is required for the execution thread opening the channel, the channel itself is not protected from access by other threads. It can be protected by wrapping it in a LockAwareReadableByteChannel.

Returns:

An open ReadableByteChannel. The channel must be closed by the caller. The channel may be a ScatteringByteChannel, but that is not required.

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 file.

See Also:

openForRead()

Locks_required:

A read lock on the file.

Permissions_required:

Read access.

getSize

long getSize()
             throws ReadLockRequiredException,
                    AccessDeniedException

Get the size of the file (in bytes). This is the number of bytes that the file occupies where it is stored.

Note: Most, but not all, implementations know their sizes. If an implementation does not know its size beforehand, this method will be slow since it has to calculate the file size when it is called.

Implementation note: If the size of the backing file is not known, the StreamUtil.getSizeOfDataInStream(InputStream, int) method can be used to calculate it.

Returns:

The size of the file, in bytes.

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 file.

Since:

1.1

See Also:

getDataSize()

Locks_required:

A read lock on the file or on its parent directory.

Permissions_required:

Read access.

getDataSize

long getDataSize()
                 throws ReadLockRequiredException,
                        AccessDeniedException

Get the size of the data in the file. For compressed files, this is larger than the value returned by getSize().

Warning: Calculating the data size of a file has the potential of being really slow, depending on the implementation used. The entire file may have to be read through in order to calculate the size of its data.

Implementation note: If the size of the backing file is not known, the StreamUtil.getSizeOfDataInStream(InputStream, int) method can be used to calculate it.

Returns:

The size of data in the file.

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 file.

Since:

1.1

See Also:

getSize()

Locks_required:

A read lock on the file.

Permissions_required:

Read access.