oracle.mail.sdk.esmail
Class OracleFolder

oracle.mail.sdk.esmail.OracleFolder

Direct Known Subclasses:

DefaultFolder, OracleSharedFolder

public class OracleFolder

This class implements an Oracle folder.

When a folder is opened, a messageCache (Vector) and a uidMap (Hashtable) is created. The messageCache contains a list of Message objects with only a small set of information filled in. The uidMap provides quick access to the Message object using the message UID.

When information is needed from the store, a database connection is retrieved from the database pool (OracleDBPool) and then released back to the pool when the operation is complete.

Version:

1.0, 2001/03/21

Inner Class Summary

static class

OracleFolder.OracleFlag

Method Summary

void	addACI(java.lang.String aUser, java.lang.String aAci) Takes in a user_address, ACI string and calls an LDAP api to set the ACI for the user.
void	addACI(java.lang.String aUser, java.lang.String aAci, boolean fullACISupport) Takes in a user_address, ACI string and a flag to determine if the full ACI list is supported or not and calls a LDAP api to set the ACI for the user.
void	addACI(java.lang.String aUserType, java.lang.String aUser, java.lang.String aAci) addACI method takes in a user type, user_address, aci string and calls ldap api to set the aci for the user.
void	addACI(java.lang.String aUserType, java.lang.String aUser, java.lang.String aAci, boolean fullACISupport) Takes in a user_address, ACI string and a flag to determine if the full ACI list is supported or not and calls a LDAP api to set the ACI for the user.
void	appendMessages(javax.mail.Message[] msgs) Appends messages to this folder.
void	appendMessages(javax.mail.Message[] msgs, java.lang.String migrationID_header) Appends messages to this folder.
void	close(boolean expunge) Closes the folder and expunges the folder if requested.
void	copyMessages(javax.mail.Message[] msgs, oracle.mail.sdk.esmail.Folder folder) Copies the specified messages from this folder to the specified destination folder.
boolean	create(int type) If type doesn't have HOLDS_MESSAGES, it implies /NOSELECT.
boolean	delete(boolean recurse) Deletes this folder.
boolean	exists() Checks if the folder exists on the store.
javax.mail.Message[]	expunge() Expunges messages marked \DELETED.
void	fetch(javax.mail.Message[] msgs, oracle.mail.sdk.esmail.FetchProfile fp) Prefetches the items specified in the FetchProfile for the given messages.
OracleFilteredMsgHdrs[]	getFilteredHeaders(long[] msgUids) Returns a list of .
oracle.mail.sdk.esmail.Folder	getFolder(java.lang.String name) Returns the folder object corresponding to the given name.
long	getFolderId() Returns the internal folder id for this folder.
int	getFolderSize() Returns the sum total of the sizes of all the messages in a folder.
java.lang.String	getFullName() Returns the current folder's full name which DOES NOT contain the namespace
java.lang.String	getFullPath() Returns the full folder name with the namespace.
java.util.Vector	getGranteeACI() Returns a vector of OracleGranteeACI objects.
javax.mail.Message	getMessage(int msgnum) Returns the message object corresponding to the given message number.
javax.mail.Message[]	getMessageByType(int type) Returns the message object that corresponds to the given message type.
javax.mail.Message	getMessageByUID(long uid) Returns the Message object that corresponds to the given message uid.
int	getMessageCount() Returns the total number of messages in a folder.
javax.mail.Message[]	getMessagesByUID(long[] uids) Returns the messages specified in the UID array.
javax.mail.Message[]	getMessagesByUID(long start, long end) Returns the messages specified in the range (inclusively).
java.lang.String	getName() Returns the cannonical name of the folder.
int	getNewMessageCount() Returns the number of messages with \RECENT flag in this folder.
oracle.mail.sdk.esmail.Folder	getParent() Returns a new folder object that represents the parent of this folder.
oracle.mail.sdk.esmail.Flags	getPermanentFlags() Returns the list of permanent flags.
char	getSeparator() Returns the folder delimiter character.
int	getType() Returns the folder type - HOLDS_FOLDER, HOLDS_MESSAGE.
long	getUID(javax.mail.Message message) Returns the msg UID for the specified message.
long	getUIDValidity() Returns the uid validity information for the folder.
int	getUnreadMessageCount() Returns the total number of unread messages in a folder.
oracle.mail.sdk.esmail.URLName	getURLName() Returns the URL name reprensenting this folder.
boolean	hasNewMessages() Checks whether the folder has messages with the \RECENT flag set.
boolean	isOpen() Returns the opened flag.
boolean	isShared() Checks if the folder is shared.
boolean	isSubscribed() Returns true if this folder is subscribed.
oracle.mail.sdk.esmail.Folder[]	list(java.lang.String pattern) Returns a list of folder objects that match the pattern.
oracle.mail.sdk.esmail.Folder[]	listSubscribed(java.lang.String pattern) Returns a list subscribed of folder objects that match the pattern.
void	moveMessages(javax.mail.Message[] msgs, oracle.mail.sdk.esmail.Folder folder) Moves messages to other folders.
void	open(int mode) Returns the folder information and then fetches all the messages in the folder.
void	removeACI(java.lang.String aUser) Takes in a user_address and removes folder access for the user.
void	removeACI(java.lang.String aUserType, java.lang.String aUser) Takes in a user type, user_address and removes access for the user.
boolean	renameTo(oracle.mail.sdk.esmail.Folder f) Renames this folder and notifies the RenameListeners.
javax.mail.Message[]	search(javax.mail.search.SearchTerm term) Constructs the IMAP4 search string and calls the PL/SQL search.
javax.mail.Message[]	search(javax.mail.search.SearchTerm term, javax.mail.Message[] msgs) Constructs the IMAP4 search string and calls the PL/SQL search.
void	setFlags(int[] msgnums, oracle.mail.sdk.esmail.Flags flag, boolean value) Set flags for the folder.
void	setFlags(int start, int end, oracle.mail.sdk.esmail.Flags flag, boolean value) Sets flags for the folder.
void	setFlags(javax.mail.Message[] msgs, oracle.mail.sdk.esmail.Flags flag, boolean value) Set flags
void	setSubscribed(boolean subscribe) Subscribes or unsubscribes the folder.
long[]	sortMessages(java.util.Vector aSortCriteriaVector) Sorts the messages in the folder according to the specified order, returning a list of message UIDs.

