Store (Java EE 5)

注意，Store 扩展了 Service 类，该类提供了许多用于命名 store、连接 store 和侦听连接事件的常用方法。

An abstract class that models a message store and its access protocol, for storing and retrieving messages. Subclasses provide actual implementations.

Note that Store extends the Service class, which provides many common methods for naming stores, connecting to stores, and listening to connection events.

Version:

1.28, 07/05/04

Author:

John Mani, Bill Shannon

See Also:

Service, ConnectionEvent, StoreEvent

protected Store(Session session, URLName urlname)
构造方法。

session	此 Store 的 Session 对象。
urlname	要用于此 Store 的 URLName 对象

英文文档：

Store

protected Store(Session session,
                URLName urlname)

Constructor.

Parameters:

session - Session object for this Store.

urlname - URLName object to be used for this Store

abstract public Folder getDefaultFolder() throws MessagingException
返回表示 Store 呈现给用户的默认名称空间的“根”的 Folder 对象。

return	根 Folder
Throws	IllegalStateException: 如果未连接此 Store。

英文文档：

getDefaultFolder

public abstract Folder getDefaultFolder()
                                 throws MessagingException

Returns a Folder object that represents the 'root' of the default namespace presented to the user by the Store.

Returns:

the root Folder

Throws:

IllegalStateException - if this Store is not connected.

MessagingException

abstract public Folder getFolder(String name) throws MessagingException
返回与给定名称相对应的 Folder 对象。注意，即使指定文件夹在物理上并不存在于该 Store 之上，也会返回一个 Folder 对象。该 Folder 对象上的 exists() 方法指示此文件夹是否实际存在。

Store 不缓存 Folder 对象，因此用相同的名称多次调用此方法将返回许多不同的 Folder 对象。

name	Folder 的名称。在某些 Store 中，名称可以是绝对路径，如果它以层次结构分界符开始。否则它将被解释为相对于此名称空间“根”的路径。
return	Folder 对象
Throws	IllegalStateException: 如果未连接此 Store。
See also	exists, create

英文文档：

getFolder

public abstract Folder getFolder(String name)
                          throws MessagingException

Return the Folder object corresponding to the given name. Note that a Folder object is returned even if the named folder does not physically exist on the Store. The exists() method on the folder object indicates whether this folder really exists.

Folder objects are not cached by the Store, so invoking this method on the same name multiple times will return that many distinct Folder objects.

Parameters:

name - The name of the Folder. In some Stores, name can be an absolute path if it starts with the hierarchy delimiter. Else it is interpreted relative to the 'root' of this namespace.

Returns:

Folder object

Throws:

IllegalStateException - if this Store is not connected.

MessagingException

See Also:

Folder.exists(), Folder.create(int)

abstract public Folder getFolder(URLName url) throws MessagingException
返回与给定 URLName 相对应的已关闭 Folder 对象。给定 URLName 中指定的 store 应该引用此 Store 对象。

此方法的实现可使用 URLName 上的 getFile() 方法获得实际文件夹的名称，并使用该名称创建该文件夹。

url	表示文件夹的 URLName
Throws	IllegalStateException: 如果未连接此 Store。
return	Folder 对象
See also	javax.mail.URLName

英文文档：

getFolder

public abstract Folder getFolder(URLName url)
                          throws MessagingException

Return a closed Folder object, corresponding to the given URLName. The store specified in the given URLName should refer to this Store object.

Implementations of this method may obtain the name of the actual folder using the getFile() method on URLName, and use that name to create the folder.

Parameters:

url - URLName that denotes a folder

Returns:

Folder object

Throws:

IllegalStateException - if this Store is not connected.

MessagingException

See Also:

URLName

public Folder[] getPersonalNamespaces() throws MessagingException
返回表示当前用户的个人 名称空间的文件夹集合。个人名称空间是被认为存在于经过验证用户的个人范围内的名称集合。通常，只有经过验证的用户能够访问其个人名称空间中的邮件文件夹。如果用户存在 INBOX，则它必须出现在该用户的个人名称空间中。一般情况下，每个 Store 中的每个用户都应该只有一个个人名称空间。

