com.nitido.nimx.nuggets.javamail
Class JavaMailNugget

java.lang.Object
  com.nitido.nim.Nugget
      com.nitido.nimx.nuggets.javamail.JavaMailNugget

All Implemented Interfaces:

CredentialConstants, java.io.Serializable

Direct Known Subclasses:

JavaMailNuggetImpl, JavaMailNuggetImpl

public abstract class JavaMailNugget
extends Nugget
implements CredentialConstants

The JavaMailNugget is a NiM nugget that abstracts access to IMAP and SMTP servers.

This Nugget acts as the integrated access point for both reading and sending email messages with JavaMail v1.2. In other words, it acts as the wrapper for both the javax.mail.Store and javax.mail.Transport classes. It also provides access to message unique ID interfaces, and thus, offloads developers' burden to manipulating with the javax.mail.UIDFolder interface.

With the NiM architecture, this Nugget can retrieve user's personal authentication credentials directly from the DataControl and connect to the server automatically. This feature helps developer to write single signon application rapidly and effectively.

The standard IMAP and SMTP implementation comes with the JavaMail package is used by default. (i.e. packages com.sun.mail.imap and com.sun.mail.smtp). If you want to use your custom implementation of IMAP and SMTP protocol or some other platform specific implementations, you can override this default behaviour by setting the system properties "mail.imap.class" and "mail.smtp.class" to the class name of your new implementation of javax.mail.Store and javax.mail.Transport classes. However, those implementation should use the same properties as declared by the standard JavaMail packages. Otherwise, this Nugget will not be able to convert the Nugget settings into the properties for your protocol implementations.

Supported Server
This nugget is designed to work with Sun's JavaMail API 1.4. For reading mail, it expects the mail server to support IMAP4rev1 (RFC 2060) with the mail Quota support (RFC 2087).

The send mail server should be supporting standard SMTP (RFC 821), preferably the new version of SMTP (RFC 2821).

Programming Model
When contacting an IMAP server, the JavaMail interface keeps a socket connection for each opened folder. Although this consume large amount of resources, it is essential for supporting the "smart message fetch" feature (i.e. retrieve message information only when requested.)

On the other hand, since NiM can be potentially executed on a cluster environment, a client request may be handled by different machines at different time. Leaving a socket connection opened after a request may create unpredictable behaviour on a such system. Therefore, your application must open the mail folder at the beginning of each client request and close the folder when the request has been served. You should never leave a folder opened between request. For example, if you are writing a JSP that displays all the messages stored in the "INBOX", you may have code like:

 ...
 Folder folder = myJavaMailNugget.openFolderByName( "INBOX" );
 Message[] msgs = folder.getMessages();
 for( int i=0; i<msgs.length; i++ )
 {
     // format the message header info into HTML display here
     ...
 } // end for
 ...
 // The request has been completed... now close the folder
 myJavaMailNugget.closeFolder( folder );
 ...
 

You should also note that JavaMailNugget will only return folders that have been opened successfully (if the folder can hold messages). In the standard JavaMail API, every time you want to access a folder, you need to check whether the folder actually exists, whether the folder can be opened and whether it is already opened. By opening the folder automatically, JavaMailNugget has handled all these error conditions for you.

On the other hand, the sending message does not have this restriction. The programmer should use the traditional JavaMail model by first creating an object that extends javax.mail.Message. Populate this message object and then simply tell JavaMailNugget to send it:

 JavaMailNugget nugget = user.getNugget();
 
 MimeMessage myMessage = nugget.createMessage();
 Address[] addr = new Address[1];

 // omitting code that populate the content of the message
 // and other header information

 // open the target "auto-save" folder first... to check if we
 // can actually connect to the IMAP server...
 Folder sentFolder = nugget.openFolderByName( "SENT" );
 
 // send message through the SMTP server
 nugget.sendMessage( myMessage, myaddresses );

 // now send is succsseful... save the message into SENT folder
 // on the IMAP server.
 Message[] msgs = new Messsage[1];
 msgs[0] = myMessage;
 folder.appendMessage( msgs );

 // remember to close it...
 nugget.closeFolder( folder );
 

If an email cannot be delivered to some of the addresses, a javax.mail.SendMailException will be thrown. This exception object contains all information for determining which addresses are invalid and which addresses have been sent successfully.

Performance Optimization The JavaMailNugget will try to keep an IMAP connection opened during its lifetime. This arrangement allow applications to fetch from different folders without the overhead of reestablishing connections. However, the application must ensure no more than one thread accessing the same instance of JavaMailNugget at the same time. This restriction is imposed by the programming model and implementation of JavaMail API.

JavaMailNugget Settings
The JavaMailNugget settings are specified in two different ways:

1. Dereferencing from the entity's user space - Any value that starts with the character '%' will be treated as the dereferencing the entity's user space. The reset of the string will be regarded as the user space key. For example, if you have the setting "mail.imap.host=%myHost", the JavaMailNugget will use the value fetched from the user space with the key "myHost"
2. Literal - Any value that does NOT start with the character '%' will be used as the actual value of the setting.

