org.processmining.framework.log.rfb.io
Class ManagedRandomAccessFile

java.lang.Object
  extended by org.processmining.framework.log.rfb.io.ManagedRandomAccessFile
All Implemented Interfaces:
java.io.DataInput, java.io.DataOutput, RandomAccessStorage
Direct Known Subclasses:
CachedRandomAccessFile

public class ManagedRandomAccessFile
extends java.lang.Object
implements RandomAccessStorage

This class represents the typical interface of a random access file, i.e. the DataInput and DataOutput interfaces plus navigation and closing functionality.

Within all instances of this class, a given limit of open files is ensured. The lightweight wrapper instances automatically care for restoring the underlying instance's state when it had been closed intermediately.

Notice that the wrapper's seek() method has been implemented in a lazy fashion, i.e. it will only access I/O when necessary.

Author:
Christian W. Guenther (christian at deckfour dot org)

Nested Class Summary
protected static class ManagedRandomAccessFile.ShutdownHook
          This class implements a shutdown hook, which will clear all files backing instances of the enclosing class from the file system at the moment, at which the JVM shuts down.
 
Field Summary
protected  long currentFilePointer
           
protected  java.io.File file
           
protected  boolean isOpen
           
protected static int maxOpenFiles
          Defines the maximal number of open random access files concurrently held by instances of this class
protected static int openFilesCounter
          Counts the global number of open random access files held by instances of this class
protected static java.util.ArrayList<ManagedRandomAccessFile> openFilesList
          Holds references of instances of this class, which currently hold an open random access file
protected  java.io.RandomAccessFile raf
           
protected static java.lang.String TEMP_FILE_PREFIX
          Prefix for temporary buffer files.
protected static java.lang.String TEMP_FILE_SUFFIX
          Suffix for temporary buffer files.
 
Constructor Summary
ManagedRandomAccessFile()
          Creates a new managed instance, which is based on the given file.
ManagedRandomAccessFile(ManagedRandomAccessFile template)
          Creates a new managed instance, which is based on the given file.
 
Method Summary
 void close()
          Closes this instance virtually (flushes and releases the managed file)
protected  void closeHandle()
          Called by the static open file management facility, when the underlying file has to be closed due to open file limit restrictions.
 RandomAccessStorage copy()
          Creates a clone, or copy, of this storage, having the exact same contents and the file pointer reset to zero.
static void copyFile(java.io.File source, java.io.File destination)
          Copies the contents of the source file verbatim to the provided destination file.
protected static java.io.File createTempFile()
          Creates a new temporary file with the configured pre- and suffix in the system-wide temporary file directory.
 boolean delete()
          Deletes the underlying file from the file system.
 void deleteOnExit()
          Deletes the underlying file from the file system when the virtual machine is shut down.
protected  void finalize()
          Cleans the actual file which has been wrapped from disk.
 long getFilePointer()
          Retrieves the current offset within the managed file, from which the next read or write occurs.
 long length()
          Retrieves the current size of the managed file
protected  java.io.RandomAccessFile raf()
          Provides wrapped access to the managed random access file.
 boolean readBoolean()
          Wrapped method from DataInput interface.
 byte readByte()
          Wrapped method from DataInput interface.
 char readChar()
          Wrapped method from DataInput interface.
 double readDouble()
          Wrapped method from DataInput interface.
 float readFloat()
          Wrapped method from DataInput interface.
 void readFully(byte[] arg0)
          Wrapped method from DataInput interface.
 void readFully(byte[] arg0, int arg1, int arg2)
          Wrapped method from DataInput interface.
 int readInt()
          Wrapped method from DataInput interface.
 java.lang.String readLine()
          Wrapped method from DataInput interface.
 long readLong()
          Wrapped method from DataInput interface.
 short readShort()
          Wrapped method from DataInput interface.
 int readUnsignedByte()
          Wrapped method from DataInput interface.
 int readUnsignedShort()
          Wrapped method from DataInput interface.
 java.lang.String readUTF()
          Warning: custom implementation will expect different low-level byte encoding than e.g.
protected static void releaseOpenFileSlot(ManagedRandomAccessFile customer)
          Called by instances of this class to signal release of a currently held open file handle (when closing the instance).
protected  void reOpen()
          Re-opens the managed random access file, implies retrieving an open file slot from the static management facilities.