此实现返回一个带有单个条目的数组，该条目包含 getDefaultFolder 方法的返回值。子类应该重写此方法，以返回相应的信息。

Throws	IllegalStateException: 如果未连接此 Store。
return	Folder 对象数组
since	en JavaMail 1.2

英文文档：

getPersonalNamespaces

public Folder[] getPersonalNamespaces()
                               throws MessagingException

Return a set of folders representing the personal namespaces for the current user. A personal namespace is a set of names that is considered within the personal scope of the authenticated user. Typically, only the authenticated user has access to mail folders in their personal namespace. If an INBOX exists for a user, it must appear within the user's personal namespace. In the typical case, there should be only one personal namespace for each user in each Store.

This implementation returns an array with a single entry containing the return value of the getDefaultFolder method. Subclasses should override this method to return appropriate information.

Returns:

array of Folder objects

Throws:

IllegalStateException - if this Store is not connected.

MessagingException

Since:

JavaMail 1.2

public Folder[] getUserNamespaces(String user) throws MessagingException
返回表示 user 的名称空间的文件夹集合。返回的名称空间表示该用户的个人名称空间。要访问其他用户的名称空间中的邮件文件夹，必须得到目前经过验证的用户显式授予的访问权。例如，对于经理而言，通常要为其秘书授予对其邮件文件夹的访问权。

此实现返回一个空数组。子类应该重写此方法，以返回相应的信息。

Throws	IllegalStateException: 如果未连接此 Store。
return	Folder 对象数组
since	en JavaMail 1.2

英文文档：

getUserNamespaces

public Folder[] getUserNamespaces(String user)
                           throws MessagingException

Return a set of folders representing the namespaces for user. The namespaces returned represent the personal namespaces for the user. To access mail folders in the other user's namespace, the currently authenticated user must be explicitly granted access rights. For example, it is common for a manager to grant to their secretary access rights to their mail folders.

This implementation returns an empty array. Subclasses should override this method to return appropriate information.

Returns:

array of Folder objects

Throws:

IllegalStateException - if this Store is not connected.

MessagingException

Since:

JavaMail 1.2

public Folder[] getSharedNamespaces() throws MessagingException
返回表示共享 名称空间的文件夹集合。共享名称空间是由打算在用户之间共享且不存在于用户的个人名称空间中的邮件文件夹组成的名称空间。

此实现返回一个空数组。子类应该重写此方法，以返回相应的信息。

Throws	IllegalStateException: 如果未连接此 Store。
return	Folder 对象数组
since	en JavaMail 1.2

英文文档：

getSharedNamespaces

public Folder[] getSharedNamespaces()
                             throws MessagingException

Return a set of folders representing the shared namespaces. A shared namespace is a namespace that consists of mail folders that are intended to be shared amongst users and do not exist within a user's personal namespace.

This implementation returns an empty array. Subclasses should override this method to return appropriate information.

Returns:

array of Folder objects

Throws:

IllegalStateException - if this Store is not connected.

MessagingException

Since:

JavaMail 1.2

public void addStoreListener(StoreListener l)
为此 Store 上的 StoreEvent 添加侦听器。

此处提供的默认实现将此侦听器添加到 StoreListener 的内部列表。

l	Store 事件的 Listener
See also	javax.mail.event.StoreEvent

英文文档：

addStoreListener

public void addStoreListener(StoreListener l)

Add a listener for StoreEvents on this Store.

The default implementation provided here adds this listener to an internal list of StoreListeners.

Parameters:

l - the Listener for Store events

See Also:

StoreEvent

public void removeStoreListener(StoreListener l)
移除 Store 事件侦听器。

此处提供的默认实现将从 StoreListener 的内部列表中移除此侦听器。

l	侦听器
See also	addStoreListener

英文文档：

removeStoreListener

