org.at4j.comp.bzip2
Class BZip2WritableFile

java.lang.Object
  extended by org.at4j.comp.bzip2.BZip2WritableFile
All Implemented Interfaces:
Lockable, WriteLockable, WritableFile

public class BZip2WritableFile
extends Object
implements WritableFile

This is a WritableFile that transparently compresses the data written to a file using bzip2 compression.

The bzip2 output stream is opened on a buffered output stream on the backing file. The size of that buffer can be configured.

This file cannot be appended to. The openForAppend methods throw an UnsupportedOperationException.

Since:
1.0
Author:
Karl Gustafsson
See Also:
BZip2ReadableFile, GZipWritableFile, LzmaWritableFile, BZip2OutputStream

Constructor Summary
BZip2WritableFile(WritableFile adapted)
          Create a new adapter using the default bzip2 block size (900kb).
BZip2WritableFile(WritableFile adapted, BZip2WritableFileSettings settings)
          Create a new adapter using the supplied bzip2 buffer size.
BZip2WritableFile(WritableFile adapted, CompressionLevel level)
          Create a new adapter using the supplied compression level.
BZip2WritableFile(WritableFile adapted, CompressionLevel level, boolean writeMagicBytes)
          Deprecated. The magic bytes are always written starting from At4J 1.1.
BZip2WritableFile(WritableFile adapted, int blockSize, boolean writeMagicBytes, int bufferSize)
          Deprecated. The magic bytes are always written starting from At4J 1.1.
 
Method Summary
 EntityLock getWriteLock()
          Get the write lock without locking it.
 boolean isWriteLockedByCurrentThread()
          Does the calling thread hold a write lock for the lockable object (this)?
 EntityLock lockForWriting()
          Lock the object for writing and return the lock.
 WritableByteChannel openChannelForAppend()
          This method always throws an UnsupportedOperationException.
 WritableByteChannel openChannelForWrite()
          Open a WritableByteChannel for writing on the file.
 OutputStream openForAppend()
          This method always throws an UnsupportedOperationException.
 OutputStream openForWrite()
          Opens the file for writing.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BZip2WritableFile

public BZip2WritableFile(WritableFile adapted)
Create a new adapter using the default bzip2 block size (900kb).

Note: Starting with At4J 1.1, the written bzip2 data will be prefixed with the bzip2 stream header "BZ".

Parameters:
adapted - The writable file to adapt.

BZip2WritableFile

public BZip2WritableFile(WritableFile adapted,
                         CompressionLevel level)
Create a new adapter using the supplied compression level.

Note: Starting with At4J 1.1, the written bzip2 data will be prefixed with the bzip2 stream header "BZ".

Parameters:
adapted - The writable file to adapt.
level - The compression level.
Since:
1.0.2

BZip2WritableFile

@Deprecated
public BZip2WritableFile(WritableFile adapted,
                                    CompressionLevel level,
                                    boolean writeMagicBytes)
Deprecated. The magic bytes are always written starting from At4J 1.1.

Create a new adapter using the supplied compression level.

Parameters:
adapted - The writable file to adapt.
level - The compression level.
writeMagicBytes - Should the written data be prefixed by the two magic bytes, "BZ"? Starting with At4J 1.1, this property must be true.
Since:
1.0.2

BZip2WritableFile

@Deprecated
public BZip2WritableFile(WritableFile adapted,
                                    int blockSize,
                                    boolean writeMagicBytes,
                                    int bufferSize)
                  throws IllegalArgumentException
Deprecated. The magic bytes are always written starting from At4J 1.1.

Create a new adapter using the supplied bzip2 buffer size.

Parameters:
adapted - The writable file to adapt.
blockSize - The size of bzip2 dictionary in 100k units. This must be a value between 1 and 9 (inclusive). A higher value gives a higher compression, but it will also make the compression and future decompressions use more memory.
writeMagicBytes - Should the written data be prefixed by the two magic bytes, "BZ"? Starting with At4J 1.1, this property must be true.
bufferSize - The size of the memory buffer used for buffering the written output before it is compressed.
Throws:
IllegalArgumentException - If the block size is less than 1 or greater than 10, or if the buffer size is less than 1.