protected static void retrieveOpenFileSlot(ManagedRandomAccessFile customer)
          Acquires an open file slot for the calling instance and registers it accordingly.
 void seek(long position)
          Sets the file pointer offset to the given position.
 int skipBytes(int arg0)
          Wrapped method from DataInput interface.
 void write(byte[] arg)
          Wrapped method from DataOutput interface.
 void write(byte[] arg, int arg1, int arg2)
          Wrapped method from DataOutput interface.
 void write(int val)
          Wrapped method from DataOutput interface.
 void writeBoolean(boolean bool)
          Wrapped method from DataOutput interface.
 void writeByte(int arg0)
          Wrapped method from DataOutput interface.
 void writeBytes(java.lang.String arg0)
          Wrapped method from DataOutput interface.
 void writeChar(int arg0)
          Wrapped method from DataOutput interface.
 void writeChars(java.lang.String arg0)
          Wrapped method from DataOutput interface.
 void writeDouble(double arg0)
          Wrapped method from DataOutput interface.
 void writeFloat(float arg0)
          Wrapped method from DataOutput interface.
 void writeInt(int arg0)
          Wrapped method from DataOutput interface.
 void writeLong(long arg0)
          Wrapped method from DataOutput interface.
 void writeShort(int arg0)
          Wrapped method from DataOutput interface.
 void writeUTF(java.lang.String arg0)
          Warning: This method uses a custom format to encode UTF-8 strings to bytes than specified in DataOutput.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TEMP_FILE_PREFIX

protected static final java.lang.String TEMP_FILE_PREFIX
Prefix for temporary buffer files.

See Also:
Constant Field Values

TEMP_FILE_SUFFIX

protected static final java.lang.String TEMP_FILE_SUFFIX
Suffix for temporary buffer files.

See Also:
Constant Field Values

openFilesCounter

protected static int openFilesCounter
Counts the global number of open random access files held by instances of this class


openFilesList

protected static java.util.ArrayList<ManagedRandomAccessFile> openFilesList
Holds references of instances of this class, which currently hold an open random access file


maxOpenFiles

protected static int maxOpenFiles
Defines the maximal number of open random access files concurrently held by instances of this class


file

protected java.io.File file

raf

protected java.io.RandomAccessFile raf

currentFilePointer

protected long currentFilePointer

isOpen

protected boolean isOpen
Constructor Detail

ManagedRandomAccessFile

public ManagedRandomAccessFile()
                        throws java.io.IOException
Creates a new managed instance, which is based on the given file.

Parameters:
aFile - The file which to access in a random fashion.
Throws:
java.io.IOException

ManagedRandomAccessFile

public ManagedRandomAccessFile(ManagedRandomAccessFile template)
                        throws java.io.IOException
Creates a new managed instance, which is based on the given file. The created instance will be an exact copy, or clone, of the given template instance. Modifications are not synchronized between template and clone, i.e. they behave as truly separate instances that are only exactly the same after construction.

Parameters:
template - The template to create a clone from.
aFile - File which is to be backing the clone to be created.
Throws:
java.io.IOException
Method Detail

retrieveOpenFileSlot

protected static void retrieveOpenFileSlot(ManagedRandomAccessFile customer)
                                    throws java.io.IOException
Acquires an open file slot for the calling instance and registers it accordingly. Transparently closes the last opened file of another instance, if limit is to be exceeded.

Parameters:
customer - Calling instance requiring an open file slot(this reference)
Throws:
java.io.IOException

releaseOpenFileSlot

protected static void releaseOpenFileSlot(ManagedRandomAccessFile customer)
                                   throws java.io.IOException
Called by instances of this class to signal release of a currently held open file handle (when closing the instance).

Parameters:
customer - Calling instance freeing an open file slot(this reference)
Throws:
java.io.IOException

delete

public boolean delete()
               throws java.io.IOException
Deletes the underlying file from the file system.

Warning: The usage contract is, that after calling this method no reading or modifying method may be called. Otherwise, unexpected results may be produced.

Returns:
Whether deleting the underlying file was successful
Throws:
java.io.IOException

deleteOnExit

public void deleteOnExit()
                  throws java.io.IOException
Deletes the underlying file from the file system when the virtual machine is shut down.

Warning: The usage contract is, that after calling this method no reading or modifying method may be called. Otherwise, unexpected results may be produced.

Throws:
java.io.IOException

close

public void close()
           throws java.io.IOException
Closes this instance virtually (flushes and releases the managed file)

Specified by:
close in interface RandomAccessStorage
Throws:
java.io.IOException

getFilePointer

public long getFilePointer()
Retrieves the current offset within the managed file, from which the next read or write occurs.

Specified by:
getFilePointer in interface RandomAccessStorage
Returns:
current offset within the managed file

length

public long length()
            throws java.io.IOException
Retrieves the current size of the managed file

Specified by:
length in interface RandomAccessStorage
Returns:
current underlying file size in bytes
Throws:
java.io.IOException

seek

public void seek(long position)
Sets the file pointer offset to the given position.

Notice that this method behaves different from the identical method in RandomAccessFile, in that it does not necessarily trigger a low-level I/O call, as this class implements lazy seeking (seeking is only performed at the point in time, at which it becomes necessary for access).

Specified by:
seek in interface RandomAccessStorage
Parameters:
position - The offset in bytes from the beginning of the managed file, at which to read or write the next data.

