it.unipi.di.util
Class Directory

java.lang.Object
  extended by it.unipi.di.util.Directory

public class Directory
extends Object

A virtual directory of files identified by unique names and physically contained into one single file on disk.
Through instances of this class it is possible to add new files to a brand-new directory (write mode) or to access files in the directory (read only mode). It is possible to manage only one file at a time (the current file). This makes this implementation not thread-safe. Simultaneous read/write accesses are not supported. Once built on disk, the directory cannot be updated.

Building a new Directory

To create a new directory just instantiate a new object of this class using the WRITE_MODE constant in the constructor. Then create a new file by using either the method newFile(String) and appending new content with the method write(byte[], int, int), or by getting an OutputStream through getOutputStream() and filling sequentially the file. There is no need to close the current file when you're done, that is automatic each time the method newFile(String) is called or this directory is closed. Once all files have been added to the new directory, call close() in order to flush its content into the file specified in the constructor.

Reading a Directory

Instantiate a new object of this class by specifying the file on disk which contains this directory and by using the READ_MODE flag. To get the list of the available files in this virtual directory, use the method list().

To access a given virtual file, use the method getInputStream(String) for a sequential access, or the methods readFileBlock(String, long, byte[]) and mapFile(String) for a random access.

Author:
Claudio Corsi, Paolo Ferragina

Field Summary
static int READ_MODE
           
static int WRITE_MODE
           
 
Constructor Summary
Directory(String filename, int mode)
          Creates a new virtual directory in read or write mode.
 
Method Summary
 void cat(String file, PrintStream out)
          Print on a PrintStream the content of a file.
 void close()
          Closes the directory.
 long dirSize()
          Returns the total size in bytes of this directory.
 boolean exist(String file)
          Returns TRUE if the passed virtual file is contained into this directory.
 long getFilePointer()
          Returns the actual position inside the current file (both in read and write mode).
 InputStream getInputStream(String file)
          Returns an InputStream to read a virtual file sequentially.
 OutputStream getOutputStream()
          Returns an OutputStream to fill sequentially the content of the current file, or null if the current file doesn't exist (i.e. this directory is empty).
 String[] list()
          Lists the names of the virtual files contained in this directory.
 void ls(PrintStream out)
          Prints the file names and their sizes (in byte) for the current directory.
static void main(String[] args)
           
 ByteBuffer mapFile(String file)
          Maps a virtual file into memory.
 void newFile(String file)
          Creates an empty file.
protected static void printUsage()
           
 int readFileBlock(String file, long pos, byte[] block)
          Read a portion of a virtual file belonging to this directory, and starting at the given file position.
 long size()
          Returns the total size of this directory in bytes.
 int sizeOf(String file)
          Returns the size in byte of a virtual file, 0 if the file doesn't exist.
 void write(byte[] b)
          Appends content to the current file from a given byte array.
 void write(byte[] b, int off, int len)
          Appends content to the current file from a given byte array.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

READ_MODE

public static final int READ_MODE
See Also:
Constant Field Values

WRITE_MODE

public static final int WRITE_MODE
See Also:
Constant Field Values
Constructor Detail

Directory

public Directory(String filename,
                 int mode)
          throws IOException
Creates a new virtual directory in read or write mode.

Parameters:
filename - the file on disk storing the directory, or where to put the newly created directory
mode - the open modality
Throws:
IOException
Method Detail

mapFile

public ByteBuffer mapFile(String file)
                   throws IOException
Maps a virtual file into memory.

This method provide a fast random access to virtual files, but it may present problems/bugs on certain JVMs.

Parameters:
file - the virtual file to map
Returns:
a ByteBuffer object to access randomly the file content, or null if the file doesn't exist
Throws:
IOException

getInputStream

public InputStream getInputStream(String file)
                           throws IOException
Returns an InputStream to read a virtual file sequentially. A null reference is returned if the file doesn't exist in this directory.

Parameters:
file - the file to access
Returns:
an InputStream to the content of the file, or null if the file doesn't exist
Throws:
IOException

readFileBlock

public int readFileBlock(String file,
                         long pos,
                         byte[] block)
                  throws IOException
Read a portion of a virtual file belonging to this directory, and starting at the given file position. If S is the result of the method sizeOf(String) for this file, then the portion to be extracted must start in the range [0, S-1]. This method tries to read up to block.length bytes. If there are less bytes to read, the remaining bytes will be unspecified.

This method returns the number of bytes effectively read.

Parameters:
file - the virtual file
pos - the starting position of the block to be fetched
block - the buffer in which the block has to be loaded
Returns:
the number of bytes effectively read, or -1 if the file doesn't exist or the starting position is negative or greater than the file size
Throws:
IOException

list

public String[] list()
Lists the names of the virtual files contained in this directory.

Returns:
the names of the virtual files

sizeOf

public int sizeOf(String file)
Returns the size in byte of a virtual file, 0 if the file doesn't exist.
This method does not change the directory current file.

Parameters:
file - the virtual file to measure
Returns:
the size of the file in bytes

size

public long size()
          throws IOException
Returns the total size of this directory in bytes.

Returns:
the size of this directory in bytes
Throws:
IOException

close

public void close()
           throws IOException
Closes the directory. If it has been opened in WRITE_MODE then this method writes on disk a file containing all the virtual files of this directory and the auxiliary data structures needed to efficiently access them. The file name is the one specified at construction time.

Throws:
IOException

exist

public boolean exist(String file)
Returns TRUE if the passed virtual file is contained into this directory.

Parameters:
file - the file name to check
Returns:
TRUE if the file is contained into this directory

newFile

public void newFile(String file)
             throws IOException
Creates an empty file. The specified name must be not already in use into this directory.

Parameters:
file - the file to add in this directory
Throws:
IOException

write

public void write(byte[] b,
                  int off,
                  int len)
           throws IOException
Appends content to the current file from a given byte array.

Parameters:
b - the content to append (as a byte array)
off - the offset from which the copy must start
len - the number of bytes to write
Throws:
IOException
See Also:
newFile(String)

write

public void write(byte[] b)
           throws IOException
Appends content to the current file from a given byte array.

Parameters:
b - the content to append (as an entire byte array)
Throws:
IOException
See Also:
newFile(String)

getOutputStream

public OutputStream getOutputStream()
                             throws IOException
Returns an OutputStream to fill sequentially the content of the current file, or null if the current file doesn't exist (i.e. this directory is empty). Writing into a file using both the returned stream and the method write(byte[], int, int) can generate undefined results.

Returns:
an OutputStream to write into the current file, or null if the directory is empty
Throws:
IOException
See Also:
newFile(String)

ls

public void ls(PrintStream out)
Prints the file names and their sizes (in byte) for the current directory.

Parameters:
out - the PrintStream where to list this directory content

cat

public void cat(String file,
                PrintStream out)
         throws IOException
Print on a PrintStream the content of a file.

Parameters:
file - the virtual file to print
out - the PrintStream where to print the file content
Throws:
IOException - if the file is not contained into this directory.

dirSize

public long dirSize()
Returns the total size in bytes of this directory. This is the length of the file where this directory is stored.

Returns:
the size of this directory

getFilePointer

public long getFilePointer()
                    throws IOException
Returns the actual position inside the current file (both in read and write mode).

Returns:
the actual position inside the current file
Throws:
IOException

printUsage

protected static void printUsage()

main

public static void main(String[] args)
                 throws Exception
Throws:
Exception