public abstract class

Store

extends Service
java.lang.Object
   ↳ com.google.code.javax.mail.Service
     ↳ com.google.code.javax.mail.Store
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

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.

See Also
  • javax.mail.Service
  • javax.mail.event.ConnectionEvent
  • javax.mail.event.StoreEvent

Summary

Fields
private Vector folderListeners
private Vector storeListeners
[Expand]
Inherited Fields
From class com.google.code.javax.mail.Service
Protected Constructors
Store(Session session, URLName urlname)
Constructor.
Public Methods
synchronized void addFolderListener(FolderListener l)
Add a listener for GmailFolder events on any GmailFolder object obtained from this Store.
synchronized void addStoreListener(StoreListener l)
Add a listener for StoreEvents on this Store.
abstract Folder getDefaultFolder()
Returns a GmailFolder object that represents the 'root' of the default namespace presented to the user by the Store.
abstract Folder getFolder(URLName url)
Return a closed GmailFolder object, corresponding to the given URLName.
abstract Folder getFolder(String name)
Return the GmailFolder object corresponding to the given name.
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.
synchronized void removeFolderListener(FolderListener l)
Remove a listener for GmailFolder events.
synchronized void removeStoreListener(StoreListener l)
Remove a listener for Store events.
Protected Methods
void notifyFolderListeners(int type, Folder folder)
Notify all FolderListeners.
void notifyFolderRenamedListeners(Folder oldF, Folder newF)
Notify all FolderListeners about the renaming of a folder.
void notifyStoreListeners(int type, String message)
Notify all StoreListeners.
[Expand]
Inherited Methods
From class com.google.code.javax.mail.Service
From class java.lang.Object

Fields

private Vector folderListeners

private Vector storeListeners

Protected Constructors

protected Store (Session session, URLName urlname)

Constructor.

Parameters
session Session object for this Store.
urlname URLName object to be used for this Store

Public Methods

public synchronized void addFolderListener (FolderListener l)

Add a listener for GmailFolder events on any GmailFolder object obtained from this Store. FolderEvents are delivered to FolderListeners on the affected GmailFolder 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 GmailFolder events
See Also
  • javax.mail.event.FolderEvent

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 The Listener for Store events
See Also
  • javax.mail.event.StoreEvent

public abstract Folder getDefaultFolder ()

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

Returns
  • the root GmailFolder
Throws
IllegalStateException if this Store is not connected.
MessagingException

public abstract Folder getFolder (URLName url)

Return a closed GmailFolder 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
  • GmailFolder object
Throws
IllegalStateException if this Store is not connected.
MessagingException
See Also

public abstract Folder getFolder (String name)

Return the GmailFolder object corresponding to the given name. Note that a GmailFolder 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.

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

Parameters
name The name of the GmailFolder. 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
  • GmailFolder object
Throws
IllegalStateException if this Store is not connected.
MessagingException
See Also
  • GmailFolder#exists
  • GmailFolder#create

public Folder[] getPersonalNamespaces ()

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 GmailFolder objects
Throws
IllegalStateException if this Store is not connected.
MessagingException

public Folder[] getSharedNamespaces ()

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 GmailFolder objects
Throws
IllegalStateException if this Store is not connected.
MessagingException

public Folder[] getUserNamespaces (String user)

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
Returns
  • array of GmailFolder objects
Throws
IllegalStateException if this Store is not connected.
MessagingException

public synchronized void removeFolderListener (FolderListener l)

Remove a listener for GmailFolder events.

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

Parameters
l The listener
See Also

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 The listener
See Also

Protected Methods

protected void notifyFolderListeners (int type, Folder folder)

Notify all FolderListeners. Store implementations are expected to use this method to broadcast GmailFolder 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 GmailFolder
See Also

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 GmailFolder 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.

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
message