Method Detail

appendMessages

public void appendMessages(javax.mail.Message[] msgs)
                    throws oracle.mail.sdk.esmail.MessagingException

Appends messages to this folder.

Parameters:

msgs - Message objects to append into this folder

See Also:

Folder.appendMessages

appendMessages

public void appendMessages(javax.mail.Message[] msgs,
                           java.lang.String migrationID_header)
                    throws oracle.mail.sdk.esmail.MessagingException

Appends messages to this folder.

Parameters:

msgs - Message objects to append into this folder

migrationID_header - Message header where the migration ID is store

See Also:

javax.mail.Folder.appendMessages

close

public void close(boolean expunge)
           throws oracle.mail.sdk.esmail.MessagingException

Closes the folder and expunges the folder if requested.

Parameters:

expunge - Flag to indicate if expunge is required

See Also:

Folder.close()

copyMessages

public void copyMessages(javax.mail.Message[] msgs,
                         oracle.mail.sdk.esmail.Folder folder)
                  throws oracle.mail.sdk.esmail.MessagingException

Copies the specified messages from this folder to the specified destination folder. Message objects MUST belong to this Folder.

See Also:

javax.mail.Folder.copyMessages

create

public boolean create(int type)
               throws oracle.mail.sdk.esmail.MessagingException

If type doesn't have HOLDS_MESSAGES, it implies /NOSELECT. This means you cannot open the folder. If type doesn't have HOLDS_FOLDER, it implies /NOINFERIORS. This means you cannot create subfolders. NOTE: The INBOX is case-sensitive, all capital letters. In addition, creation of any folder with the name inbox is not allowed.

See Also:

javax.mail.Folder.create()

delete

public boolean delete(boolean recurse)
               throws oracle.mail.sdk.esmail.MessagingException

Deletes this folder. If recurse is true, delete all the sub-folders. as well. Notifies the listeners of the DELETE event. NOTE: The INBOX is case-sensitive, all capital letters. In addition, creation or deletion of any folder with the name inbox is not allowed.

See Also:

Folder.delete

exists

public boolean exists()
               throws oracle.mail.sdk.esmail.MessagingException

Checks if the folder exists on the store.

See Also:

javax.mail.Folder.exists

moveMessages

public void moveMessages(javax.mail.Message[] msgs,
                         oracle.mail.sdk.esmail.Folder folder)
                  throws oracle.mail.sdk.esmail.MessagingException

Moves messages to other folders. This is an extended api. To use this api cast to OracleFolder. In OCS version 2, it is possible to use this api to copy between shared folders.

expunge

public javax.mail.Message[] expunge()
                             throws oracle.mail.sdk.esmail.MessagingException

Expunges messages marked \DELETED. Returns an array containing the expunged message objects.

See Also:

Folder.expunge()

fetch

public void fetch(javax.mail.Message[] msgs,
                  oracle.mail.sdk.esmail.FetchProfile fp)
           throws oracle.mail.sdk.esmail.MessagingException

Prefetches the items specified in the FetchProfile for the given messages.

See Also:

javax.mail.Folder.fetch

getFolder

public oracle.mail.sdk.esmail.Folder getFolder(java.lang.String name)
                                        throws oracle.mail.sdk.esmail.MessagingException

Returns the folder object corresponding to the given name. It doesn't have to physically exist in the Store. NOTE: The INBOX is case-sensitive, all capital letters. In addition, creation or deletion of any folder with the name inbox is not allowed. Assume that the folder name is relative to the current folder; absolute path is NOT supported.

See Also:

javax.mail.Folder.getFolder

getFullName

public java.lang.String getFullName()

Returns the current folder's full name which DOES NOT contain the namespace

See Also:

javax.mail.Folder.getFullName

getMessage

public javax.mail.Message getMessage(int msgnum)
                              throws oracle.mail.sdk.esmail.MessagingException

Returns the message object corresponding to the given message number.

See Also:

javax.mail.Folder.getMessage

getMessageCount

public int getMessageCount()
                    throws oracle.mail.sdk.esmail.MessagingException

Returns the total number of messages in a folder. NOTE: For optimization, we can just use the cached number, but it may be out of sync with what is in the store.

See Also:

javax.mail.Folder.getMessageCount

getName

public java.lang.String getName()

Returns the cannonical name of the folder.

See Also:

javax.mail.Folder.getName

getNewMessageCount

public int getNewMessageCount()
                       throws oracle.mail.sdk.esmail.MessagingException

Returns the number of messages with \RECENT flag in this folder. If opened, do a NOOP and return the number of recent messages. If closed, do a STATUS and return the number of recent messages.

See Also:

javax.mail.Folder.getNewMessageCount()

getParent

public oracle.mail.sdk.esmail.Folder getParent()
                                        throws oracle.mail.sdk.esmail.MessagingException

Returns a new folder object that represents the parent of this folder.

See Also:

javax.mail.Folder.getParent

getPermanentFlags

public oracle.mail.sdk.esmail.Flags getPermanentFlags()

Returns the list of permanent flags.

See Also:

javax.mail.Folder.getPermanentFlags

getSeparator

public char getSeparator()

Returns the folder delimiter character.

See Also:

javax.mail.Folder.getSeparator

getType

public int getType()
            throws oracle.mail.sdk.esmail.MessagingException

Returns the folder type - HOLDS_FOLDER, HOLDS_MESSAGE. This information is from the cache; may be out of sync with the store.

See Also:

javax.mail.Folder.getType

getUnreadMessageCount

public int getUnreadMessageCount()
                          throws oracle.mail.sdk.esmail.MessagingException

Returns the total number of unread messages in a folder. NOTE: in the opened state, returning a cached unread number; it may be out of sync with what is in the store.