The compulsory settings of this nugget are:

Name	Constant	Type	Description
mail.imap.host	KEY_IMAP_HOST	String	The IMAP server to connect to (for reading email in your mail box).
mail.smtp.host	KEY_SMTP_HOST	String	The SMTP server to connect to (for sending out email).

The following are the optional settings required for IMAP (reading mail). Since we are using the standard JavaMail package for interacting with the mail server, the descriptions are quoted directly from the corresponding JavaDoc entries for the package com.sun.mail.imap:

Name	Constant	Type	Description
mail.imap.user	KEY_IMAP_USER	String	The user ID for the IMAP connection. If this configuration is not provided, the nugget will use the entity's ID as the IMAP user ID.
mail.imap.pwd	KEY_IMAP_PWD	String	The user password for the IMAP cnonection. If this configuration is not provided, the nugget will use the entity's identifying credential's "password" token as the IMAP user password.
mail.imap.port	KEY_IMAP_PORT	int	"The IMAP server port to connect to, if the connect() method doesn't explicitly specify one. Defaults to 143."
mail.imap.partialfetch	KEY_IMAP_PARTIALFETCH	boolean	"Controls whether the IMAP partial-fetch capability should be used. Defaults to true."
mail.imap.fetchsize	KEY_IMAP_FETCHSIZE	int	"Partial fetch size in bytes. Defaults to 16K."
mail.imap.connectiontimeout	KEY_IMAP_CONNECTIONTIMEOUT	int	"Socket connection timeout value in milliseconds. Default is infinite timeout."
mail.imap.timeout	KEY_IMAP_TIMEOUT	int	"Socket I/O timeout value in milliseconds. Default is infinite timeout."
mail.imap.statuscachetimeout	KEY_IMAP_STATUSCACHETIMEOUT	int	"Timeout value in milliseconds for cache of STATUS command response. Default is 1000 (1 second). Zero disables cache."
mail.imap.appendbuffersize	KEY_IMAP_APPENDBUFFERSIZE	int	"Maximum size of a message to buffer in memory when appending to an IMAP folder. If not set, or set to -1, there is no maximum and all messages are buffered. If set to 0, no messages are buffered. If set to (e.g.) 8192, messages of 8K bytes or less are buffered, larger messages are not buffered. Buffering saves cpu time at the expense of short term memory usage. If you commonly append very large messages to IMAP mailboxes you might want to set this to a moderate value (1M or less)."
mail.imap.connectionpoolsize	KEY_IMAP_CONNECTIONPOOLSIZE	int	"Maximum number of available connections in the connection pool. Default is 1."
mail.imap.connectionpooltimeout	KEY_IMAP_CONNECTIONPOOLTIMEOUT	int	"Timeout value in milliseconds for connection pool connections. Default is 45000 (45 seconds)."
mail.imap.separatestoreconnection	KEY_IMAP_SEPARATESTORECONNECTION	boolean	"Flag to indicate whether to use a dedicated store connection for store commands. Default is false."

The following are the optional settings required for SMTP (sending mail). Since we are using the standard JavaMail package for interacting with the mail server, the descriptions are quoted directly from the corresponding JavaDoc entries for the package com.sun.mail.smtp:

Name	Constant	Type	Description
mail.smtp.user	KEY_SMTP_USER	String	The user ID for the SMTP connection. If this configuration is not provided, the nugget will use the entity's ID as the SMTP user ID.
mail.smtp.pwd	KEY_SMTP_PWD	String	The user password for the SMTP cnonection. If this configuration is not provided, the nugget will use the entity's identifying credential's "password" token as the SMTP user password.
mail.smtp.port	KEY_SMTP_PORT	int	"The SMTP server port to connect to, if the connect() method doesn't explicitly specify one. Defaults to 25."
mail.smtp.from	KEY_SMTP_FROM	String	The default Email address to use for SMTP MAIL command. This sets the envelope return address. Developers should not need this settings at all.
mail.smtp.connectiontimeout	KEY_SMTP_CONNECTIONTIMEOUT	int	"Socket connection timeout value in milliseconds. Default is infinite timeout."
mail.smtp.timeout	KEY_SMTP_TIMEOUT	int	"Socket I/O timeout value in milliseconds. Default is infinite timeout."
mail.smtp.localhost	KEY_SMTP_LOCALHOST	String	"Local host name. Defaults to InetAddress.getLocalHost().getHostName(). Should not normally need to be set if your JDK and your name service are configured properly."
mail.smtp.ehlo	KEY_SMTP_EHLO	boolean	"If false, do not attempt to sign on with the EHLO command. Defaults to true. Normally failure of the EHLO command will fall back to the HELO command; this property exists only for servers that don't fail EHLO properly or don't implement EHLO properly."
mail.smtp.auth	KEY_SMTP_AUTH	boolean	"If true, attempt to authenticate the user using the AUTH command. Defaults to false."
mail.smtp.dsn.notify	KEY_SMTP_DSN_NOTIFY	String	"The NOTIFY option to the RCPT command. Either NEVER, or some combination of SUCCESS, FAILURE, and DELAY (separated by commas)."
mail.smtp.dsn.ret	KEY_SMTP_DSN_RET	String	"The RET option to the MAIL command. Either FULL or HDRS."
mail.smtp.allow8bitmime	KEY_SMTP_ALLOW8BITMIME	boolean	"If set to true, and the server supports the 8BITMIME extension, text parts of messages that use the "quoted-printable" or "base64" encodings are converted to use "8bit" encoding if they follow the RFC2045 rules for 8bit text."
mail.smtp.sendpartial	KEY_SMTP_SENDPARTIAL	boolean	"If set to true, and a message has some valid and some invalid addresses, send the message anyway, reporting the partial failure with a SendFailedException. If set to false (the default), the message is not sent to any of the recipients if there is an invalid recipient address."

