Store (Java EE 5)

Java EE API

previous page next page
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.mail Class Store

java.lang.Object
  extended by javax.mail.Service
      extended by javax.mail.Store

public abstract class Store
extends Service

Extends: Service

模拟消息存储及其访问协议的抽象类，用于存储和获取消息。子类提供实际实现。

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

version1.28, 07/05/04
See also javax.mail.Service, javax.mail.event.ConnectionEvent, javax.mail.event.StoreEvent

英文文档：

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

Field Summary
 
Fields inherited from class javax.mail.Service
debug, session, url
 
Constructor Summary
protected Store(Session session, URLName urlname)
          Constructor.
 
Method Summary
 void addFolderListener(FolderListener l)
          Add a listener for Folder events on any Folder object obtained from this Store.
 void addStoreListener(StoreListener l)
          Add a listener for StoreEvents on this Store.
abstract  Folder getDefaultFolder()
          Returns a Folder object that represents the 'root' of the default namespace presented to the user by the Store.
abstract  Folder getFolder(String name)
          Return the Folder object corresponding to the given name.
abstract  Folder getFolder(URLName url)
          Return a closed Folder object, corresponding to the given URLName.
 Folder[] getPersonalNamespaces()
          Return a set of folders representing the personal namespaces for the current user.
 Folder[] getSharedNamespaces()
          Return a set of folders representing the shared namespaces.
 Folder[] getUserNamespaces(String user)
          Return a set of folders representing the namespaces for user.
protected  void notifyFolderListeners(int type, Folder folder)
          Notify all FolderListeners.
protected  void notifyFolderRenamedListeners(Folder oldF, Folder newF)
          Notify all FolderListeners about the renaming of a folder.
protected  void notifyStoreListeners(int type, String message)
          Notify all StoreListeners.
 void removeFolderListener(FolderListener l)
          Remove a listener for Folder events.
 void removeStoreListener(StoreListener l)
          Remove a listener for Store events.
 
Methods inherited from class javax.mail.Service
addConnectionListener, close, connect, connect, connect, connect, finalize, getURLName, isConnected, notifyConnectionListeners, protocolConnect, queueEvent, removeConnectionListener, setConnected, setURLName, toString
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

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

Method Detail

abstract public Folder getDefaultFolder() throws MessagingException
返回表示 Store 呈现给用户的默认名称空间的“根”的 Folder 对象。
return 根 Folder
ThrowsIllegalStateException: 如果未连接此 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 对象
ThrowsIllegalStateException: 如果未连接此 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
ThrowsIllegalStateException: 如果未连接此 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 方法的返回值。子类应该重写此方法，以返回相应的信息。

ThrowsIllegalStateException: 如果未连接此 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 的名称空间的文件夹集合。返回的名称空间表示该用户的个人名称空间。要访问其他用户的名称空间中的邮件文件夹，必须得到目前经过验证的用户显式授予的访问权。例如，对于经理而言，通常要为其秘书授予对其邮件文件夹的访问权。

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

ThrowsIllegalStateException: 如果未连接此 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
返回表示共享 名称空间的文件夹集合。共享名称空间是由打算在用户之间共享且不存在于用户的个人名称空间中的邮件文件夹组成的名称空间。

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

ThrowsIllegalStateException: 如果未连接此 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
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature

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

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

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

previous page start next page