com.openexchange.mail.api
Class MailAccess<F extends IMailFolderStorage,M extends IMailMessageStorage>

java.lang.Object
  com.openexchange.mail.api.MailAccess<F,M>

All Implemented Interfaces:

java.io.Serializable

public abstract class MailAccess<F extends IMailFolderStorage,M extends IMailMessageStorage>
extends java.lang.Object
implements java.io.Serializable

MailAccess - Handles connecting to the mailing system while using an internal cache for connected access objects (see MailAccessCache).

Moreover it provides access to either message storage, folder storage and logic tools.

Author:

Thorben Betten

See Also:

Serialized Form

Method Summary

void	addWarnings(java.util.Collection<MailException> warnings) Adds given warnings.
void	close(boolean put2Cache) Closes this access.
void	connect() Opens this access.
void	connect(boolean checkDefaultFolders) Opens this access.
boolean	delegateCheckMailServerPort() For delegating purpose.
void	delegateCloseInternal() For delegating purpose.
void	delegateConnectInternal() For delegating purpose.
MailConfig	delegateCreateNewMailConfig() For delegating purpose.
IMailProperties	delegateCreateNewMailProperties() For delegating purpose.
void	delegateReleaseResources() For delegating purpose.
int	getAccountId() Gets this mail access' account ID.
int	getCacheIdleSeconds() Gets the number of seconds this mail access is allowed to remain idle in cache before being removed and closed.
static int	getCounter()
abstract F	getFolderStorage() Gets the appropriate IMailFolderStorage implementation that is considered as the main entry point to a user's mailbox.
static MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage>	getInstance(int userId, int contextId) Gets the proper instance of MailAccess for specified user's default account.
static MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage>	getInstance(int userId, int contextId, int accountId) Gets the proper instance of MailAccess for specified user and account ID.
static MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage>	getInstance(com.openexchange.session.Session session) Gets the proper instance of MailAccess for session user's default mail account.
static MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage>	getInstance(com.openexchange.session.Session session, int accountId) Gets the proper instance of MailAccess parameterized with given session and account ID.
abstract MailLogicTools	getLogicTools() Gets the appropriate MailLogicTools implementation that provides operations/methods to create a reply/forward message from a referenced message.
MailConfig	getMailConfig() Returns the mail configuration appropriate for current user.
java.util.Properties	getMailProperties() Gets the optional properties used on connect.
abstract M	getMessageStorage() Gets the appropriate IMailMessageStorage implementation that provides necessary message-related operations/methods.
MailFolder	getRootFolder() Convenience method to obtain root folder in a fast way; meaning no default folder check is performed which is not necessary to return the root folder.
java.lang.String	getTrace() Gets the trace of the thread that lastly obtained this access.
int	getUnreadMessagesCount(java.lang.String fullname) Convenience method to obtain folder's number of unread messages in a fast way; meaning no default folder check is performed.
java.util.Collection<MailException>	getWarnings() Gets possible warnings.
boolean	isCacheable() Indicates if this mail access is cacheable.
abstract boolean	isConnected() Checks if this connection is currently connected.
abstract boolean	isConnectedUnsafe() Checks if this connection is currently connected in an unsafe, but faster manner than isConnected().
boolean	ping() Pings the mail server to check if a connection can be established and and immediately closes connection.
void	setCacheable(boolean cacheable) Sets whether this mail access is cacheable or not.
void	setMailProperties(java.util.Properties mailProperties) Sets optional properties used on connect.

Methods inherited from class java.lang.Object

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

Method Detail

addWarnings

public void addWarnings(java.util.Collection<MailException> warnings)

Adds given warnings.

Parameters:

warnings - The warnings to add

getWarnings

public java.util.Collection<MailException> getWarnings()

Gets possible warnings.

Returns:

Possible warnings.

getInstance

public static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> getInstance(com.openexchange.session.Session session)
                                                                                                throws MailException

Gets the proper instance of MailAccess for session user's default mail account.