See Also:

Serialized Form

Field Summary

static java.lang.String	KEY_CHECK_UID_VALIDITY Constant String for "check.uidvalidity".
static java.lang.String	KEY_IMAP_APPENDBUFFERSIZE Constant String for "mail.imap.appendbuffersize".
static java.lang.String	KEY_IMAP_CONNECTION_DEBUG Constant String for "mail.imap.connectionpool.debug".
static java.lang.String	KEY_IMAP_CONNECTIONPOOLSIZE Constant String for "mail.imap.connectionpoolsize".
static java.lang.String	KEY_IMAP_CONNECTIONPOOLTIMEOUT Constant String for "mail.imap.connectionpooltimeout".
static java.lang.String	KEY_IMAP_CONNECTIONTIMEOUT Constant String for "mail.imap.connectiontimeout".
static java.lang.String	KEY_IMAP_FETCHSIZE Constant String for "mail.imap.fetchsize".
static java.lang.String	KEY_IMAP_HOST Constant String for "mail.imap.host".
static java.lang.String	KEY_IMAP_PARTIALFETCH Constant String for "mail.imap.partialfetch".
static java.lang.String	KEY_IMAP_PORT Constant String for "mail.imap.port".
protected static java.lang.String	KEY_IMAP_PWD
static java.lang.String	KEY_IMAP_SEPARATESTORECONNECTION Constant String for "mail.imap.separatestoreconnection".
static java.lang.String	KEY_IMAP_STATUSCACHETIMEOUT Constant String for "mail.imap.statuscachetimeout".
static java.lang.String	KEY_IMAP_TIMEOUT Constant String for "mail.imap.timeout".
protected static java.lang.String	KEY_IMAP_USER
static java.lang.String	KEY_JAVAMAIL_DEBUG Constant String for "mail.debug".
static java.lang.String	KEY_SMTP_ALLOW8BITMIME Constant String for "mail.smtp.allow8bitmime".
static java.lang.String	KEY_SMTP_AUTH Constant String for "mail.smtp.auth".
static java.lang.String	KEY_SMTP_CONNECTIONTIMEOUT Constant String for "mail.smtp.connectiontimeout".
static java.lang.String	KEY_SMTP_DSN_NOTIFY Constant String for "mail.smtp.dsn.notify".
static java.lang.String	KEY_SMTP_DSN_RET Constant String for "mail.smtp.dsn.ret".
static java.lang.String	KEY_SMTP_EHLO Constant String for "mail.smtp.ehlo".
static java.lang.String	KEY_SMTP_FROM Constant String for "mail.smtp.from".
static java.lang.String	KEY_SMTP_HOST Constant String for "mail.smtp.host".
static java.lang.String	KEY_SMTP_LOCALHOST Constant String for "mail.smtp.localhost".
static java.lang.String	KEY_SMTP_PORT Constant String for "mail.smtp.port".
protected static java.lang.String	KEY_SMTP_PWD
static java.lang.String	KEY_SMTP_SENDPARTIAL Constant String for "mail.smtp.sendpartial".
static java.lang.String	KEY_SMTP_TIMEOUT Constant String for "mail.smtp.timoeut".
protected static java.lang.String	KEY_SMTP_USER
protected static java.lang.String	KEY_STORE_PROTOCOL
protected static java.lang.String	KEY_TRANSPORT_PROTOCOL
static java.lang.String	NAME_DRAFTS Constant String of "Drafts" (one of the default folder name).
static java.lang.String	NAME_INBOX Constant String of "Inbox" (one of the default folder name).
static java.lang.String	NAME_SENT Constant String of "Sent" (one of the default folder name).
static java.lang.String	NAME_TRASH Constant String of "Trash" (one of the default folder name).

Fields inherited from class com.nitido.nim.Nugget

_entity, _nim, _nuggetName, _settings

Fields inherited from interface com.nitido.nim.CredentialConstants

CRED_ADMIN, CRED_CONTAINER, CRED_HELPDESK, CRED_SYSTEM, CRED_USER, KEY_PASSWORD

