org.abstracthorizon.mercury.maildir
Class MaildirStore

java.lang.Object
  javax.mail.Service
      javax.mail.Store
          org.abstracthorizon.mercury.maildir.MaildirStore

Direct Known Subclasses:

UIDMaildirStore

public class MaildirStore
extends javax.mail.Store

This is simple maildir implementation store. It reads files from the cur and new subdirectories of the store or subdirectories of store's folders. When new message is created tmp subdirectory is used for RFC-822 mail to be written in it and then it is renamed to new directory. This implementation doesn't write/read to/from any special index files and it is not implementing UIDFolder interface from javax.mail API. Messages are ordered in folders in the way java.io.File.list method is returning files.

It takes a path of the store an input parameter (path in URLName). Also it uses following session properties:

property	default value if not present	description
maildir.leadingDot	true	If this property has value of true then folders' directories are with the leading dot. This is standard used by most implementations of maildir. If value is set to false then folders' directories are stored without leading dot. Note: If directories are without leading dot then tmp, cur and new are invalid names of folders.
maildir.infoSeparator	System.getProperty("path.separator") is ":" then ":". Othewise "."	If value is set then it will be used as separator of info part in maildir's filename.
maildir.httpSyntax	false is ":" then ":". Othewise "."	If set to true then URLName's syntax for maildir should be: maildir://user:password@host:port/foldername?base=base_directory_of_maildir_store. Otherwise it is maildir://user:password@host:port/base_directory_of_maildir_store#foldername. Note: foldername is not used when store is being obtained.
maildir.home		If maildir store's base directory is not set in URL this session property will be queried and its value used if present.

Maildir store's base directory is searched in following order:

1. URLName (check maildir.httpSyntax for more details). If not present then
2. maildir.home from session. If not present then
3. user.home from system properties with .mail appended to the path. If that directory is not present then
4. user.home from system properties with Mail appended to the path.

If all fails it obtaining the store will fail as well.

This implementation also does substitutions in supplied path based on url name parameters:

• {user} in the path is substituted by username from url name
• {protocol} in the path is substituted by protocol from url name
• {port} in the path is substituted by port from url name
• {host} in the path is substituted by host from url name

This class implements centralised cached directory of all currently open folder.

Folder data actually contains messages while folders have only wrappers with references to folder data's messages. Each folder uses wrappers to maintain message number. All open folders are registered with folder data and changes one folder, through folder data, are immediately propagated to other folder over the same folder data (same virtually folder). Folder data here serves as central repository of messages over one directory.

If new messages are discovered in directory or one folder over folder data has new messages added by append method, all other folders over the same folder data will be notified of new messages and then will immediately appear in their lists

Similarily if one folder expunges messages or messages are detected as deleted from the underlaying directory, all folder's will be notified of the change and all messages will be marked as expunged.

Author:

Daniel Senudula

Field Summary

protected File	base Store's base directory file
protected Map<File,Reference<MaildirFolderData>>	directories Cache
static String	HOME Store's home directory session attribute name
static String	HTTP_SYNTAX Http syntax session attribute name
protected boolean	httpSyntax Cached http syntax property
static String	INFO_SEPARATOR Info separator session attribute name
protected char	infoSeparator Cached info separator property
static String	LEADING_DOT Leading dot session attribute name
protected boolean	leadingDot Cached leading dot property
static long	MAX_FOLDER_DATA_LIFE Amount of time folder is going to be kept in list of folders

Fields inherited from class javax.mail.Service

debug, session, url

Constructor Summary

MaildirStore(javax.mail.Session session, javax.mail.URLName urlname)
Constructor

Method Summary

