com.sas.edir.content
Class FileManager

java.lang.Object
  |
  +--java.util.Dictionary
        |
        +--com.sas.edir.content.FileManager

public final class FileManager

extends java.util.Dictionary

The File Manager gives a java.util.Dictionary access to the file system.
Objects (java.io.InputStream, java.io.Reader, or java.io.Serializable) are added
into the FileManager based on a Serializable Key, FileManager.Key.
Objects (java.io.InputStream, java.io.Reader, or java.io.Serializable) are retrieved
from the FileManager based on the FileManager.Key.

Two FileManager.Key objects are equal (by default) if their user (getUser())
and their uid (getUID()) fields are equal.  This can be redefined on a per
FileManager.Key extension.

The actual storage of the data is done through a protected class, FileManager.Storage.
There is one Storage class per user. (obtained from the FileManager.Key information)
Given a FileManager.Key, the FileManager.Storage class generates a unique key
and writes/reads the file from the file system using it's unique key.

The FileManager.Key class must be serializable in order for the Storage class
to write it's FileManager.Key/Storage class key mapping state to the file system.

In addition to the java.util.Dictionary methods, FileManager provides

public Enumeration clear()
public Enumeration clear(Object key)
public Enumeration keys(Object key)
public Enumeration elements(Object key)
public Enumeration users()
public long getUsage(Object key)
public long setQuota(Object key, long quota)
public long getQuota(Object key)
public long getUsage()
public File getFile(Object key)
public int getGarbageCollectionInterval()
public int setGarbageCollectionInterval(int secs)
public void gc()
public int setReadBufferSize(int size)
public int getReadBufferSize()
public int setUserStackSize(int size)
public int getUserStackSize()

in order to aid in System Administration.

Version:

1.0

Author:

SAS

Inner Class Summary

static class	FileManager.DefaultKey Default key.
protected static class	FileManager.GarbageCollector The GarbageCollector's resposibility is to lazily enumerate the Storage object's keys and check for expiration.
static class	FileManager.Key This is the abstract class that all keys must extend in order to store content in the FileManager.
protected static class	FileManager.Link Link extends java.io.File and provides a "first-line" defense that discourages inadvertant modifications.
protected static class	FileManager.Storage The Storage class provides java.util.Dictionary access to the file system for the File Manager.

Field Summary

static java.lang.String	ROOT Storage designated for the root location of the File Manager
static long	UNLIMITED The default Quota assigned to a user

Method Summary

protected FileManager.Storage	borrowStorage(java.lang.Object key) Checks out and returns a Storage Object based on the specified key
java.util.Enumeration	clear() Clears this File Manager so that it contains no keys.
java.util.Enumeration	clear(java.lang.Object key) Clears this FileManager so that it contains no keys for a particular user.
static FileManager.Key	createDefaultKey(java.lang.String path) Returns a new DefaultKey based on a path.
static FileManager.Key	createDefaultKey(java.lang.String user, java.lang.Object uid) Returns a new DefaultKey based on a user and a unique id A null or FileManager.ROOT user will store the data associated with this key in the root directory of the FileManager.
protected FileManager.GarbageCollector	createGarbageCollector() Creates the garbage collector for this instance.
protected java.lang.Integer	createReadBufferSize() Creates the read buffer size either from serialized data or default 512 This value is serialized to/from the FileManager.ROOT
protected java.lang.Integer	createUserStackSize() Creates the user stack size either from serialized data or default 200 This value is serialized to/from the FileManager.ROOT
java.util.Enumeration	elements() Returns an enumeration of the values in this dictionary.
java.util.Enumeration	elements(java.lang.Object key) Returns an enumeration of the values in this dictionary for a particular user.
void	gc() Manually run the garbage collector to collect expired keys
java.lang.Object	get(java.lang.Object key) Returns the value to which the key is mapped in this dictionary.
java.io.File	getDirectory() Returns the java.io.File that is the location of the File Manager.
java.io.File	getFile() Returns the java.io.File that is the fully qualified name of the File Manager.
java.io.File	getFile(java.lang.Object key) Returns a FileManager.Link based on a FileManager.Key.
int	getGarbageCollectionInterval() Gets the garbage collection interval of expired keys in seconds
protected FileManager.GarbageCollector	getGarbageCollector() Gets the garbage collector for this instance.
static FileManager	getInstance() Returns the single instance of this class.
protected FileManager.Key	getKey(java.lang.Object key) Returns a Key based on the specified key.
java.lang.String	getName() Returns the name of the File Manager
long	getQuota(java.lang.Object key) Gets the quota in bytes for a particular user in the File Manager.
int	getReadBufferSize() Gets the read buffer size for Stream/Reader IO.
protected int	getType(java.lang.Object object) Types of Objects the File Manager can store.
long	getUsage() Returns usage in bytes of the File Manager.
long	getUsage(java.lang.Object key) Returns usage in bytes of a particular user in the File Manager.
int	getUserStackSize() Gets the user stack size to maintain in memory.
protected boolean	isAvailable(FileManager.Storage storage) Returns the availablilty of a Storage Object based on the specified storage
protected boolean	isAvailable(java.lang.Object key) Returns the availablilty of a Storage Object based on the specified key
boolean	isEmpty() Tests if this dictionary maps no keys to value.
java.util.Enumeration	keys() Returns an enumeration of the keys in this dictionary.
java.util.Enumeration	keys(java.lang.Object key) Returns an enumeration of the keys in this dictionary for a particular user.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Maps the specified key to the specified value in this dictionary.
java.lang.Object	remove(java.lang.Object key) Removes the key (and its corresponding value) from this dictionary.
protected void	returnStorage(FileManager.Storage storage) Returns a Storage Object to the pool
void	save(java.lang.Object key)
protected FileManager.GarbageCollector	saveGarbageCollector() Saves the garbage collector for this instance.
protected java.lang.Integer	saveReadBufferSize() Saves the read buffer size.
protected java.lang.Integer	saveUserStackSize() Saves the user stack size.
void	setDebugStream(java.io.PrintStream debugStream)
int	setGarbageCollectionInterval(int secs) Sets the garbage collection interval of expired keys in seconds
void	setLocation(java.lang.String location)
void	setName(java.lang.String name)
long	setQuota(java.lang.Object key, long quota) Sets the quota in bytes for a particular user in the File Manager.
int	setReadBufferSize(int size) Sets the read buffer size for Stream/Reader IO.
int	setUserStackSize(int size) Sets the user stack size to maintain in memory.
int	size() Returns the number of keys in this dictionary.
void	start()
java.util.Enumeration	users() Returns an enumeration of the users in this dictionary.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ROOT

