Top Description Fields Constructors Methods
javax.mail

public abstract Class Store

extends Service
Class Inheritance
Known Direct Subclasses
com.sun.mail.imap.IMAPStore, com.sun.mail.pop3.POP3Store
Imports
java.io.*, java.net.*, java.util.*, javax.mail.event.*
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.

Authors
John Mani, Bill Shannon
See Also
javax.mail.Service, javax.mail.event.ConnectionEvent, javax.mail.event.StoreEvent

Field Summary

Modifier and TypeField and Description
private volatile Vector<FolderListener>
folderListeners

private volatile Vector<StoreListener>
storeListeners

Inherited from javax.mail.Service:
debugsessionurl

Constructor Summary

AccessConstructor and Description
protected
Store(Session
Session object for this Store.
session, URLName
URLName object to be used for this Store
urlname)

Constructor.

Method Summary

Modifier and TypeMethod and Description
public synchronized void
addFolderListener(FolderListener
the Listener for Folder events
l)

Add a listener for Folder events on any Folder object obtained from this Store.

public synchronized void
addStoreListener(StoreListener
the Listener for Store events
l)

Add a listener for StoreEvents on this Store.

public abstract Folder

Returns:

the root Folder
getDefaultFolder()

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

public abstract Folder

Returns:

Folder object
getFolder(String
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.
name)

Return the Folder object corresponding to the given name.

public abstract Folder

Returns:

Folder object
getFolder(URLName
URLName that denotes a folder
url)

Return a closed Folder object, corresponding to the given URLName.

public Folder[]

Returns:

array of Folder objects
getPersonalNamespaces()

Return a set of folders representing the personal namespaces for the current user.

public Folder[]

Returns:

array of Folder objects
getSharedNamespaces()

Return a set of folders representing the shared namespaces.

public Folder[]

Returns:

array of Folder objects
getUserNamespaces(String
the user name
user)

Return a set of folders representing the namespaces for user.

protected void
notifyFolderListeners(int
type of FolderEvent
type, Folder
affected Folder
folder)

Notify all FolderListeners.

protected void
notifyFolderRenamedListeners(Folder
the folder being renamed
oldF, Folder
the folder representing the new name.
newF)

Notify all FolderListeners about the renaming of a folder.

protected void
notifyStoreListeners(int
the StoreEvent type
type, String
a message for the StoreEvent
message)

Notify all StoreListeners.

public synchronized void
removeFolderListener(FolderListener
the listener
l)

Remove a listener for Folder events.

public synchronized void
removeStoreListener(StoreListener
the listener
l)

Remove a listener for Store events.

Inherited from javax.mail.Service:
addConnectionListenercloseconnectconnectconnectconnectfinalizegetEventQueuegetSessiongetURLNameisConnectednotifyConnectionListenersprotocolConnectqueueEventremoveConnectionListenersetConnectedsetURLNametoString

Field Detail

folderListenersback to summary
private volatile Vector<FolderListener> folderListeners
storeListenersback to summary
private volatile Vector<StoreListener> storeListeners

Constructor Detail

Storeback to summary
protected Store(Session session, URLName urlname)

Constructor.

Parameters
session:Session

Session object for this Store.

urlname:URLName

URLName object to be used for this Store

Method Detail

addFolderListenerback to summary
public synchronized 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:FolderListener

the Listener for Folder events

See Also
javax.mail.event.FolderEvent
addStoreListenerback to summary
public synchronized 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:StoreListener

the Listener for Store events

See Also
javax.mail.event.StoreEvent
getDefaultFolderback to summary
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:Folder

the root Folder

Exceptions
MessagingException:
for other failures
IllegalStateException:
if this Store is not connected.
getFolderback to summary
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:String

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

Folder object

Exceptions
MessagingException:
for other failures
IllegalStateException:
if this Store is not connected.
See Also
Folder#exists, Folder#create
getFolderback to summary
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

URLName that denotes a folder

Returns:Folder

Folder object

Exceptions
MessagingException:
for other failures
IllegalStateException:
if this Store is not connected.
See Also
URLName
getPersonalNamespacesback to summary
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:Folder[]

array of Folder objects

Exceptions
MessagingException:
for other failures
IllegalStateException:
if this Store is not connected.
Since
JavaMail 1.2
getSharedNamespacesback to summary
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:Folder[]

array of Folder objects

Exceptions
MessagingException:
for other failures
IllegalStateException:
if this Store is not connected.
Since
JavaMail 1.2
getUserNamespacesback to summary
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.

Parameters
user:String

the user name

Returns:Folder[]

array of Folder objects

Exceptions
MessagingException:
for other failures
IllegalStateException:
if this Store is not connected.
Since
JavaMail 1.2
notifyFolderListenersback to summary
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:int

type of FolderEvent

folder:Folder

affected Folder

See Also
notifyFolderRenamedListeners
notifyFolderRenamedListenersback to summary
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:Folder

the folder being renamed

newF:Folder

the folder representing the new name.

Since
JavaMail 1.1
notifyStoreListenersback to summary
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.

Parameters
type:int

the StoreEvent type

message:String

a message for the StoreEvent

removeFolderListenerback to summary
public synchronized 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:FolderListener

the listener

See Also
addFolderListener
removeStoreListenerback to summary
public synchronized 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:StoreListener

the listener

See Also
addStoreListener