BZip2WritableFile

public BZip2WritableFile(WritableFile adapted,
                         BZip2WritableFileSettings settings)
                  throws IllegalArgumentException
Create a new adapter using the supplied bzip2 buffer size.

Parameters:
adapted - The writable file to adapt.
settings - Settings. A clone of the settings object is stored in the created object.
Throws:
IllegalArgumentException - If the block size is less than 1 or greater than 10, or if the buffer size is less than 1.
Since:
1.1
Method Detail

openChannelForAppend

public WritableByteChannel openChannelForAppend()
                                         throws UnsupportedOperationException
This method always throws an UnsupportedOperationException.

Specified by:
openChannelForAppend in interface WritableFile
Returns:
An open WritableByteChannel. The channel must be closed by the caller. The returned channel may be a GatheringByteChannel, but that is not required.
Throws:
UnsupportedOperationException - Always.

openChannelForWrite

public WritableByteChannel openChannelForWrite()
                                        throws WriteLockRequiredException,
                                               AccessDeniedException,
                                               ReadOnlyException
Description copied from interface: WritableFile
Open a WritableByteChannel for writing on the file. The semantics of this method is the same as for WritableFile.openForWrite().

Specified by:
openChannelForWrite in interface WritableFile
Returns:
An open WritableByteChannel. The channel must be closed by the caller. The returned channel may be a GatheringByteChannel, but that is not required.
Throws:
WriteLockRequiredException - If the client does not have a write lock for the file.
AccessDeniedException - If the client does not have write access to the file.
ReadOnlyException - If the file system is read-only.
See Also:
WritableFile.openForWrite(), WritableFile.openChannelForAppend()

openForAppend

public OutputStream openForAppend()
                           throws UnsupportedOperationException
This method always throws an UnsupportedOperationException.

Specified by:
openForAppend in interface WritableFile
Returns:
An OutputStream to write to. The stream must be closed by the caller.
Throws:
UnsupportedOperationException - Always.
See Also:
WritableFile.openForWrite(), WritableFile.openChannelForAppend()

openForWrite

public OutputStream openForWrite()
                          throws WriteLockRequiredException,
                                 AccessDeniedException,
                                 ReadOnlyException
Description copied from interface: WritableFile
Opens the file for writing. This deletes all previous contents of the file. Use WritableFile.openForAppend() to append to the file.

The caller is responsible for closing the stream.

When two output streams, one writing and one appending are open on the same file, the stream opened for write will ignore the contents written by the other stream and the content written by the other stream will be overwritten. When two or more appending streams are opened on a file, a stream will not overwrite the content written by the other streams.

Although a write 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 LockAwareOutputStream.

Specified by:
openForWrite in interface WritableFile
Returns:
An OutputStream to write to. The stream must be closed by the caller.
Throws:
WriteLockRequiredException - If the client does not have a write lock for the file.
AccessDeniedException - If the client does not have write access to the file.
ReadOnlyException - If the file system is read-only.
See Also:
WritableFile.openForAppend(), WritableFile.openChannelForWrite()

getWriteLock

public EntityLock getWriteLock()
Description copied from interface: WriteLockable
Get the write 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:
getWriteLock in interface WriteLockable
Returns:
The lockable's write lock. This might be unlocked or locked by someone else.

isWriteLockedByCurrentThread

public boolean isWriteLockedByCurrentThread()
Description copied from interface: WriteLockable
Does the calling thread hold a write lock for the lockable object (this)?

Specified by:
isWriteLockedByCurrentThread in interface WriteLockable
Returns:
true if the lockable object is write locked by the current thread.

lockForWriting

public EntityLock lockForWriting()
                          throws LockTimeoutException
Description copied from interface: WriteLockable
Lock the object for writing 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 is somehow connected to an Entity object, that entity's file systems' lock adapter factory and lock acquiring strategy is used. A write lock can be downgraded to a read lock (by calling ReadLockable.lockForReading() and then releasing the write lock).

An entity in a locking read only file system may still be locked for writing.

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

This method always returns a lock, even if the file system is not locking.

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