public void removeStoreListener(StoreListener l)

Remove a listener for Store events.

The default implementation provided here removes this listener from the internal list of StoreListeners.

Parameters:

l - the listener

See Also:

addStoreListener(javax.mail.event.StoreListener)

protected void notifyStoreListeners(int type, String message)
通知所有 StoreListener。Store 实现应该使用此方法广播 StoreEvent。

提供的默认实现将该事件加入到内部事件队列。事件分发程序线程取消队列中事件的排队，并将其分发给注册的 StoreListener。注意，事件分发发生在不同的线程中，因此避免了可能出现的死锁问题。

英文文档：

notifyStoreListeners

protected void notifyStoreListeners(int type,
                                    String message)

Notify all StoreListeners. Store implementations are expected to use this method to broadcast StoreEvents.

The provided default implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered StoreListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.

public void addFolderListener(FolderListener l)
为从此 Store 中获得的任何 Folder 对象上的 Folder 事件添加侦听器。向受影响的 Folder 上的 FolderListener 以及包含 Store 上的 FolderListener 传送 FolderEvent。

此处提供的默认实现将此侦听器添加到 FolderListener 的内部列表。

l	Folder 事件的 Listener
See also	javax.mail.event.FolderEvent

英文文档：

addFolderListener

public void addFolderListener(FolderListener l)

Add a listener for Folder events on any Folder object obtained from this Store. FolderEvents are delivered to FolderListeners on the affected Folder as well as to FolderListeners on the containing Store.

The default implementation provided here adds this listener to an internal list of FolderListeners.

Parameters:

l - the Listener for Folder events

See Also:

FolderEvent

public void removeFolderListener(FolderListener l)
移除 Folder 事件侦听器。

此处提供的默认实现将从 FolderListener 的内部列表中移除此侦听器。

l	侦听器
See also	addFolderListener

英文文档：

removeFolderListener

public void removeFolderListener(FolderListener l)

Remove a listener for Folder events.

The default implementation provided here removes this listener from the internal list of FolderListeners.

Parameters:

l - the listener

See Also:

addFolderListener(javax.mail.event.FolderListener)

protected void notifyFolderListeners(int type, Folder folder)
通知所有 FolderListener。Store 实现应该使用此方法广播 Folder 事件。

提供的默认实现将该事件加入到内部事件队列。事件分发程序线程取消队列中事件的排队，并将其分发给注册的 FolderListener。注意，事件分发发生在不同的线程中，因此避免了可能出现的死锁问题。

type	FolderEvent 的类型
folder	受影响的 Folder
See also	notifyFolderRenamedListeners

英文文档：

notifyFolderListeners

protected void notifyFolderListeners(int type,
                                     Folder folder)

Notify all FolderListeners. Store implementations are expected to use this method to broadcast Folder events.

The provided default implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered FolderListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.

Parameters:

type - type of FolderEvent

folder - affected Folder

See Also:

notifyFolderRenamedListeners(javax.mail.Folder, javax.mail.Folder)

protected void notifyFolderRenamedListeners(Folder oldF, Folder newF)
通知所有 FolderListener 有关文件夹重命名的信息。Store 实现应该使用此方法广播 Folder 事件，指示文件夹的重命名。

提供的默认实现将该事件加入到内部事件队列。事件分发程序线程取消队列中事件的排队，并将其分发给注册的 FolderListener。注意，事件分发发生在不同的线程中，因此避免了可能出现的死锁问题。

oldF	将被重命名的文件夹
newF	表示新名称的文件夹。
since	en JavaMail 1.1

英文文档：

notifyFolderRenamedListeners

protected void notifyFolderRenamedListeners(Folder oldF,
                                            Folder newF)

Notify all FolderListeners about the renaming of a folder. Store implementations are expected to use this method to broadcast Folder events indicating the renaming of folders.

The provided default implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered FolderListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.

Parameters:

oldF - the folder being renamed

newF - the folder representing the new name.

Since:

JavaMail 1.1

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