public static java.lang.String ROOT

Storage designated for the root location of the File Manager

UNLIMITED

public static long UNLIMITED

The default Quota assigned to a user

Method Detail

createDefaultKey

public static FileManager.Key createDefaultKey(java.lang.String user,
                                               java.lang.Object uid)

Returns a new DefaultKey based on a user and a unique id A null or FileManager.ROOT user will store the data associated with this key in the root directory of the FileManager.

createDefaultKey

public static FileManager.Key createDefaultKey(java.lang.String path)

Returns a new DefaultKey based on a path. User: everything before java.io.File.separator UID: everything after java.io.File.separator If no java.io.File.separator exists in path, then path is the UID

getInstance

public static final FileManager getInstance()

Returns the single instance of this class.

Returns:

The class instance.

setDebugStream

public void setDebugStream(java.io.PrintStream debugStream)

getDirectory

public java.io.File getDirectory()

Returns the java.io.File that is the location of the File Manager. The directories are created if necessary.

setLocation

public void setLocation(java.lang.String location)

getName

public java.lang.String getName()

Returns the name of the File Manager

setName

public void setName(java.lang.String name)

getFile

public java.io.File getFile()

Returns the java.io.File that is the fully qualified name of the File Manager. That is, getLocation() + java.io.File.separator + getName() The directories are created if necessary.

start

public void start()

elements

public java.util.Enumeration elements()

Returns an enumeration of the values in this dictionary. Use the Enumeration methods on the returned object to fetch the elements sequentially.

Overrides:

elements in class java.util.Dictionary

Returns:

an enumeration of the values in this dictionary.

See Also:

Dictionary.keys(), Enumeration

get

public java.lang.Object get(java.lang.Object key)

Returns the value to which the key is mapped in this dictionary.

Overrides:

get in class java.util.Dictionary

Parameters:

key - a key in this dictionary. null if the key is not mapped to any value in this dictionary.

Returns:

the value to which the key is mapped in this dictionary;

See Also:

If key is not a FileManager.Key (!(key instanceof FileManager.Key)) then a FileManager.DefaultKey will be created using key as the UID

isEmpty

public boolean isEmpty()

Tests if this dictionary maps no keys to value.

Overrides:

isEmpty in class java.util.Dictionary

Returns:

true if this dictionary maps no keys to values; false otherwise.

keys

public java.util.Enumeration keys()

Returns an enumeration of the keys in this dictionary.

Overrides:

keys in class java.util.Dictionary

Returns:

an enumeration of the keys in this dictionary.

See Also:

Dictionary.elements(), Enumeration

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Maps the specified key to the specified value in this dictionary. Neither the key nor the value can be null.

The value can be retrieved by calling the get method with a key that is equal to the original key.

Overrides:

put in class java.util.Dictionary

Parameters:

key - the hashtable key.

value - the value. One of java.io.InputStream, java.io.Reader, java.io.Serializable

Returns:

the previous value to which the key was mapped in this dictionary, or null if the key did not have a previous mapping.

Throws:

java.lang.NullPointerException - if the key or value is null. RuntimeException if the user's quota has been exceeded.

See Also:

Object.equals(java.lang.Object), If key is not a FileManager.Key (!(key instanceof FileManager.Key)) then a FileManager.DefaultKey will be created using key as the UID

remove

public java.lang.Object remove(java.lang.Object key)

Removes the key (and its corresponding value) from this dictionary. This method does nothing if the key is not in this dictionary.

Overrides:

remove in class java.util.Dictionary