Constructor Summary

protected

JavaMailNugget(NuggetVisa visa) Default constructor.

Method Summary

abstract void	checkUIDValidity(javax.mail.Folder folder, long orgUIDValidity) This method will throw an InvalidUIDException if the folder's current UIDValidity value is not the same as the original value.
abstract void	closeFolder(javax.mail.Folder folder, boolean expunge) Close the specified folder.
abstract void	closeFolderQuietly(javax.mail.Folder folder, boolean expunge) Close the specified folder quietly.
abstract void	connectIMAP() Notify the nugget that IMAP operations will start.
abstract javax.mail.Folder	createFolder(java.lang.String folderName, int type, boolean isOpenedFolder) Create a new folder by specifying the full name of the folder.
javax.mail.Folder	createFolderByName(java.lang.String folderName, int type) Deprecated.
abstract javax.mail.internet.MimeMessage	createMessage() This method creates an empty MimeMessage for the user to populate and save/send.
abstract void	disconnectIMAP() Force a disconnection from the IMAP server.
abstract void	disconnectIMAPQuietly() Force a disconnection from the IMAP server.
abstract javax.mail.Folder	getDefaultFolder() Get the folder that represents the 'root' of the mailbox.
abstract javax.mail.Folder	getFolderByName(java.lang.String folderName) Get the folder with the specified folder name.
abstract Usage	getMailBoxUsage() Get mail box usage information.
abstract javax.mail.Message	getMessageByUID(javax.mail.Folder folder, long orgUIDValidity, long uid) Get the message by UID.
abstract javax.mail.Message[]	getMessagesByUIDRange(javax.mail.Folder folder, long orgUIDValidity, long start, long end) Get messages by UIDs
abstract javax.mail.Message[]	getMessagesByUIDs(javax.mail.Folder folder, long orgUIDValidity, long[] uids) Get messages by UIDs
abstract java.lang.String[]	getPersonalNamespaces() Deprecated.
abstract java.lang.String[]	getSharedNamespaces() Deprecated.
abstract java.lang.String[]	getSystemFolders() This method reports a list of folders that are system folders.
abstract long	getUIDNext(javax.mail.Folder folder) Get the UIDNext number of the folder.
abstract long	getUIDofMessage(javax.mail.Folder folder, javax.mail.Message msg) Get the UID of the message.
abstract long[]	getUIDofMessages(javax.mail.Folder folder, javax.mail.Message[] msgs) Get the UIDs of the messages.
abstract long	getUIDValidity(javax.mail.Folder folder) Get the UIDValidity number of the folder.
abstract boolean	isCachable() This method indicates whether the Nugget implementation is a cachable nugget.
abstract javax.mail.Folder	openDefaultFolder() Open the folder that represents the 'root' of the mailbox.
abstract javax.mail.Folder	openFolderByName(java.lang.String folderName) Open the folder with the specified folder name.
abstract void	sendMessage(javax.mail.Message msg, javax.mail.Address[] addr) Send the message to the address.

Methods inherited from class com.nitido.nim.Nugget

activate, deactivate, destroy, destroyImpl, getDescriptor, getEntity, getNuggetName, getSetting, getSettings, init, initImpl, requestBegin, requestEnd

Methods inherited from class java.lang.Object

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

Field Detail

KEY_IMAP_HOST

public static final java.lang.String KEY_IMAP_HOST

Constant String for "mail.imap.host".

See Also:

Constant Field Values

KEY_SMTP_HOST

public static final java.lang.String KEY_SMTP_HOST

Constant String for "mail.smtp.host".

See Also:

Constant Field Values

KEY_SMTP_FROM

public static final java.lang.String KEY_SMTP_FROM

Constant String for "mail.smtp.from".

See Also:

Constant Field Values

KEY_IMAP_PORT

public static final java.lang.String KEY_IMAP_PORT

Constant String for "mail.imap.port".

See Also:

Constant Field Values

KEY_IMAP_PARTIALFETCH

public static final java.lang.String KEY_IMAP_PARTIALFETCH

Constant String for "mail.imap.partialfetch".

See Also:

Constant Field Values

KEY_IMAP_FETCHSIZE

public static final java.lang.String KEY_IMAP_FETCHSIZE

Constant String for "mail.imap.fetchsize".

See Also:

Constant Field Values

KEY_IMAP_CONNECTIONTIMEOUT

public static final java.lang.String KEY_IMAP_CONNECTIONTIMEOUT

Constant String for "mail.imap.connectiontimeout".

See Also:

Constant Field Values

KEY_IMAP_TIMEOUT

public static final java.lang.String KEY_IMAP_TIMEOUT

Constant String for "mail.imap.timeout".

See Also:

Constant Field Values

KEY_IMAP_STATUSCACHETIMEOUT

public static final java.lang.String KEY_IMAP_STATUSCACHETIMEOUT

Constant String for "mail.imap.statuscachetimeout".

