SK.gnome.dwarf.mail.store
Class GenericFileStore

java.lang.Object
  extended bySK.gnome.dwarf.GenericService
      extended bySK.gnome.dwarf.mail.store.GenericFileStore
All Implemented Interfaces:
SK.gnome.dwarf.Service
Direct Known Subclasses:
FileACLStore, FileMailStore, FileUserStore

public abstract class GenericFileStore
extends SK.gnome.dwarf.GenericService

This class provides a generic filesystem-based store.

This kind of store may be used to hold and manage a user-specific data, like mail messages, security permissions, application configuration files, etc. There is a separate space reserved for each user, represented by a directory in the filesystem.

All user files are kept within the specified userBaseDir directory. For each user ther will be a special subdirectory created in it, with the name equal to the user's name. It may be then obtained via the getUserDirectory(String) method.

If letterSubdirs feature is enabled, the user subdirectories will be grouped according to the first letter of the user name. Thus a user named "joe" would reside in the "<userBaseDir>/j/joe" subdirectory instead of the default "<userBaseDir>/joe". If autoCreate feature is enabled, the getUserDirectory(String) method will automatically create a store for the given user if it does not yet exists.

The storeObject(String, String, Object) and readObject(String, String) methods may be used for reading and storing arbitrary serializable objects to the store. If backupObjects feature is enabled, the storing method will automatically create a backup of the existing file before it stores the serialized object to it. This option is enabled by default.


Field Summary
protected  boolean autoCreate
          Whether a store will be created automatically for the given user by the getUserDirectory(String) method.
protected  boolean backupObjects
          Whether a backup file will be create when storing the serialized object by the storeObject(String, String, Object) method.
protected  boolean letterSubdirs
          Whether a subdirectories will be created according to the first letter of a user identification.
protected  java.io.File userBaseDir
          The base directory of the store.
 
Fields inherited from class SK.gnome.dwarf.GenericService
initParameters, parent
 
Fields inherited from interface SK.gnome.dwarf.Service
INITIALIZED, LOG_DEBUG, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_TRACE, LOG_WARN, LOG_XFER, SHUTDOWN, STARTED, STOPPED
 
Constructor Summary
GenericFileStore(java.lang.String name)
          Creates a new GenericFileStore.
 
Method Summary
 void create(java.lang.String user)
          Creates a store for the given user.
 boolean exists(java.lang.String user)
          Whether the given user's store exists.
protected  java.io.File getUserDirectory(java.lang.String user)
          Returns a subdirectory associated with the given user.
 void init(SK.gnome.dwarf.Server parent)
           
 java.lang.String[] listUsers()
          Returns a list of all users present in this store.
protected  boolean lock(java.lang.String user, java.lang.String filename)
          Locks the given file within the user subdirectory.
protected  java.lang.Object readObject(java.lang.String user, java.lang.String filename)
          Reads an object from the given user store.
 void remove(java.lang.String user)
          Removes the given user's store.
 void setAutoCreate(boolean enable)
          Enables or disables the store auto-creation feature.
 void setBackupObjects(boolean enable)
          Enables or disables backup files when storing the serialized objects.
 void setLetterSubdirs(boolean enable)
          Enables or disables the first-letter subdirectories.
 void setUserBaseDir(java.io.File dir)
          Sets the base directory of the store.
protected  void storeObject(java.lang.String user, java.lang.String filename, java.lang.Object object)
          Stores the object to the given user store.
protected  void unlock(java.lang.String user, java.lang.String filename)
          Unlocks the given file within the user subdirectory.
 
Methods inherited from class SK.gnome.dwarf.GenericService
getAuthenticator, getAuthFacility, getFullName, getInitParameter, getInitParameterNames, getLogFacility, getLogger, getName, getParameters, getPrincipal, getShutdownTimeout, getState, log, log, login, logout, setAuthFacility, setInitParameters, setLogFacility, shutdown, start, stop, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

autoCreate

protected boolean autoCreate
Whether a store will be created automatically for the given user by the getUserDirectory(String) method.

Default value: MailConstants.MAIL_DEFAULT_AUTO_CREATE_STORE


