org.at4j.comp.bzip2
Class BZip2ReadableFile

java.lang.Object
  extended by org.at4j.comp.bzip2.BZip2ReadableFile
All Implemented Interfaces:
Lockable, ReadLockable, ReadableFile

public class BZip2ReadableFile
extends Object
implements ReadableFile

This is a ReadableFile that transparently decompresses the contents of a wrapped file using bzip2.

bzip2 input streams are opened on buffered input streams on the underlying file. The buffer size can be configured.

A ReadableFile can be made into a NamedReadableFile using the NamedReadableFileAdapter.

Since:
1.0
Author:
Karl Gustafsson
See Also:
BZip2WritableFile, LzmaReadableFile, GZipReadableFile, BZip2InputStream

Constructor Summary
BZip2ReadableFile(ReadableFile adapted)
          Create a new adapter.
BZip2ReadableFile(ReadableFile adapted, boolean assumeMagicBytes)
          Deprecated. The assumeMagicBytes property is always true from At4J 1.1.
BZip2ReadableFile(ReadableFile adapted, boolean assumeMagicBytes, int bufferSize)
          Deprecated. The assumeMagicBytes property is always true from At4J 1.1.
BZip2ReadableFile(ReadableFile adapted, BZip2ReadableFileSettings settings)
          Create a new adapter.
 
Method Summary
 long getDataSize()
          Get the size of the data in the file.
 EntityLock getReadLock()
          Get the read lock without locking it.
 long getSize()
          Get the size of the file (in bytes).
 boolean isReadLockedByCurrentThread()
          Does the calling thread hold a read lock for this object? A write lock also qualifies as a read lock.
 EntityLock lockForReading()
          Lock object for reading and return the lock.
 ReadableByteChannel openChannelForRead()
          Open a ReadableByteChannel for reading from the file.
 InputStream openForRead()
          Opens the file for reading.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BZip2ReadableFile

public BZip2ReadableFile(ReadableFile adapted)
Create a new adapter. The adapter will assume that the bzip2 compressed data does not start with the two magic bytes "BZ".

Parameters:
adapted - The adapted file.
See Also:
BZip2ReadableFile(ReadableFile, BZip2ReadableFileSettings)

BZip2ReadableFile

@Deprecated
public BZip2ReadableFile(ReadableFile adapted,
                                    boolean assumeMagicBytes)
Deprecated. The assumeMagicBytes property is always true from At4J 1.1.

Create a new adapter. The adapter will use the default buffer size of 8192 bytes.

Parameters:
adapted - The adapted file.
assumeMagicBytes - Does the compressed data in the file start with the two magic bytes "BZ"? Starting with At4J 1.1, this property must be true.

BZip2ReadableFile

@Deprecated
public BZip2ReadableFile(ReadableFile adapted,
                                    boolean assumeMagicBytes,
                                    int bufferSize)
Deprecated. The assumeMagicBytes property is always true from At4J 1.1.

Create a new adapter.

Parameters:
adapted - The adapted file.
assumeMagicBytes - Does the compressed data in the file start with the two magic bytes "BZ"? Starting with At4J 1.1, this property must be true.
bufferSize - The size of the buffer for the buffered input stream that the bzip2 input stream is opened on. Set this to -1 to use the default buffer size (8192 bytes).

BZip2ReadableFile

public BZip2ReadableFile(ReadableFile adapted,
                         BZip2ReadableFileSettings settings)
Create a new adapter.

Parameters:
adapted - The adapted file.
settings - The settings for this readable file. A clone of the settings object is stored in the created object.
Since:
1.1
See Also:
BZip2ReadableFile(ReadableFile)
Method Detail

openChannelForRead

public ReadableByteChannel openChannelForRead()
                                       throws ReadLockRequiredException,
                                              AccessDeniedException
Description copied from interface: ReadableFile
Open a ReadableByteChannel for reading from the file. The semantics of this method is the same as for ReadableFile.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.

Specified by:
openChannelForRead in interface ReadableFile
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:
ReadableFile.openForRead()

openForRead

public InputStream openForRead()
                        throws ReadLockRequiredException,
                               AccessDeniedException
Description copied from interface: ReadableFile
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.

Specified by:
openForRead in interface ReadableFile
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.

getReadLock

public EntityLock getReadLock()
Description copied from interface: ReadLockable
Get the read lock without locking it.

This method always returns a lock, even if the object's file system is not locking or if the object is read only.

Specified by:
getReadLock in interface ReadLockable
Returns:
The lockable's read lock. This might be unlocked or locked by someone else.

isReadLockedByCurrentThread

public boolean isReadLockedByCurrentThread()
                                    throws IllegalStateException
Description copied from interface: ReadLockable
Does the calling thread hold a read lock for this object? A write lock also qualifies as a read lock.

Specified by:
isReadLockedByCurrentThread in interface ReadLockable
Returns:
true if the lockable object is read or write locked by the current thread.
Throws:
IllegalStateException - If this is called on a disconnected entity view.

lockForReading

public EntityLock lockForReading()
                          throws LockTimeoutException
Description copied from interface: ReadLockable
Lock object for reading and return the lock. How the lock is acquired is determined by the EntityLockAdapterFactory and LockAcquiringStrategy used. If this is called on an object that somehow is connected to an entity object, that entity's file system's entity lock adapter factory and lock acquiring strategy is used.

A read lock cannot be upgraded to a write lock (just like how Java's ReadWriteLock works).

For more discussions on locks and locking, see Entity and FileSystem.

This method always returns a lock, even if the object's file system is not locking or if the object is read only.

Specified by:
lockForReading in interface ReadLockable
Returns:
A locked read lock.
Throws:
LockTimeoutException - If the lock acquiring timed out. (It is up to the LockAcquiringStrategy to decide if lock acquiring can time out.)

getDataSize

public long getDataSize()
                 throws ReadLockRequiredException,
                        AccessDeniedException
Description copied from interface: ReadableFile
Get the size of the data in the file. For compressed files, this is larger than the value returned by ReadableFile.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.

Specified by:
getDataSize in interface ReadableFile
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.
See Also:
ReadableFile.getSize()

getSize

public long getSize()
             throws ReadLockRequiredException,
                    AccessDeniedException
Description copied from interface: ReadableFile
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.

Specified by:
getSize in interface ReadableFile
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.
See Also:
ReadableFile.getDataSize()