See Also:

Constant Field Values

KEY_IMAP_APPENDBUFFERSIZE

public static final java.lang.String KEY_IMAP_APPENDBUFFERSIZE

Constant String for "mail.imap.appendbuffersize".

See Also:

Constant Field Values

KEY_IMAP_CONNECTIONPOOLSIZE

public static final java.lang.String KEY_IMAP_CONNECTIONPOOLSIZE

Constant String for "mail.imap.connectionpoolsize".

See Also:

Constant Field Values

KEY_IMAP_CONNECTIONPOOLTIMEOUT

public static final java.lang.String KEY_IMAP_CONNECTIONPOOLTIMEOUT

Constant String for "mail.imap.connectionpooltimeout".

See Also:

Constant Field Values

KEY_IMAP_SEPARATESTORECONNECTION

public static final java.lang.String KEY_IMAP_SEPARATESTORECONNECTION

Constant String for "mail.imap.separatestoreconnection".

See Also:

Constant Field Values

KEY_IMAP_CONNECTION_DEBUG

public static final java.lang.String KEY_IMAP_CONNECTION_DEBUG

Constant String for "mail.imap.connectionpool.debug".

See Also:

Constant Field Values

KEY_SMTP_PORT

public static final java.lang.String KEY_SMTP_PORT

Constant String for "mail.smtp.port".

See Also:

Constant Field Values

KEY_SMTP_CONNECTIONTIMEOUT

public static final java.lang.String KEY_SMTP_CONNECTIONTIMEOUT

Constant String for "mail.smtp.connectiontimeout".

See Also:

Constant Field Values

KEY_SMTP_TIMEOUT

public static final java.lang.String KEY_SMTP_TIMEOUT

Constant String for "mail.smtp.timoeut".

See Also:

Constant Field Values

KEY_SMTP_LOCALHOST

public static final java.lang.String KEY_SMTP_LOCALHOST

Constant String for "mail.smtp.localhost".

See Also:

Constant Field Values

KEY_SMTP_EHLO

public static final java.lang.String KEY_SMTP_EHLO

Constant String for "mail.smtp.ehlo".

See Also:

Constant Field Values

KEY_SMTP_AUTH

public static final java.lang.String KEY_SMTP_AUTH

Constant String for "mail.smtp.auth".

See Also:

Constant Field Values

KEY_SMTP_DSN_NOTIFY

public static final java.lang.String KEY_SMTP_DSN_NOTIFY

Constant String for "mail.smtp.dsn.notify".

See Also:

Constant Field Values

KEY_SMTP_DSN_RET

public static final java.lang.String KEY_SMTP_DSN_RET

Constant String for "mail.smtp.dsn.ret".

See Also:

Constant Field Values

KEY_SMTP_ALLOW8BITMIME

public static final java.lang.String KEY_SMTP_ALLOW8BITMIME

Constant String for "mail.smtp.allow8bitmime".

See Also:

Constant Field Values

KEY_SMTP_SENDPARTIAL

public static final java.lang.String KEY_SMTP_SENDPARTIAL

Constant String for "mail.smtp.sendpartial".

See Also:

Constant Field Values

KEY_JAVAMAIL_DEBUG

public static final java.lang.String KEY_JAVAMAIL_DEBUG

Constant String for "mail.debug".

See Also:

Constant Field Values

KEY_CHECK_UID_VALIDITY

public static final java.lang.String KEY_CHECK_UID_VALIDITY

Constant String for "check.uidvalidity".

See Also:

Constant Field Values

KEY_IMAP_USER

protected static final java.lang.String KEY_IMAP_USER

See Also:

Constant Field Values

KEY_IMAP_PWD

protected static final java.lang.String KEY_IMAP_PWD

See Also:

Constant Field Values

KEY_SMTP_USER

protected static final java.lang.String KEY_SMTP_USER

See Also:

Constant Field Values

KEY_SMTP_PWD

protected static final java.lang.String KEY_SMTP_PWD

See Also:

Constant Field Values

KEY_STORE_PROTOCOL

protected static final java.lang.String KEY_STORE_PROTOCOL

See Also:

Constant Field Values

KEY_TRANSPORT_PROTOCOL

protected static final java.lang.String KEY_TRANSPORT_PROTOCOL

See Also:

Constant Field Values

NAME_INBOX

public static final java.lang.String NAME_INBOX

Constant String of "Inbox" (one of the default folder name).

See Also:

Constant Field Values

NAME_DRAFTS

public static final java.lang.String NAME_DRAFTS

Constant String of "Drafts" (one of the default folder name).

See Also:

Constant Field Values

NAME_SENT

public static final java.lang.String NAME_SENT

Constant String of "Sent" (one of the default folder name).

See Also:

Constant Field Values

NAME_TRASH

public static final java.lang.String NAME_TRASH

Constant String of "Trash" (one of the default folder name).

See Also:

Constant Field Values

Constructor Detail

JavaMailNugget