See Also:

javax.mail.Folder.getUnreadMessageCount

getURLName

public oracle.mail.sdk.esmail.URLName getURLName()
                                          throws oracle.mail.sdk.esmail.MessagingException

Returns the URL name reprensenting this folder.

See Also:

javax.mail.Folder.getURLName

hasNewMessages

public boolean hasNewMessages()
                       throws oracle.mail.sdk.esmail.MessagingException

Checks whether the folder has messages with the \RECENT flag set. If folder is open, already know the number of recent msgs. If folder is closed, check for recent messages.

See Also:

javax.mail.Folder.hasNewMessages

isOpen

public boolean isOpen()

Returns the opened flag.

See Also:

javax.mail.Folder.isOpen

isSubscribed

public boolean isSubscribed()

Returns true if this folder is subscribed.

See Also:

javax.mail.Folder.isSubscribed

list

public oracle.mail.sdk.esmail.Folder[] list(java.lang.String pattern)
                                     throws oracle.mail.sdk.esmail.MessagingException

Returns a list of folder objects that match the pattern.

See Also:

javax.mail.Folder.list

listSubscribed

public oracle.mail.sdk.esmail.Folder[] listSubscribed(java.lang.String pattern)
                                               throws oracle.mail.sdk.esmail.MessagingException

Returns a list subscribed of folder objects that match the pattern.

See Also:

javax.mail.Folder.listSubscribed

open

public void open(int mode)
          throws oracle.mail.sdk.esmail.MessagingException

Returns the folder information and then fetches all the messages in the folder. Creates light weight message objects.

See Also:

javax.mail.Folder.open

renameTo

public boolean renameTo(oracle.mail.sdk.esmail.Folder f)
                 throws oracle.mail.sdk.esmail.MessagingException

Renames this folder and notifies the RenameListeners.

See Also:

javax.mail.Folder.renameTo

search

public javax.mail.Message[] search(javax.mail.search.SearchTerm term)
                            throws oracle.mail.sdk.esmail.MessagingException

Constructs the IMAP4 search string and calls the PL/SQL search.

See Also:

javax.mail.Folder.search

search

public javax.mail.Message[] search(javax.mail.search.SearchTerm term,
                                   javax.mail.Message[] msgs)
                            throws oracle.mail.sdk.esmail.MessagingException

Constructs the IMAP4 search string and calls the PL/SQL search.

See Also:

javax.mail.Folder.search

setFlags

public void setFlags(int[] msgnums,
                     oracle.mail.sdk.esmail.Flags flag,
                     boolean value)
              throws oracle.mail.sdk.esmail.MessagingException

Set flags for the folder.

See Also:

javax.mail.Folder.setFlags

setFlags

public void setFlags(int start,
                     int end,
                     oracle.mail.sdk.esmail.Flags flag,
                     boolean value)
              throws oracle.mail.sdk.esmail.MessagingException

Sets flags for the folder.

See Also:

javax.mail.Folder.setFlags

setFlags

public void setFlags(javax.mail.Message[] msgs,
                     oracle.mail.sdk.esmail.Flags flag,
                     boolean value)
              throws oracle.mail.sdk.esmail.MessagingException

Set flags

See Also:

javax.mail.Folder.setFlags

setSubscribed

public void setSubscribed(boolean subscribe)
                   throws oracle.mail.sdk.esmail.MessagingException

Subscribes or unsubscribes the folder.

See Also:

javax.mail.Folder.setSubscribed

getMessageByUID

public javax.mail.Message getMessageByUID(long uid)
                                   throws oracle.mail.sdk.esmail.MessagingException

Returns the Message object that corresponds to the given message uid. If not such message exists, null is returned.

See Also:

javax.mail.UIDFolder.getMessageByUID

getMessagesByUID

public javax.mail.Message[] getMessagesByUID(long[] uids)
                                      throws oracle.mail.sdk.esmail.MessagingException

Returns the messages specified in the UID array. If any uid in the array is invalid, a null entry is returned for that element.

