UIDFolder (Java EE 5)

Java EE API


javax.mail Interface UIDFolder


public interface UIDFolder


UIDFolder 接口由可支持 "disconnected" 操作模式的 Folder 实现,实现方式是为该文件夹中的消息提供唯一 id。此接口基于 IMAP 模型实现对 disconnected 操作的支持。

唯一标识符 (UID) 是一个正的 long 值,被分配给特定文件夹中的每条消息。在邮箱中,唯一标识符是以严格的升序方式分配的。也就是说,向邮箱中添加每条消息时都会给它分配一个比以前添加的消息更高的 UID。唯一标识符可以跨会话保留。这允许客户端重新与服务器同步其来自以前会话的状态。

与每个邮箱关联的是唯一标识符有效性值。如果以前会话中的唯一标识符无法保留到此会话,那么唯一标识符有效性值必须是比以前会话中使用的有效性值更大的值。

有关更多信息,请参见 RFC 2060 http://www.ietf.org/rfc/rfc2060.txt

英文文档:

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 http://www.ietf.org/rfc/rfc2060.txt for more information.

Author:
John Mani

Nested Class Summary
static class
 
Field Summary
static long
 
Method Summary
 Message
 Message[]
 Message[]
 long
 long
 

Field Detail

英文文档:

LASTUID

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(long, long), Constant Field Values

Method Detail

public long getUIDValidity() throws MessagingException
返回与此文件夹关联的 UIDValidity 值。

客户端通常将此值与以前会话中保存的 UIDValidity 值进行比较,以确保所有缓存的 UID 都没有过时。

return
UIDValidity

英文文档:

getUIDValidity

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:
UIDValidity
Throws:
MessagingException

public Message getMessageByUID(long uid) throws MessagingException
获取与给定 UID 相对应的 Message。如果不存在这样的消息,则返回 null
uid 所需消息的 UID
return Message 对象。如果没有获得与此 UID 相对应的消息,则返回 null
ThrowsMessagingException:
英文文档:

getMessageByUID

Message getMessageByUID(long uid)
                        throws MessagingException
Get the Message corresponding to the given UID. If no such message exists, null is returned.

Parameters:
uid - UID for the desired message
Returns:
the Message object. null is returned if no message corresponding to this UID is obtained.
Throws:
MessagingException

public Message[] getMessagesByUID(long start, long end) throws MessagingException
获取给定范围指定的 Message。可将特殊值 LASTUID 用于 end 参数,以指示文件夹中最后一条消息的 UID。
start 起始 UID
end 结束 UID
return Message 对象数组
ThrowsMessagingException:
See also LASTUID
英文文档:

getMessagesByUID

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.

Parameters:
start - start UID
end - end UID
Returns:
array of Message objects
Throws:
MessagingException
See Also:
LASTUID

public Message[] getMessagesByUID(long[] uids) throws MessagingException
获取给定 UID 数组指定的 Message。如果任一 UID 无效,则为该条目返回 null

注意,返回数组的大小应该与指定的 UID 数组的大小相同,并且 null 条目可能出现在数组中,指示无效 UID。

uids UID 数组
return Message 对象数组
ThrowsMessagingException:

英文文档:

getMessagesByUID

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 - array of UIDs
Returns:
array of Message objects
Throws:
MessagingException

public long getUID(Message message) throws MessagingException
获取指定消息的 UID。注意,该消息必须属于此文件夹。否则抛出 java.util.NoSuchElementException。
message 来自此文件夹的 Message
return 此消息的 UID
Throwsjava.util.NoSuchElementException: 如果给定 Message 不在此 Folder 中。
英文文档:

getUID

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 from this folder
Returns:
UID for this message
Throws:
NoSuchElementException - if the given Message is not in this Folder.
MessagingException


Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正;若因此而造成任何损失请直接找人民主席,请勿与本人联系。谢谢!