protected File	createBaseFile(javax.mail.URLName urlName, String baseName) Creates base file and substitues {user}, {port}, {host} and {protocol}
protected MaildirFolder	createFolder(MaildirFolderData folderData) Creates new folder instance with given folder data.
protected MaildirFolderData	createFolderData(File file) This implementation creates MaildirFolderData from supplied file.
File	getBaseFile() Retuns base file (store's base directory)
javax.mail.Folder	getDefaultFolder() Returns default folder
javax.mail.Folder	getFolder(String name) Returns new folder from full folder's name
javax.mail.Folder	getFolder(javax.mail.URLName urlName) Returns new folder from URLName.
protected MaildirFolderData	getFolderData(File file) This method returns folder data needed for folder to operate on.
protected MaildirFolderData	getFolderData(String name) Returns folder data for given folder.
char	getInfoSeparator() Returns info separator
javax.mail.Folder	getParentFolder(MaildirFolderData folderData) Returns folder with given folder data
boolean	isHttpSyntax() Returns http syntax
boolean	isLeadingDot() Returns leading dot
protected void	parseURLName(javax.mail.URLName urlname) Parses url name
protected void	processParam(javax.mail.URLName urlName, String param) Processes singe parameter from url name
protected boolean	protocolConnect(String host, int port, String user, String password) This method returns true always.
protected String	replace(String s, String what, String with) Replaces substring

Methods inherited from class javax.mail.Store

addFolderListener, addStoreListener, getPersonalNamespaces, getSharedNamespaces, getUserNamespaces, notifyFolderListeners, notifyFolderRenamedListeners, notifyStoreListeners, removeFolderListener, removeStoreListener

Methods inherited from class javax.mail.Service

addConnectionListener, close, connect, connect, connect, connect, finalize, getURLName, isConnected, notifyConnectionListeners, queueEvent, removeConnectionListener, setConnected, setURLName, toString

Methods inherited from class java.lang.Object

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

Field Detail

LEADING_DOT

public static final String LEADING_DOT

Leading dot session attribute name

See Also:

Constant Field Values

HOME

public static final String HOME

Store's home directory session attribute name

See Also:

Constant Field Values

INFO_SEPARATOR

public static final String INFO_SEPARATOR

Info separator session attribute name

See Also:

Constant Field Values

HTTP_SYNTAX

public static final String HTTP_SYNTAX

Http syntax session attribute name

See Also:

Constant Field Values

MAX_FOLDER_DATA_LIFE

public static final long MAX_FOLDER_DATA_LIFE

Amount of time folder is going to be kept in list of folders

See Also:

Constant Field Values

base

protected File base

Store's base directory file

leadingDot

protected boolean leadingDot

Cached leading dot property

httpSyntax

protected boolean httpSyntax

Cached http syntax property

infoSeparator

protected char infoSeparator

Cached info separator property

directories

protected Map<File,Reference<MaildirFolderData>> directories

Cache

Constructor Detail

MaildirStore

public MaildirStore(javax.mail.Session session,
                    javax.mail.URLName urlname)

Constructor

Parameters:

session - mail session

urlname - url name

Method Detail

parseURLName

protected void parseURLName(javax.mail.URLName urlname)

Parses url name

Parameters:

urlname - url name

processParam

protected void processParam(javax.mail.URLName urlName,
                            String param)

Processes singe parameter from url name

Parameters:

urlName - url name

param - parameter

createBaseFile

protected File createBaseFile(javax.mail.URLName urlName,
                              String baseName)

Creates base file and substitues {user}, {port}, {host} and {protocol}

Parameters:

urlName - url name

baseName - directory path

Returns:

created file that represents base directory of the store

replace

protected String replace(String s,
                         String what,
                         String with)

Replaces substring

Parameters:

s - string on which operation is done

what - what to be replaced

with - new value to be placed instead

Returns:

new string

getInfoSeparator

public char getInfoSeparator()

Returns info separator

Returns:

info separator

isLeadingDot

public boolean isLeadingDot()

Returns leading dot

Returns:

leading dot

isHttpSyntax

public boolean isHttpSyntax()

Returns http syntax

Returns:

http syntax

getBaseFile

public File getBaseFile()

Retuns base file (store's base directory)

Returns:

base file

getDefaultFolder

public javax.mail.Folder getDefaultFolder()
                                   throws javax.mail.MessagingException

Returns default folder

Specified by:

getDefaultFolder in class javax.mail.Store

Returns:

default folder

Throws:

javax.mail.MessagingException

getFolderData

protected MaildirFolderData getFolderData(String name)

Returns folder data for given folder. This is needed for new folder is created. This implementation obtains proper folder's directory and passes file to getFolderData(File) method.

Parameters:

name - full folder's name

Returns:

folder data

getFolderData

protected MaildirFolderData getFolderData(File file)

This method returns folder data needed for folder to operate on. If first checks cache and if there is no folder data in it new will be created and stored in the cache.

Parameters:

file - directory

Returns:

new folder data

createFolderData

protected MaildirFolderData createFolderData(File file)

This implementation creates MaildirFolderData from supplied file.

Parameters:

file - file

Returns:

new maildir folder data

getParentFolder

public javax.mail.Folder getParentFolder(MaildirFolderData folderData)
                                  throws javax.mail.MessagingException

Returns folder with given folder data

Parameters:

folderData - folder data

Returns:

new folder instance

Throws:

javax.mail.MessagingException

getFolder

public javax.mail.Folder getFolder(String name)
                            throws javax.mail.MessagingException

Returns new folder from full folder's name

Specified by:

getFolder in class javax.mail.Store

Parameters:

name - full folder's name

Returns:

new folder

Throws:

javax.mail.MessagingException

getFolder

public javax.mail.Folder getFolder(javax.mail.URLName urlName)
                            throws javax.mail.MessagingException

Returns new folder from URLName. if maildir.httpSyntax attribute has value of true then url name's file is used, otherwise url name's ref is used.

Specified by:

getFolder in class javax.mail.Store

Parameters:

urlName - url name

Returns:

new folder

Throws:

javax.mail.MessagingException

createFolder

protected MaildirFolder createFolder(MaildirFolderData folderData)

Creates new folder instance with given folder data. This metod is to be overriden by class extensions.

Parameters:

folderData - folder data

Returns:

new folder instance

protocolConnect

protected boolean protocolConnect(String host,
                                  int port,
                                  String user,
                                  String password)
                           throws javax.mail.MessagingException

This method returns true always.

Overrides:

protocolConnect in class javax.mail.Service

Parameters:

host - ignored

port - ignored

user - ignored

password - ignored

Returns:

true

Throws:

javax.mail.MessagingException - never