Parameters:

key - the key that needs to be removed.

Returns:

the value to which the key had been mapped in this dictionary, or null if the key did not have a mapping. If key is not a FileManager.Key (!(key instanceof FileManager.Key)) then a FileManager.DefaultKey will be created using key as the UID The key is notified of the removal by FileManager.Key.delete() If FileManager.Key.delete() throws an Exception, the key and data will not be removed.

save

public void save(java.lang.Object key)

size

public int size()

Returns the number of keys in this dictionary.

Overrides:

size in class java.util.Dictionary

Returns:

the number of keys in this dictionary.

clear

public java.util.Enumeration clear()

Clears this File Manager so that it contains no keys. This method returns an Enumeration of java.io.File objects that could not be removed.

clear

public java.util.Enumeration clear(java.lang.Object key)

Clears this FileManager so that it contains no keys for a particular user.

keys

public java.util.Enumeration keys(java.lang.Object key)

Returns an enumeration of the keys in this dictionary for a particular user.

elements

public java.util.Enumeration elements(java.lang.Object key)

Returns an enumeration of the values in this dictionary for a particular user. Use the Enumeration methods on the returned object to fetch the elements sequentially.

users

public java.util.Enumeration users()

Returns an enumeration of the users in this dictionary. Use the Enumeration methods on the returned object to fetch the elements sequentially.

getUsage

public long getUsage(java.lang.Object key)

Returns usage in bytes of a particular user in the File Manager.

setQuota

public long setQuota(java.lang.Object key,
                     long quota)

Sets the quota in bytes for a particular user in the File Manager. Negative values imply UNLIMITED

getQuota

public long getQuota(java.lang.Object key)

Gets the quota in bytes for a particular user in the File Manager. Negative values imply UNLIMITED

getUsage

public long getUsage()

Returns usage in bytes of the File Manager.

getFile

public java.io.File getFile(java.lang.Object key)

Returns a FileManager.Link based on a FileManager.Key. FileManager.Link extends java.io.File and provides a "first-line" defense that discourages inadvertant modifications.

getGarbageCollectionInterval

public int getGarbageCollectionInterval()

Gets the garbage collection interval of expired keys in seconds

setGarbageCollectionInterval

public int setGarbageCollectionInterval(int secs)

Sets the garbage collection interval of expired keys in seconds

gc

public void gc()

Manually run the garbage collector to collect expired keys

setReadBufferSize

public int setReadBufferSize(int size)

Sets the read buffer size for Stream/Reader IO. By default, this value is 512.

getReadBufferSize

public int getReadBufferSize()

Gets the read buffer size for Stream/Reader IO. By default, this value is 512.

setUserStackSize

public int setUserStackSize(int size)

Sets the user stack size to maintain in memory. Since Storage classes are created dynamically, the FileManager can cache the Storage classes. The least accessed Storage classes will be discarded when the stack size is met. Negative values imply the default (200). A value of 0 imply 1.

getUserStackSize

public int getUserStackSize()

Gets the user stack size to maintain in memory. Since Storage classes are created dynamically, the FileManager can cache the Storage classes. The least accessed Storage classes will be discarded when the stack size is met.

createUserStackSize

protected java.lang.Integer createUserStackSize()

Creates the user stack size either from serialized data or default 200 This value is serialized to/from the FileManager.ROOT

saveUserStackSize

protected java.lang.Integer saveUserStackSize()

Saves the user stack size. This value is serialized to/from the FileManager.ROOT

createReadBufferSize

protected java.lang.Integer createReadBufferSize()

Creates the read buffer size either from serialized data or default 512 This value is serialized to/from the FileManager.ROOT

saveReadBufferSize

protected java.lang.Integer saveReadBufferSize()

Saves the read buffer size. This value is serialized to/from the FileManager.ROOT

getGarbageCollector

protected FileManager.GarbageCollector getGarbageCollector()

Gets the garbage collector for this instance.

createGarbageCollector

protected FileManager.GarbageCollector createGarbageCollector()

Creates the garbage collector for this instance. This value is serialized to/from the FileManager.ROOT

saveGarbageCollector

protected FileManager.GarbageCollector saveGarbageCollector()

Saves the garbage collector for this instance. This value is serialized to/from the FileManager.ROOT

getType

protected int getType(java.lang.Object object)

Types of Objects the File Manager can store. These are flags so you get back what you put in.

getKey

protected FileManager.Key getKey(java.lang.Object key)

Returns a Key based on the specified key. If the key is a FileManager.Key then it returns the key. Otherwise a FileManager.DefaultKey is created using kek as the unique identifier

borrowStorage

protected FileManager.Storage borrowStorage(java.lang.Object key)

Checks out and returns a Storage Object based on the specified key

returnStorage

protected void returnStorage(FileManager.Storage storage)

Returns a Storage Object to the pool

isAvailable

protected boolean isAvailable(java.lang.Object key)

Returns the availablilty of a Storage Object based on the specified key

isAvailable

protected boolean isAvailable(FileManager.Storage storage)

Returns the availablilty of a Storage Object based on the specified storage