When starting to work with obtained mail access at first its connect() method is supposed to be invoked. On finished work the final close(boolean) must be called:

 final MailAccess mailAccess = MailAccess.getInstance(session);
 mailAccess.connect();
 try {
  // Do something
 } finally {
  mailAccess.close(putToCache)
 }
 

Parameters:

session - The session

Returns:

A proper instance of MailAccess

Throws:

MailException - If instantiation fails or a caching error occurs

getInstance

public static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> getInstance(com.openexchange.session.Session session,
                                                                                                       int accountId)
                                                                                                throws MailException

Gets the proper instance of MailAccess parameterized with given session and account ID.

When starting to work with obtained mail access at first its connect() method is supposed to be invoked. On finished work the final close(boolean) must be called:

 final MailAccess mailAccess = MailAccess.getInstance(session, accountID);
 mailAccess.connect();
 try {
        // Do something
 } finally {
        mailAccess.close(putToCache)
 }
 

Parameters:

session - The session

accountId - The account ID

Returns:

A proper instance of MailAccess

Throws:

MailException - If instantiation fails or a caching error occurs

getInstance

public static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> getInstance(int userId,
                                                                                                       int contextId)
                                                                                                throws MailException

Gets the proper instance of MailAccess for specified user's default account.

When starting to work with obtained mail access at first its connect() method is supposed to be invoked. On finished work the final close(boolean) must be called:

 final MailAccess mailAccess = MailAccess.getInstance(session, accountID);
 mailAccess.connect();
 try {
  // Do something
 } finally {
  mailAccess.close(putToCache)
 }
 

Parameters:

userId - The user identifier

contextId - The context identifier

Returns:

An appropriate mail access

Throws:

MailException - If instantiation fails or a caching error occurs

getInstance

public static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> getInstance(int userId,
                                                                                                       int contextId,
                                                                                                       int accountId)
                                                                                                throws MailException

Gets the proper instance of MailAccess for specified user and account ID.

When starting to work with obtained mail access at first its connect() method is supposed to be invoked. On finished work the final close(boolean) must be called:

 final MailAccess mailAccess = MailAccess.getInstance(session, accountID);
 mailAccess.connect();
 try {
  // Do something
 } finally {
  mailAccess.close(putToCache)
 }
 

Parameters:

userId - The user identifier

contextId - The context identifier

accountId - The account identifier

Returns:

An appropriate mail access

Throws:

MailException - If instantiation fails or a caching error occurs

getCounter

public static final int getCounter()

Returns:

the global access counter

getMailProperties

public java.util.Properties getMailProperties()

Gets the optional properties used on connect.

Returns:

the mailProperties

setMailProperties

public void setMailProperties(java.util.Properties mailProperties)

Sets optional properties used on connect. Herewith additional properties can be applied and checked later on.

Parameters:

mailProperties - The properties

ping

public boolean ping()
             throws MailException

Pings the mail server to check if a connection can be established and and immediately closes connection.

Default implementation just delegates to connect() but may be overridden in implementing subclass if not appropriate or a faster way can be achieved.

Returns:

true if a connection can be established; otherwise false

Throws:

MailException - If the ping fails

connect

public final void connect()
                   throws MailException

Opens this access. May be invoked on an already opened access.

Throws:

MailException - If the connection could not be established for various reasons

connect

public final void connect(boolean checkDefaultFolders)
                   throws MailException

Opens this access. May be invoked on an already opened access.

Parameters:

checkDefaultFolders - true to check existence of default folders; otherwise false to omit check

Throws:

MailException - If the connection could not be established for various reasons

getRootFolder

public MailFolder getRootFolder()
                         throws MailException

Convenience method to obtain root folder in a fast way; meaning no default folder check is performed which is not necessary to return the root folder.

The same result is yielded through calling getFolderStorage().getRootFolder() on a connected MailAccess.

Since this mail access instance is connected if not already done before, the close(boolean) operation should be invoked afterwards:

 final MailAccess mailAccess = MailAccess.getInstance(session);
 final MailFolder rootFolder = mailAccess.getRootFolder();
 try {
  // Do something with root folder
 } finally {
  mailAccess.close(putToCache)
 }
 