See Also:

javax.mail.UIDFolder.getMessagesByUID

getMessagesByUID

public javax.mail.Message[] getMessagesByUID(long start,
                                             long end)
                                      throws oracle.mail.sdk.esmail.MessagingException

Returns the messages specified in the range (inclusively). If any uid in the range is invalid, a null entry is returned for that element.

See Also:

javax.mail.UIDFolder.getMessagesByUID

getUID

public long getUID(javax.mail.Message message)
            throws oracle.mail.sdk.esmail.MessagingException

Returns the msg UID for the specified message.

See Also:

javax.mail.UIDFolder.getUID

getUIDValidity

public long getUIDValidity()
                    throws oracle.mail.sdk.esmail.MessagingException

Returns the uid validity information for the folder.

See Also:

javax.mail.UIDFolder.getUIDValidity

getFullPath

public java.lang.String getFullPath()

Returns the full folder name with the namespace.

getFolderId

public long getFolderId()
                 throws oracle.mail.sdk.esmail.MessagingException

Returns the internal folder id for this folder.

addACI

public void addACI(java.lang.String aUser,
                   java.lang.String aAci)
            throws oracle.mail.sdk.esmail.MessagingException

Takes in a user_address, ACI string and calls an LDAP api to set the ACI for the user. The user type defaults to mailuser(ESDSConstants.DS_MAILUSER). In OCS version 1, no grouping of ACIs was done. The only supported acis were i(write) and r(read). In OCS version 2, this api will continue to be supported However, the ACIs will be grouped as follows for backward compatibility reasons:
If you give only the "r" ACI, the following ACIs are also granted: l - list/lookup, r - read, s - set seen/unseen flags,
If you give only the "i" ACI, the following ACIs will also be granted: l - list/lookup, w - set other flags, i - insert, d - set delete flag
If you choose to use the OCS version 2 method use: addACI (String aUser, String aACI, true) OR addACI (String aUserType, String aUser, String aCI, true)

Parameters:

aUser - user, dl, domain, etc to be granted access to shared folder

aAci - user's ACI

Throws:

oracle.mail.sdk.esmail.MessagingException - IOException

addACI

public void addACI(java.lang.String aUser,
                   java.lang.String aAci,
                   boolean fullACISupport)
            throws oracle.mail.sdk.esmail.MessagingException

Takes in a user_address, ACI string and a flag to determine if the full ACI list is supported or not and calls a LDAP api to set the ACI for the user. The user type defaults to mailuser(ESDSConstants.DS_MAILUSER)
The full ACI list supported in OCS version 2 is : l - list/lookup, r - read, s - set seen/unseen flags, w - set other flags, i - insert, d - set delete flag
No grouping of acis is done in OCS version 2. Each aci has to be explicitly granted including l. However, OJMA implicitly allows lookup/listing for backward compatibility.

Parameters:

aUser - user, dl, domain, etc to be granted access to shared folder

aAci - user's aci

Throws:

oracle.mail.sdk.esmail.MessagingException - IOException

addACI

public void addACI(java.lang.String aUserType,
                   java.lang.String aUser,
                   java.lang.String aAci,
                   boolean fullACISupport)
            throws oracle.mail.sdk.esmail.MessagingException

Takes in a user_address, ACI string and a flag to determine if the full ACI list is supported or not and calls a LDAP api to set the ACI for the user. The user type defaults to mailuser(ESDSConstants.DS_MAILUSER)
The full ACL list supported in OCS version 2 is : l - list/lookup, r - read, s - set seen/unseen flags, w - set other flags, i - insert, d - set delete flag
No grouping of ACIs is done in OCS version 2. Each ACI has to be explicitly granted including l. Set the fullACISupport to true to use v2 style ACI support.
For backward compatibility reasons, OJMA implicitly allows lookup/listing even though the ACI is not present in the ACI list.

Parameters:

aUserType - user - ESDSConstants.DS_MAILUSER, dl - ESDSConstants.DS_DISTRIBUTION_LIST, domain - ESDSConstants.DS_DOMAIN