letterSubdirs

protected boolean letterSubdirs
Whether a subdirectories will be created according to the first letter of a user identification.

Default value: false


backupObjects

protected boolean backupObjects
Whether a backup file will be create when storing the serialized object by the storeObject(String, String, Object) method.

Default value: true


userBaseDir

protected java.io.File userBaseDir
The base directory of the store.

Constructor Detail

GenericFileStore

public GenericFileStore(java.lang.String name)
Creates a new GenericFileStore.

Method Detail

setAutoCreate

public void setAutoCreate(boolean enable)
Enables or disables the store auto-creation feature.

Parameters:
enable - true to enable the feature, false to disable
See Also:
autoCreate

setLetterSubdirs

public void setLetterSubdirs(boolean enable)
Enables or disables the first-letter subdirectories.

Parameters:
enable - true to enable the feature, false to disable
See Also:
letterSubdirs

setBackupObjects

public void setBackupObjects(boolean enable)
Enables or disables backup files when storing the serialized objects.

Parameters:
enable - true to enable the feature, false to disable
See Also:
backupObjects

setUserBaseDir

public void setUserBaseDir(java.io.File dir)
Sets the base directory of the store.

Parameters:
dir - the directory

init

public void init(SK.gnome.dwarf.Server parent)
          throws SK.gnome.dwarf.ServiceException
Throws:
SK.gnome.dwarf.ServiceException

create

public void create(java.lang.String user)
            throws MailException
Creates a store for the given user.

Parameters:
user - the user identification
Throws:
MailException - if an error occured

exists

public boolean exists(java.lang.String user)
               throws MailException
Whether the given user's store exists.

Parameters:
user - the user identification
Returns:
true if the store exists, false otherwise
Throws:
MailException - if an error occured

remove

public void remove(java.lang.String user)
            throws MailException
Removes the given user's store.

Parameters:
user - the user identification
Throws:
MailException - if an error occured

listUsers

public java.lang.String[] listUsers()
                             throws MailException
Returns a list of all users present in this store.

Returns:
the array of user identifications
Throws:
MailException - if an error occured

getUserDirectory

protected java.io.File getUserDirectory(java.lang.String user)
                                 throws MailException
Returns a subdirectory associated with the given user.

Parameters:
user - the user identification
Returns:
the user's own subdirectory
Throws:
MailException - if an error occured

readObject

protected java.lang.Object readObject(java.lang.String user,
                                      java.lang.String filename)
                               throws MailException
Reads an object from the given user store.

The returned object is read from a file input stream denoted by the filename argument. If the input file does not exists, a null value is returned.

The object must be stored via the storeObject(String, String, Object) first to be made available for reading.

Parameters:
user - the user identification
filename - the name of file to read the object from
Returns:
the read object or null if the source file does not exists
Throws:
MailException - if an error occured

storeObject

protected void storeObject(java.lang.String user,
                           java.lang.String filename,
                           java.lang.Object object)
                    throws MailException
Stores the object to the given user store.

The object is stored to a file output stream denoted by the filename argument. Only serializable objects may be stored by this method, and only one object instance per file is permitted.

The stored object can be read via the readObject(String, String) method.

Parameters:
user - the user udentification
filename - the name of file to store the object to
object - the object to be stored
Throws:
MailException - if an error occured

lock

protected boolean lock(java.lang.String user,
                       java.lang.String filename)
                throws MailException
Locks the given file within the user subdirectory.

If the filename argument is null, the whole user subdirectory will be locked instead of a single file.

Parameters:
user - the user identification
filename - the name of file
Returns:
true if the file has been locked, false otherwise
Throws:
MailException - if an error occured

unlock

protected void unlock(java.lang.String user,
                      java.lang.String filename)
               throws MailException
Unlocks the given file within the user subdirectory.

If the filename argument is null, the whole user subdirectory will be unlocked instead of a single file.

Parameters:
user - the user identification
filename - the name of file
Throws:
MailException - if an error occured


Copyright (c) 2004-2005, Gnome Ltd. All rights reserved.