Throws:

MailException - If returning the root folder fails

getUnreadMessagesCount

public int getUnreadMessagesCount(java.lang.String fullname)
                           throws MailException

Convenience method to obtain folder's number of unread messages in a fast way; meaning no default folder check is performed.

The same result is yielded through calling getFolderStorage().getFolder().getUnreadMessageCount() on a connected MailAccess.

Since this mail access instance is connected if not already done before, the close(boolean) operation should be invoked afterwards:

 final MailAccess mailAccess = MailAccess.getInstance(session);
 final int unreadCount = mailAccess.getNumberOfUnreadMessages();
 try {
  // Do something with unread count
 } finally {
  mailAccess.close(putToCache)
 }
 

Throws:

MailException - If returning the unread count fails

delegateConnectInternal

public void delegateConnectInternal()
                             throws MailException

For delegating purpose. Don't invoke.

Throws:

MailException

close

public final void close(boolean put2Cache)

Closes this access.

An already closed access is not going to be put into cache and is treated as a no-op.

Parameters:

put2Cache - true to try to put this mail connection into cache; otherwise false

getTrace

public final java.lang.String getTrace()

Gets the trace of the thread that lastly obtained this access.

This is useful to detect certain threads which uses an access for a long time

Returns:

the trace of the thread that lastly obtained this access

getMailConfig

public MailConfig getMailConfig()
                         throws MailException

Returns the mail configuration appropriate for current user. It provides needed connection and login information.

Returns:

The mail configuration

Throws:

MailException

getAccountId

public int getAccountId()

Gets this mail access' account ID.

Returns:

The account ID

getCacheIdleSeconds

public int getCacheIdleSeconds()

Gets the number of seconds this mail access is allowed to remain idle in cache before being removed and closed. If the default value shall be used for this mail access, return -1.

Returns:

The number of allowed idle seconds or -1 to signal using default value.

isCacheable

public boolean isCacheable()

Indicates if this mail access is cacheable.

Returns:

true if this mail access is cacheable; otherwise false

setCacheable

public void setCacheable(boolean cacheable)

Sets whether this mail access is cacheable or not.

Parameters:

cacheable - true if this mail access is cacheable; otherwise false

delegateCreateNewMailConfig

public MailConfig delegateCreateNewMailConfig()

For delegating purpose. Don't invoke.

delegateCreateNewMailProperties

public IMailProperties delegateCreateNewMailProperties()
                                                throws MailException

For delegating purpose. Don't invoke.

Throws:

MailException

delegateCheckMailServerPort

public boolean delegateCheckMailServerPort()

For delegating purpose. Don't invoke.

delegateReleaseResources

public void delegateReleaseResources()

For delegating purpose. Don't invoke.

delegateCloseInternal

public void delegateCloseInternal()

For delegating purpose. Don't invoke.

getFolderStorage

public abstract F getFolderStorage()
                                                       throws MailException

Gets the appropriate IMailFolderStorage implementation that is considered as the main entry point to a user's mailbox.

Returns:

The appropriate IMailFolderStorage implementation

Throws:

MailException - If connection is not established

getMessageStorage

public abstract M getMessageStorage()
                                                         throws MailException

Gets the appropriate IMailMessageStorage implementation that provides necessary message-related operations/methods.

Returns:

The appropriate IMailMessageStorage implementation

Throws:

MailException - If connection is not established

getLogicTools

public abstract MailLogicTools getLogicTools()
                                      throws MailException

Gets the appropriate MailLogicTools implementation that provides operations/methods to create a reply/forward message from a referenced message.

Returns:

The appropriate MailLogicTools implementation

Throws:

MailException - If connection is not established

isConnected

public abstract boolean isConnected()

Checks if this connection is currently connected.

Returns:

true if connected; otherwise false

See Also:

isConnectedUnsafe()

isConnectedUnsafe

public abstract boolean isConnectedUnsafe()

Checks if this connection is currently connected in an unsafe, but faster manner than isConnected().

Returns:

true if connected; otherwise false

See Also:

isConnected()