protected JavaMailNugget(NuggetVisa visa)

Default constructor.

Method Detail

openDefaultFolder

public abstract javax.mail.Folder openDefaultFolder()
                                             throws javax.mail.FolderNotFoundException,
                                                    javax.mail.MessagingException,
                                                    JavaMailNuggetException

Open the folder that represents the 'root' of the mailbox. If the folder can contain messages, this method will automatically open the folder. Otherwise, this method will return the unopened Folder object as it may contain other folders.

Returns:

an opened Folder object for the requested folder.

Throws:

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

getDefaultFolder

public abstract javax.mail.Folder getDefaultFolder()
                                            throws javax.mail.FolderNotFoundException,
                                                   javax.mail.MessagingException,
                                                   JavaMailNuggetException

Get the folder that represents the 'root' of the mailbox. NOTE: the returned Folder object is not "opened". You cannot obtain the messages inside it. You should call openDefaultFolder() if you want to access an opened folder.

Returns:

an opened Folder object for the requested folder.

Throws:

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

openFolderByName

public abstract javax.mail.Folder openFolderByName(java.lang.String folderName)
                                            throws javax.mail.FolderNotFoundException,
                                                   javax.mail.MessagingException,
                                                   JavaMailNuggetException

Open the folder with the specified folder name. If the folder can contain messages, this method will automatically open the folder.

Parameters:

folderName - The folder name can be a full folder name or short name (with path relative to the default 'root' folder for the user).

Returns:

an opened Folder object for the requested folder.

Throws:

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

getFolderByName

public abstract javax.mail.Folder getFolderByName(java.lang.String folderName)
                                           throws javax.mail.FolderNotFoundException,
                                                  javax.mail.MessagingException,
                                                  JavaMailNuggetException

Get the folder with the specified folder name. This folder will return a closed folder.

Parameters:

folderName - The folder name can be a full folder name or short name (with path relative to the default 'root' folder for the user).

Returns:

a closed Folder object for the requested folder.

Throws:

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

createFolderByName

public final javax.mail.Folder createFolderByName(java.lang.String folderName,
                                                  int type)
                                           throws javax.mail.MessagingException,
                                                  JavaMailNuggetException

Deprecated.

Create a new folder by specifying the full name of the folder. Any non-existing folders along its path will be also created.

If the creation is successful, a Folder object of the new folder will be returned. This Folder object will be opened automatically if its type integer has set Folder.HOLDS_MESSAGES bit.

This method is deprecated by NiM 2.4. If you still want your folder to be automatically opened, you should call createFolder( folderName, type, true ).

This method is deprecated because most applications do not want to validate if the new folder can be opened successfully (in order to improve the performance). Moreover, we noticed that inexperience JavaMailNugget developers usually forget about closing the new Folder Object. This can create connection leaks that are difficult to debug.

Parameters:

folderName - the name of the new folder (this includes the full path)

type - The type of the folders. It is a bit-field stored as integer. The valid fields are Folder.HOLDS_FOLDERS and Folder.HOLDS_MESSAGES. If a folder can hold both folders and messages, the value would be ( Folder.HOLDS_FOLDERS | Folder.HOLDS_MESSAGES ) - i.e. bitwise OR of the values.
For more details, please refer to the JavaDoc for the class javax.mail.Folder (Belongs to JavaMail 1.2 API).

Returns:

A Folder object for the requested folder. This Folder object will be opened if it can contain messages.

Throws:

javax.mail.MessagingException

JavaMailNuggetException

createFolder

public abstract javax.mail.Folder createFolder(java.lang.String folderName,
                                               int type,
                                               boolean isOpenedFolder)
                                        throws javax.mail.MessagingException,
                                               JavaMailNuggetException

Create a new folder by specifying the full name of the folder. Any non-existing folders along its path will be also created.

If the creation is successful, a Folder object of the new folder will be returned. This Folder object will be opened if the type parameter has set the Folder.HOLDS_MESSAGES bit, AND, the isOpenedFolder parameter is "true". Otherwise, the returning Folder object will remain closed.

This method is introduced in NiM 2.4 to replace the original "Folder createFolderByName( String folderName, int type )" method.

Parameters:

folderName - the name of the new folder (this includes the full path)

type - The type of the folders. It is a bit-field stored as integer. The valid fields are Folder.HOLDS_FOLDERS and Folder.HOLDS_MESSAGES. If a folder can hold both folders and messages, the value would be ( Folder.HOLDS_FOLDERS | Folder.HOLDS_MESSAGES ) - i.e. bitwise OR of the values.
For more details, please refer to the JavaDoc for the class javax.mail.Folder (Belongs to JavaMail 1.2 API).

Returns:

A Folder object for the requested folder. This Folder object will be opened if it can contain messages.

Throws:

javax.mail.MessagingException

JavaMailNuggetException

getPersonalNamespaces

public abstract java.lang.String[] getPersonalNamespaces()
                                                  throws javax.mail.MessagingException,
                                                         JavaMailNuggetException

