public abstract class MailAccess<F extends IMailFolderStorage,M extends IMailMessageStorage>
extends java.lang.Object
implements java.io.Serializable, java.io.Closeable
MailAccess
- Handles connecting to the mailing system while using an internal cache for connected access objects (see
SingletonMailAccessCache
).
Moreover it provides access to either message storage, folder storage and logic tools.
Modifier and Type | Field and Description |
---|---|
static int |
MAX_PER_USER
- The max. number of MailAccess instanced allowed being cached concurrently for a user's account.
|
Modifier and Type | Method and Description |
---|---|
void |
addWarnings(java.util.Collection<com.openexchange.exception.OXException> warnings)
Adds given warnings.
|
void |
close() |
void |
close(boolean put2Cache)
Closes this access.
|
void |
connect()
Opens this access.
|
void |
connect(boolean checkDefaultFolders)
Opens this access.
|
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. |
static IMailAccessCache |
getMailAccessCache()
Gets the appropriate
mail access cache instance. |
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. |
static MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> |
getNewInstance(com.openexchange.session.Session session,
int accountId)
Gets a new, un-cached MailAccess instance that is initially not connected.
|
MailProvider |
getProvider()
Gets the associated
MailProvider instance. |
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.
|
com.openexchange.session.Session |
getSession()
Gets the session associated with this MailAccess instance.
|
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<com.openexchange.exception.OXException> |
getWarnings()
Gets possible warnings.
|
void |
invokeReleaseResources()
Releases all used resources prior to caching or closing a connection.
|
boolean |
isCacheable()
Indicates if this mail access is cacheable.
|
boolean |
isCached()
Indicates if this mail access is currently cached in
IMailAccessCache . |
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 |
isTrackable()
Indicates if this mail access is trackable by
MailAccessWatcher . |
boolean |
isWaiting()
Indicates if this mail access is currently waiting for any server notifications (idle mode).
|
void |
logTrace(java.lang.StringBuilder sBuilder,
org.slf4j.Logger log)
Logs the trace of the thread that lastly obtained this access.
|
boolean |
ping()
Pings the mail server to check if a connection can be established and and immediately closes connection.
|
static MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> |
reconnect(MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> mailAccess)
Re-connects specified MailAccess instance.
|
static void |
rememberMimeCleanUp(MimeCleanUp mimeCleanUp)
Remembers specified
MimeCleanUp instance. |
void |
setCacheable(boolean cacheable)
Sets whether this mail access is cacheable or not.
|
void |
setCached(boolean cached)
Sets whether this mail access is currently cached or not.
|
void |
setMailProperties(java.util.Properties mailProperties)
Sets optional properties used on connect.
|
void |
setTrackable(boolean trackable)
Sets if this mail access is trackable by
MailAccessWatcher . |
void |
setWaiting(boolean waiting)
Sets whether this mail access is currently waiting for any mail server notifications or not.
|
java.lang.String |
toString() |
public static final int MAX_PER_USER
public com.openexchange.session.Session getSession()
public MailProvider getProvider()
MailProvider
instance.public void addWarnings(java.util.Collection<com.openexchange.exception.OXException> warnings)
warnings
- The warnings to addpublic java.util.Collection<com.openexchange.exception.OXException> getWarnings()
public static IMailAccessCache getMailAccessCache() throws com.openexchange.exception.OXException
mail access cache
instance.com.openexchange.exception.OXException
- If cache cannot be initializedpublic static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> getInstance(com.openexchange.session.Session session) throws com.openexchange.exception.OXException
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:
MailAccess mailAccess = null; try { mailAccess = MailAccess.getInstance(...); mailAccess.connect(); // Do something } finally { if (mailAccess != null) { mailAccess.close(putToCache); } }
session
- The sessioncom.openexchange.exception.OXException
- If instantiation fails or a caching error occurspublic static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> getInstance(com.openexchange.session.Session session, int accountId) throws com.openexchange.exception.OXException
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:
MailAccess mailAccess = null; try { mailAccess = MailAccess.getInstance(...); mailAccess.connect(); // Do something } finally { if (mailAccess != null) { mailAccess.close(putToCache); } }
session
- The sessionaccountId
- The account IDcom.openexchange.exception.OXException
- If instantiation fails or a caching error occurspublic static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> getNewInstance(com.openexchange.session.Session session, int accountId) throws com.openexchange.exception.OXException
session
- The associated sessionaccountId
- The account identifiercom.openexchange.exception.OXException
- If a new, un-cached MailAccess instance cannot be returnedpublic static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> reconnect(MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> mailAccess) throws com.openexchange.exception.OXException
mailAccess
- The MailAccess instance to re-connectcom.openexchange.exception.OXException
- If re-connect attempt failsgetNewInstance(Session, int)
public static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> getInstance(int userId, int contextId) throws com.openexchange.exception.OXException
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:
MailAccess mailAccess = null; try { mailAccess = MailAccess.getInstance(...); mailAccess.connect(); // Do something } finally { if (mailAccess != null) { mailAccess.close(putToCache); } }
userId
- The user identifiercontextId
- The context identifiermail access
com.openexchange.exception.OXException
- If instantiation fails or a caching error occurspublic static final MailAccess<? extends IMailFolderStorage,? extends IMailMessageStorage> getInstance(int userId, int contextId, int accountId) throws com.openexchange.exception.OXException
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:
MailAccess mailAccess = null; try { mailAccess = MailAccess.getInstance(...); mailAccess.connect(); // Do something } finally { if (mailAccess != null) { mailAccess.close(putToCache); } }
userId
- The user identifiercontextId
- The context identifieraccountId
- The account identifiermail access
com.openexchange.exception.OXException
- If instantiation fails or a caching error occurspublic static final int getCounter()
public java.util.Properties getMailProperties()
public void setMailProperties(java.util.Properties mailProperties)
mailProperties
- The propertiespublic boolean ping() throws com.openexchange.exception.OXException
Default implementation just delegates to connect()
but may be overridden in implementing subclass if not appropriate or a
faster way can be achieved.
true
if a connection can be established; otherwise false
com.openexchange.exception.OXException
- If the ping failspublic final void connect() throws com.openexchange.exception.OXException
com.openexchange.exception.OXException
- If the connection could not be established for various reasonspublic final void connect(boolean checkDefaultFolders) throws com.openexchange.exception.OXException
checkDefaultFolders
- true
to check existence of default folders; otherwise false
to omit checkcom.openexchange.exception.OXException
- If the connection could not be established for various reasonspublic MailFolder getRootFolder() throws com.openexchange.exception.OXException
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) }
com.openexchange.exception.OXException
- If returning the root folder failspublic int getUnreadMessagesCount(java.lang.String fullname) throws com.openexchange.exception.OXException
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) }
com.openexchange.exception.OXException
- If returning the unread count failspublic void close()
close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
public final void close(boolean put2Cache)
An already closed access is not going to be put into cache and is treated as a no-op.
put2Cache
- true
to try to put this mail connection into cache; otherwise false
public static void rememberMimeCleanUp(MimeCleanUp mimeCleanUp)
MimeCleanUp
instance.mimeCleanUp
- The MimeCleanUp
instancepublic void logTrace(java.lang.StringBuilder sBuilder, org.slf4j.Logger log)
public final java.lang.String getTrace()
This is useful to detect certain threads which uses an access for a long time
public java.lang.String toString()
toString
in class java.lang.Object
public MailConfig getMailConfig() throws com.openexchange.exception.OXException
com.openexchange.exception.OXException
public int getAccountId()
public boolean isTrackable()
MailAccessWatcher
.true
if this mail access is trackable; otherwise false
public void setTrackable(boolean trackable)
MailAccessWatcher
.trackable
- true
if this mail access is trackable; otherwise false
public int getCacheIdleSeconds()
cache
before being removed
and closed. If the default value shall be used for this mail access, return -1
.-1
to signal using default value.public boolean isCacheable()
true
if this mail access is cacheable; otherwise false
public void setCacheable(boolean cacheable)
cacheable
- true
if this mail access is cacheable; otherwise false
public boolean isCached()
IMailAccessCache
.true
if this mail access is cached; otherwise false
public void setCached(boolean cached)
cacheable
- true
if this mail access is cached; otherwise false
public boolean isWaiting()
true
if this mail access is waiting; otherwise false
public void setWaiting(boolean waiting)
cacheable
- true
if this mail access is waiting; otherwise false
public void invokeReleaseResources()
public abstract F getFolderStorage() throws com.openexchange.exception.OXException
IMailFolderStorage
implementation that is considered as the main entry point to a user's mailbox.IMailFolderStorage
implementationcom.openexchange.exception.OXException
- If connection is not establishedpublic abstract M getMessageStorage() throws com.openexchange.exception.OXException
IMailMessageStorage
implementation that provides necessary message-related operations/methods.IMailMessageStorage
implementationcom.openexchange.exception.OXException
- If connection is not establishedpublic abstract MailLogicTools getLogicTools() throws com.openexchange.exception.OXException
MailLogicTools
implementation that provides operations/methods to create a reply/forward message from a
referenced message.MailLogicTools
implementationcom.openexchange.exception.OXException
- If connection is not establishedpublic abstract boolean isConnected()
true
if connected; otherwise false
isConnectedUnsafe()
public abstract boolean isConnectedUnsafe()
isConnected()
.true
if connected; otherwise false
isConnected()