aUser - user, dl, domain, etc to be granted access to shared folder

aAci - user's aci

fullACISupport - flag for full aci vs r,i only

Throws:

oracle.mail.sdk.esmail.MessagingException - IOException

addACI

public void addACI(java.lang.String aUserType,
                   java.lang.String aUser,
                   java.lang.String aAci)
            throws oracle.mail.sdk.esmail.MessagingException

addACI method takes in a user type, user_address, aci string and calls ldap api to set the aci for the user. The full ACL list supported in OCS v2 is : l - list/lookup, r - read, s - set seen/unseen flags, w - set other flags, i - insert, d - set delete flag No grouping of acis is done in OCS v2. Each aci has to be explicitly granted including l. Set the fullACISupport to true to use v2 style aci support. For backward compatibility reasons, OJMA implicitly allows lookup/listing even though the aci is not present in the aci list.

Parameters:

aUserType - user - ESDSConstants.DS_MAILUSER, dl - ESDSConstants.DS_DISTRIBUTION_LIST, domain - ESDSConstants.DS_DOMAIN

aUser - user, dl, domain, etc to be granted access to shared folder

aAci - user's aci

Throws:

oracle.mail.sdk.esmail.MessagingException - IOException

removeACI

public void removeACI(java.lang.String aUser)
               throws oracle.mail.sdk.esmail.MessagingException

Takes in a user_address and removes folder access for the user. Calls an LDAP api to remove shared folder ACI for the user. User type defaults to mailuser(ESDSConstants.DS_MAILUSER).

Parameters:

aUser - user, dl, domain, oid group to be granted access to shared folder

Throws:

oracle.mail.sdk.esmail.MessagingException -

removeACI

public void removeACI(java.lang.String aUserType,
                      java.lang.String aUser)
               throws oracle.mail.sdk.esmail.MessagingException

Takes in a user type, user_address and removes access for the user. Calls an LDAP api to remove the shared folder ACI for the user.

Parameters:

aUserType - user - ESDSConstants.DS_MAILUSER, dl - ESDSConstants.DS_DISTRIBUTION_LIST, domain - ESDSConstants.DS_DOMAIN

aUser - user, dl, domain, oid group to be granted access to shared folder

Throws:

oracle.mail.sdk.esmail.MessagingException -

getGranteeACI

public java.util.Vector getGranteeACI()
                               throws oracle.mail.sdk.esmail.MessagingException

Returns a vector of OracleGranteeACI objects. The complete list of grantee aci(s) on shared folders can be obtained by using the OracleGranteeACI objects.

Throws:

oracle.mail.sdk.esmail.MessagingException -

isShared

public boolean isShared()
                 throws oracle.mail.sdk.esmail.MessagingException

Checks if the folder is shared.

Returns:

boolean true/false

getFolderSize

public int getFolderSize()
                  throws oracle.mail.sdk.esmail.MessagingException

Returns the sum total of the sizes of all the messages in a folder.

Returns:

Message size

sortMessages

public long[] sortMessages(java.util.Vector aSortCriteriaVector)
                    throws oracle.mail.sdk.esmail.MessagingException

Sorts the messages in the folder according to the specified order, returning a list of message UIDs.

Parameters:

aSortCriteriaVector - Construct a vector with all the sort criteria

Returns:

array of msg_uid(s)

getMessageByType

public javax.mail.Message[] getMessageByType(int type)
                                      throws oracle.mail.sdk.esmail.MessagingException

Returns the message object that corresponds to the given message type. If not such message exists, null is returned. NOTE: this method does NOT update the message cache. To update the message cache, user can call getMessages(), getMessageCount(), getNewMessageCount() methods.

getFilteredHeaders

public OracleFilteredMsgHdrs[] getFilteredHeaders(long[] msgUids)
                                           throws oracle.mail.sdk.esmail.MessagingException

Returns a list of . If not such message exists, null is returned. NOTE: this method does NOT update the message cache. To update the message cache, user can call getMessages(), getMessageCount(), getNewMessageCount() methods.