Deprecated.

Retrieve the set of folders that represents the personal name spaces.

This method is deprecated because future versions of JavaMail will not support this type of methods. JavaMail 1.2 is the last version that supports it.

Returns:

an array of full folder name for those matched folders.

Throws:

javax.mail.MessagingException

JavaMailNuggetException

getSharedNamespaces

public abstract java.lang.String[] getSharedNamespaces()
                                                throws javax.mail.MessagingException,
                                                       JavaMailNuggetException

Deprecated.

Retrieve the set of folders that represents the shared name spaces. This method is deprecated because future versions of JavaMail will not support this type of methods. JavaMail 1.2 is the last version that supports it.

Returns:

an array of full folder name for those matched folders.

Throws:

javax.mail.MessagingException

JavaMailNuggetException

closeFolder

public abstract void closeFolder(javax.mail.Folder folder,
                                 boolean expunge)
                          throws javax.mail.MessagingException,
                                 JavaMailNuggetException

Close the specified folder. If the folder has already been closed, nothing will happen.

Parameters:

folder - the Folder object of the folder to be closed.

expunge - Determine how the IMAP server treats "deleted" messages upon closing the folder. If the parameter is set to true, the server will permanently remove all the messages with flag marked as DELETED. Otherwise, the server will just leave those messages on the system.

Throws:

JavaMailNuggetException - if the folder object is null

javax.mail.MessagingException - if error has occurred when connecting the IMAP server and/or when executing the command.

closeFolderQuietly

public abstract void closeFolderQuietly(javax.mail.Folder folder,
                                        boolean expunge)

Close the specified folder quietly. This method basically do the same thing as closeFolder, except that it will never throw any exceptions.

Parameters:

folder - the Folder object of the folder to be closed.

expunge - Determine how the IMAP server treats "deleted" messages upon closing the folder. If the parameter is set to true, the server will permanently remove all the messages with flag marked as DELETED. Otherwise, the server will just leave those messages on the system.

getSystemFolders

public abstract java.lang.String[] getSystemFolders()
                                             throws javax.mail.MessagingException,
                                                    JavaMailNuggetException

This method reports a list of folders that are system folders. These are folders such as Inbox that may have special needs within a project.

Returns:

An array of String objects containing the name of each system folder.

Throws:

javax.mail.MessagingException

JavaMailNuggetException

getUIDValidity

public abstract long getUIDValidity(javax.mail.Folder folder)
                             throws javax.mail.FolderNotFoundException,
                                    javax.mail.MessagingException,
                                    JavaMailNuggetException

Get the UIDValidity number of the folder. This number is required if you want to refer any messages with UID in the future. According to the IMAP v4 protocol (RFC 2445), this number will be increased if the server has changed the UID of messages stored under the folder.

Parameters:

folder - The folder to fetch the UIDValidity number from

Returns:

The UIDValidity number of the folder.

Throws:

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

getUIDNext

public abstract long getUIDNext(javax.mail.Folder folder)
                         throws javax.mail.FolderNotFoundException,
                                javax.mail.MessagingException,
                                JavaMailNuggetException

Get the UIDNext number of the folder. This number is required if you want to refer any messages with UID in the future.

Parameters:

folder - The folder to fetch the UIDNext number from.

Returns:

The UIDNext number of the folder.

Throws:

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

getUIDofMessage

public abstract long getUIDofMessage(javax.mail.Folder folder,
                                     javax.mail.Message msg)
                              throws javax.mail.FolderNotFoundException,
                                     javax.mail.MessagingException,
                                     MessageNotInFolderException,
                                     JavaMailNuggetException

Get the UID of the message. The messages must be stored under the specified folder.

Throws:

MessageNotInFolderException - If the message is not stored under the specified folder.

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

getUIDofMessages

public abstract long[] getUIDofMessages(javax.mail.Folder folder,
                                        javax.mail.Message[] msgs)
                                 throws javax.mail.FolderNotFoundException,
                                        javax.mail.MessagingException,
                                        MessageNotInFolderException,
                                        JavaMailNuggetException

Get the UIDs of the messages. All the messages must be stored under the specified folder.

Throws:

MessageNotInFolderException - If at least one of the message is not stored under the specified folder.

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

getMessageByUID

public abstract javax.mail.Message getMessageByUID(javax.mail.Folder folder,
                                                   long orgUIDValidity,
                                                   long uid)
                                            throws javax.mail.FolderNotFoundException,
                                                   javax.mail.MessagingException,
                                                   InvalidUIDException,
                                                   JavaMailNuggetException

Get the message by UID.

Parameters:

folder - The folder to get the message from.

orgUIDValidity - The original UIDValidity number that the folder returns when you fetch the message UID. This number is used to determine whether the server has altered the UIDs between your request.

uid - The uid of the message you want to fetch.

Returns:

A javax.mail.Message object

Throws:

InvalidUIDException - If the server has changed the UID between your requests.

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

getMessagesByUIDs

