Top Description Inners Fields Methods
javax.mail

public Interface UIDFolder

Imports
java.util.NoSuchElementException
The UIDFolder interface is implemented by Folders that can support the "disconnected" mode of operation, by providing unique-ids for messages in the folder. This interface is based on the IMAP model for supporting disconnected operation.

A Unique identifier (UID) is a positive long value, assigned to each message in a specific folder. Unique identifiers are assigned in a strictly ascending fashion in the mailbox. That is, as each message is added to the mailbox it is assigned a higher UID than the message(s) which were added previously. Unique identifiers persist across sessions. This permits a client to resynchronize its state from a previous session with the server.

Associated with every mailbox is a unique identifier validity value. If unique identifiers from an earlier session fail to persist to this session, the unique identifier validity value must be greater than the one used in the earlier session.

Refer to RFC 2060 for more information. All the Folder objects returned by the default IMAP provider implement the UIDFolder interface. Use it as follows: 


 	Folder f = store.getFolder("whatever");
	UIDFolder uf = (UIDFolder)f;
	long uid = uf.getUID(msg);

Authors
Bill Shannon, John Mani

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
UIDFolder.FetchProfileItem

A fetch profile item for fetching UIDs.

Field Summary

Modifier and TypeField and Description
public static final long
LASTUID

This is a special value that can be used as the end parameter in getMessagesByUID(start, end), to denote the UID of the last message in the folder.

public static final long
MAXUID

The largest value possible for a UID, a 32-bit unsigned integer.

Method Summary

Modifier and TypeMethod and Description
public Message

Returns:

the Message object. null is returned if no message corresponding to this UID is obtained.
getMessageByUID(long
UID for the desired message
uid)

Get the Message corresponding to the given UID.

public Message[]

Returns:

array of Message objects
getMessagesByUID(long
start UID
start, long
end UID
end)

Get the Messages specified by the given range.

public Message[]

Returns:

array of Message objects
getMessagesByUID(long[]
array of UIDs
uids)

Get the Messages specified by the given array of UIDs.

public long

Returns:

UID for this message
getUID(Message
Message from this folder
message)

Get the UID for the specified message.

public long

Returns:

the UIDNEXT value, or -1 if unknown
getUIDNext()

Returns the predicted UID that will be assigned to the next message that is appended to this folder.

public long

Returns:

UIDValidity
getUIDValidity()

Returns the UIDValidity value associated with this folder.

Field Detail

LASTUIDback to summary
public static final long LASTUID

This is a special value that can be used as the end parameter in getMessagesByUID(start, end), to denote the UID of the last message in the folder.

See Also
getMessagesByUID
MAXUIDback to summary
public static final long MAXUID

The largest value possible for a UID, a 32-bit unsigned integer. This can be used to fetch all new messages by keeping track of the last UID that was seen and using: 


 	Folder f = store.getFolder("whatever");
	UIDFolder uf = (UIDFolder)f;
	Message[] newMsgs =
		uf.getMessagesByUID(lastSeenUID + 1, UIDFolder.MAXUID);

Since
JavaMail 1.6

Method Detail

getMessageByUIDback to summary
public Message getMessageByUID(long uid) throws MessagingException

Get the Message corresponding to the given UID. If no such message exists, null is returned.

Parameters
uid:long

UID for the desired message

Returns:Message

the Message object. null is returned if no message corresponding to this UID is obtained.

Exceptions
MessagingException:
for failures
getMessagesByUIDback to summary
public Message[] getMessagesByUID(long start, long end) throws MessagingException

Get the Messages specified by the given range. The special value LASTUID can be used for the end parameter to indicate the UID of the last message in the folder.

Note that end need not be greater than start; the order of the range doesn't matter. Note also that, unless the folder is empty, use of LASTUID ensures that at least one message will be returned - the last message in the folder.

Parameters
start:long

start UID

end:long

end UID

Returns:Message[]

array of Message objects

Exceptions
MessagingException:
for failures
See Also
LASTUID
getMessagesByUIDback to summary
public Message[] getMessagesByUID(long[] uids) throws MessagingException

Get the Messages specified by the given array of UIDs. If any UID is invalid, null is returned for that entry.

Note that the returned array will be of the same size as the specified array of UIDs, and null entries may be present in the array to indicate invalid UIDs.

Parameters
uids:long[]

array of UIDs

Returns:Message[]

array of Message objects

Exceptions
MessagingException:
for failures
getUIDback to summary
public long getUID(Message message) throws MessagingException

Get the UID for the specified message. Note that the message must belong to this folder. Otherwise java.util.NoSuchElementException is thrown.

Parameters
message:Message

Message from this folder

Returns:long

UID for this message

Exceptions
MessagingException:
for other failures
NoSuchElementException:
if the given Message is not in this Folder.
getUIDNextback to summary
public long getUIDNext() throws MessagingException

Returns the predicted UID that will be assigned to the next message that is appended to this folder. Messages might be appended to the folder after this value is retrieved, causing this value to be out of date. This value might only be updated when a folder is first opened. Note that messages may have been appended to the folder while it was open and thus this value may be out of date.

If the value is unknown, -1 is returned.

Returns:long

the UIDNEXT value, or -1 if unknown

Exceptions
MessagingException:
for failures
Since
JavaMail 1.6
getUIDValidityback to summary
public long getUIDValidity() throws MessagingException

Returns the UIDValidity value associated with this folder.

Clients typically compare this value against a UIDValidity value saved from a previous session to insure that any cached UIDs are not stale.

Returns:long

UIDValidity

Exceptions
MessagingException:
for failures
javax.mail back to summary

public Class UIDFolder.FetchProfileItem

extends Item
Class Inheritance
A fetch profile item for fetching UIDs. This inner class extends the FetchProfile.Item class to add new FetchProfile item types, specific to UIDFolders. The only item currently defined here is the UID item.
See Also
FetchProfile

Field Summary

Modifier and TypeField and Description
public static final UIDFolder.FetchProfileItem
UID

UID is a fetch profile item that can be included in a FetchProfile during a fetch request to a Folder.

Inherited from javax.mail.FetchProfile.Item:
CONTENT_INFOENVELOPEFLAGSSIZE

Constructor Summary

AccessConstructor and Description
protected
FetchProfileItem(String name)

Method Summary

Inherited from javax.mail.FetchProfile.Item:
toString

Field Detail

UIDback to summary
public static final UIDFolder.FetchProfileItem UID

UID is a fetch profile item that can be included in a FetchProfile during a fetch request to a Folder. This item indicates that the UIDs for messages in the specified range are desired to be prefetched.

An example of how a client uses this is below: 


 	FetchProfile fp = new FetchProfile();
	fp.add(UIDFolder.FetchProfileItem.UID);
	folder.fetch(msgs, fp);

Constructor Detail

FetchProfileItemback to summary
protected FetchProfileItem(String name)