closeHandle

protected void closeHandle()
                    throws java.io.IOException
Called by the static open file management facility, when the underlying file has to be closed due to open file limit restrictions.

Usage contract: This method must only be called on instances which are guaranteed to hold an open file reference at the point of calling!

Throws:
java.io.IOException

reOpen

protected void reOpen()
               throws java.io.IOException
Re-opens the managed random access file, implies retrieving an open file slot from the static management facilities.

Throws:
java.io.IOException

raf

protected java.io.RandomAccessFile raf()
                                throws java.io.IOException
Provides wrapped access to the managed random access file. Use only this method, and not the attribute reference directly. Calling this method will transparently ensure, that the returned random access file references an open instance which is intelligently reset to the previous file pointer position if necessary (lazy seeking)

Returns:
the managed random access file handle for internal use
Throws:
java.io.IOException

write

public void write(int val)
           throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
write in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

write

public void write(byte[] arg)
           throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
write in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

write

public void write(byte[] arg,
                  int arg1,
                  int arg2)
           throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
write in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeBoolean

public void writeBoolean(boolean bool)
                  throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeBoolean in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeByte

public void writeByte(int arg0)
               throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeByte in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeShort

public void writeShort(int arg0)
                throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeShort in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeChar

public void writeChar(int arg0)
               throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeChar in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeInt

public void writeInt(int arg0)
              throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeInt in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeLong

public void writeLong(long arg0)
               throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeLong in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeFloat

public void writeFloat(float arg0)
                throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeFloat in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeDouble

public void writeDouble(double arg0)
                 throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeDouble in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeBytes

public void writeBytes(java.lang.String arg0)
                throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeBytes in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeChars

public void writeChars(java.lang.String arg0)
                throws java.io.IOException
Wrapped method from DataOutput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
writeChars in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

writeUTF

public void writeUTF(java.lang.String arg0)
              throws java.io.IOException
Warning: This method uses a custom format to encode UTF-8 strings to bytes than specified in DataOutput.

Preserves the internal state of the managed proxy instance.

Specified by:
writeUTF in interface java.io.DataOutput
Throws:
java.io.IOException
See Also:
DataOutput

readFully

public void readFully(byte[] arg0)
               throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readFully in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readFully

public void readFully(byte[] arg0,
                      int arg1,
                      int arg2)
               throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readFully in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

skipBytes

public int skipBytes(int arg0)
              throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
skipBytes in interface java.io.DataInput
Specified by:
skipBytes in interface RandomAccessStorage
Throws:
java.io.IOException
See Also:
DataInput

readBoolean

public boolean readBoolean()
                    throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readBoolean in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readByte

public byte readByte()
              throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readByte in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readUnsignedByte

public int readUnsignedByte()
                     throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readUnsignedByte in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readShort

public short readShort()
                throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readShort in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readUnsignedShort

public int readUnsignedShort()
                      throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readUnsignedShort in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readChar

public char readChar()
              throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readChar in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readInt

public int readInt()
            throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readInt in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readLong

public long readLong()
              throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readLong in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readFloat

public float readFloat()
                throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readFloat in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readDouble

public double readDouble()
                  throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readDouble in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readLine

public java.lang.String readLine()
                          throws java.io.IOException
Wrapped method from DataInput interface.

Preserves the internal state of the managed proxy instance.

Specified by:
readLine in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

readUTF

public java.lang.String readUTF()
                         throws java.io.IOException
Warning: custom implementation will expect different low-level byte encoding than e.g. the identical method from RandomAccessFile!

Preserves the internal state of the managed proxy instance.

Specified by:
readUTF in interface java.io.DataInput
Throws:
java.io.IOException
See Also:
DataInput

finalize

protected void finalize()
                 throws java.lang.Throwable
Cleans the actual file which has been wrapped from disk.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

copyFile

public static void copyFile(java.io.File source,
                            java.io.File destination)
                     throws java.io.IOException
Copies the contents of the source file verbatim to the provided destination file.

This implementation uses the Java NIO API to realize a most efficient copy procedure. The NIO API should automatically be mapped to highly efficient operating system level functionality available in the respective host operating system.

Parameters:
source - File to be copied.
destination - Destination of copy.
Throws:
java.io.IOException

copy

public RandomAccessStorage copy()
                         throws java.io.IOException
Description copied from interface: RandomAccessStorage
Creates a clone, or copy, of this storage, having the exact same contents and the file pointer reset to zero.

Specified by:
copy in interface RandomAccessStorage
Returns:
Throws:
java.io.IOException

createTempFile

protected static java.io.File createTempFile()
                                      throws java.io.IOException
Creates a new temporary file with the configured pre- and suffix in the system-wide temporary file directory.

Returns:
Throws:
java.io.IOException