public abstract javax.mail.Message[] getMessagesByUIDs(javax.mail.Folder folder,
                                                       long orgUIDValidity,
                                                       long[] uids)
                                                throws javax.mail.FolderNotFoundException,
                                                       javax.mail.MessagingException,
                                                       InvalidUIDException,
                                                       JavaMailNuggetException

Get messages by UIDs

Parameters:

folder - The folder to get the message from.

orgUIDValidity - The original UIDValidity number that the folder returns when you fetch the message UID. This number is used to determine whether the server has altered the UIDs between your request.

uids - An array of uid of the messages you want to fetch.

Returns:

An array of javax.mail.Message objects

Throws:

InvalidUIDException - If the server has changed the UID between your requests.

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

getMessagesByUIDRange

public abstract javax.mail.Message[] getMessagesByUIDRange(javax.mail.Folder folder,
                                                           long orgUIDValidity,
                                                           long start,
                                                           long end)
                                                    throws javax.mail.FolderNotFoundException,
                                                           javax.mail.MessagingException,
                                                           InvalidUIDException,
                                                           JavaMailNuggetException

Get messages by UIDs

Parameters:

folder - The folder to get the message from.

orgUIDValidity - The original UIDValidity number that the folder returns when you fetch the message UID. This number is used to determine whether the server has altered the UIDs between your request.

start - The smallest UID of the message to fetch.

end - The largest UID index of the message to fetch.

Returns:

An array of javax.mail.Message objects

Throws:

InvalidUIDException - If the server has changed the UID between your requests.

javax.mail.FolderNotFoundException

javax.mail.MessagingException

JavaMailNuggetException

getMailBoxUsage

public abstract Usage getMailBoxUsage()
                               throws javax.mail.MessagingException,
                                      JavaMailNuggetException

Get mail box usage information.

Returns:

a Usage object that contains both the quota and the space that has been used. If the user account has no quota associated to its root folder or INBOX folder, a null object will be returned.

Throws:

javax.mail.MessagingException

JavaMailNuggetException

createMessage

public abstract javax.mail.internet.MimeMessage createMessage()

This method creates an empty MimeMessage for the user to populate and save/send. ALL user-composed messages must be created through this method, no matter whether those messages will be sent right away or stored into the draft folder.

Its headers field is set to an empty InternetHeaders object. The flags field is set to an empty Flags object. The modified flag is set to true.

In other words, this method would not restrict the caller on the setting of the message. The caller can set these header information in anyway that is suitable for the nature of the message.

This method does not require the caller to have any folder opened,.

sendMessage

public abstract void sendMessage(javax.mail.Message msg,
                                 javax.mail.Address[] addr)
                          throws javax.mail.SendFailedException,
                                 javax.mail.MessagingException,
                                 JavaMailNuggetException

Send the message to the address. This method will perform a msg.saveChange() before sending out the message.

Parameters:

msg - the message to be sent.

addr - an array of Address objects that are going to be sent. If this parameter is null, it will use the addresses from msg.getAllRecipients() instead.

Throws:

javax.mail.SendFailedException

javax.mail.MessagingException

JavaMailNuggetException

connectIMAP

public abstract void connectIMAP()
                          throws JavaMailNuggetException

Notify the nugget that IMAP operations will start.

Throws:

JavaMailNuggetException

disconnectIMAP

public abstract void disconnectIMAP()
                             throws ActivationException

Force a disconnection from the IMAP server. Once this method is call, the connection to the IMAP server will be dropped, no matter how many folders are still opened.

Throws:

ActivationException - if network error occurs or problems with disconnection.

disconnectIMAPQuietly

public abstract void disconnectIMAPQuietly()

Force a disconnection from the IMAP server. Once this method is call, the connection to the IMAP server will be dropped, no matter how many folders are still opened.

If the connection has been dropped already or IO/IMAP problem occured, this method will not do anything (i.e. no exception).

isCachable

public abstract boolean isCachable()

This method indicates whether the Nugget implementation is a cachable nugget. A cachable nugget will be instantiate only once during the lifetime of the associated Entity. The nugget instance will be reused for future requests. On the other hand, a non-cachable nugget will be instantiated every time that the getNugget() method is invoked. A Nugget implementation can be cachable only if every method is thread safe and atomic. Namely, if there are multiple threads access it at the same time, they will not interfere each other.

Specified by:

isCachable in class Nugget

Returns:

true if the Nugget implementation is cachable, false otherwise.

checkUIDValidity

public abstract void checkUIDValidity(javax.mail.Folder folder,
                                      long orgUIDValidity)
                               throws InvalidUIDException,
                                      javax.mail.MessagingException

This method will throw an InvalidUIDException if the folder's current UIDValidity value is not the same as the original value.

Parameters:

folder - The folder object must be an UIDFolder instance and should be already opened.

orgUIDValidity - The original UIDValidity value. If it is a negative number, no check will be performed.

Throws:

InvalidUIDException

javax.mail.MessagingException