http://javaee.github.io/javamail/javax.mail-api: JavaMail API jar (Oracle)
  • Bill Shannon (Oracle) 
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2017 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
 * or LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

package javax.mail;

import java.io.*;
import java.net.*;
import java.util.*;
import 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.

Author:John Mani, Bill Shannon
See Also:
/**
 * An abstract class that models a message store and its
 * access protocol, for storing and retrieving messages. 
 * Subclasses provide actual implementations. <p>
 *
 * Note that <code>Store</code> extends the <code>Service</code>
 * class, which provides many common methods for naming stores,
 * connecting to stores, and listening to connection events.
 *
 * @author John Mani
 * @author Bill Shannon
 *
 * @see javax.mail.Service
 * @see javax.mail.event.ConnectionEvent
 * @see javax.mail.event.StoreEvent
 */

public abstract class Store extends Service {

    
Constructor.

Params:
  • session – Session object for this Store.
  • urlname – 	URLName object to be used for this Store
/**
     * Constructor.
     *
     * @param	session Session object for this Store.
     * @param	urlname	URLName object to be used for this Store
     */
    protected Store(Session session, URLName urlname) {
	super(session, urlname);
    }

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

Throws:
Returns:the root Folder
/**
     * Returns a Folder object that represents the 'root' of
     * the default namespace presented to the user by the Store.
     *
     * @return the root Folder
     * @exception	IllegalStateException if this Store is not connected.
     * @exception 	MessagingException for other failures
     */
    public abstract Folder getDefaultFolder() 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.

Params:
  • 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.
Throws:
See Also:
Returns:		Folder object
/**
     * 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 <code>exists()</code> 
     * method on the folder object indicates whether this folder really
     * exists. <p>
     *
     * 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.
     *
     * @param 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.
     * @return		Folder object
     * @exception 	IllegalStateException if this Store is not connected.
     * @exception 	MessagingException for other failures
     * @see 		Folder#exists
     * @see		Folder#create
     */
    public abstract Folder getFolder(String name)
			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.

Params:
  • url – 	URLName that denotes a folder
Throws:
See Also:
Returns:		Folder object
/**
     * Return a closed Folder object, corresponding to the given 
     * URLName. The store specified in the given URLName should
     * refer to this Store object. <p>
     *
     * Implementations of this method may obtain the name of the
     * actual folder using the <code>getFile()</code> method on
     * URLName, and use that name to create the folder.
     * 
     * @param url	URLName that denotes a folder
     * @return		Folder object
     * @exception 	IllegalStateException if this Store is not connected.
     * @exception 	MessagingException for other failures
     * @see 		URLName
     */
    public abstract Folder getFolder(URLName url)
			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.

Throws:
Returns:		array of Folder objects
Since:		JavaMail 1.2
/**
     * Return a set of folders representing the <i>personal</i> 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. <p>
     *
     * This implementation returns an array with a single entry containing
     * the return value of the <code>getDefaultFolder</code> method.
     * Subclasses should override this method to return appropriate information.
     *
     * @return		array of Folder objects
     * @exception 	IllegalStateException if this Store is not connected.
     * @exception 	MessagingException for other failures
     * @since		JavaMail 1.2
     */
    public Folder[] getPersonalNamespaces() throws MessagingException {
	return new Folder[] { getDefaultFolder() };
    }

    
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.

Params:
  • user – 	the user name
Throws:
Returns:		array of Folder objects
Since:		JavaMail 1.2
/**
     * Return a set of folders representing the namespaces for
     * <code>user</code>.  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. <p>
     *
     * This implementation returns an empty array.  Subclasses should
     * override this method to return appropriate information.
     *
     * @param	user	the user name
     * @return		array of Folder objects
     * @exception 	IllegalStateException if this Store is not connected.
     * @exception 	MessagingException for other failures
     * @since		JavaMail 1.2
     */
    public Folder[] getUserNamespaces(String user)
				throws MessagingException {
	return new Folder[0];
    }

    
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.

Throws:
  • IllegalStateException – if this Store is not connected.
  • MessagingException – for other failures
Returns:		array of Folder objects
Since:		JavaMail 1.2
/**
     * Return a set of folders representing the <i>shared</i> 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. <p>
     *
     * This implementation returns an empty array.  Subclasses should
     * override this method to return appropriate information.
     *
     * @exception 	IllegalStateException if this Store is not connected.
     * @exception 	MessagingException for other failures
     * @return		array of Folder objects
     * @since		JavaMail 1.2
     */
    public Folder[] getSharedNamespaces() throws MessagingException {
	return new Folder[0];
    }

    // Vector of Store listeners
    private volatile Vector<StoreListener> storeListeners = null;

    
Add a listener for StoreEvents on this Store. 

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

Params:
  • l –         the Listener for Store events
See Also:
/**
     * Add a listener for StoreEvents on this Store. <p>
     *
     * The default implementation provided here adds this listener
     * to an internal list of StoreListeners.
     *
     * @param l         the Listener for Store events
     * @see             javax.mail.event.StoreEvent
     */
    public synchronized void addStoreListener(StoreListener l) {
	if (storeListeners == null)
	    storeListeners = new Vector<>();
	storeListeners.addElement(l);
    }

    
Remove a listener for Store events. 

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

Params:
  • l –         the listener
See Also:
/**
     * Remove a listener for Store events. <p>
     *
     * The default implementation provided here removes this listener
     * from the internal list of StoreListeners.
     *
     * @param l         the listener
     * @see             #addStoreListener
     */
    public synchronized void removeStoreListener(StoreListener l) {
	if (storeListeners != null)
	    storeListeners.removeElement(l);
    }

    
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.

Params:
  • type – 	the StoreEvent type
  • message – 	a message for the StoreEvent
/**
     * Notify all StoreListeners. Store implementations are
     * expected to use this method to broadcast StoreEvents. <p>
     *
     * 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.
     *
     * @param	type	the StoreEvent type
     * @param	message	a message for the StoreEvent
     */
    protected void notifyStoreListeners(int type, String message) {
   	if (storeListeners == null)
	    return;
	
	StoreEvent e = new StoreEvent(this, type, message);
	queueEvent(e, storeListeners);
    }

    // Vector of folder listeners
    private volatile Vector<FolderListener> folderListeners = null;

    
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.

Params:
  • l –         the Listener for Folder events
See Also:
/**
     * 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. <p>
     *
     * The default implementation provided here adds this listener
     * to an internal list of FolderListeners.
     *
     * @param l         the Listener for Folder events
     * @see             javax.mail.event.FolderEvent
     */
    public synchronized void addFolderListener(FolderListener l) {
   	if (folderListeners == null)
	    folderListeners = new Vector<>();
	folderListeners.addElement(l);
    }

    
Remove a listener for Folder events. 

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

Params:
  • l –         the listener
See Also:
/**
     * Remove a listener for Folder events. <p>
     *
     * The default implementation provided here removes this listener
     * from the internal list of FolderListeners.
     *
     * @param l         the listener
     * @see             #addFolderListener
     */
    public synchronized void removeFolderListener(FolderListener l) {
   	if (folderListeners != null)
	    folderListeners.removeElement(l);
    }

    
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.

Params:
  • type – 	type of FolderEvent
  • folder – 	affected Folder
See Also:
/**
     * Notify all FolderListeners. Store implementations are
     * expected to use this method to broadcast Folder events. <p>
     *
     * 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.
     *
     * @param	type	type of FolderEvent
     * @param	folder	affected Folder
     * @see		#notifyFolderRenamedListeners
     */
    protected void notifyFolderListeners(int type, Folder folder) {
   	if (folderListeners == null) 
	    return;
	
	FolderEvent e = new FolderEvent(this, folder, type);
	queueEvent(e, folderListeners);
    }

    
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.

Params:
  • oldF – 	the folder being renamed
  • newF – 	the folder representing the new name.
Since:	JavaMail 1.1
/**
     * 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. <p>
     *
     * 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.
     *
     * @param	oldF	the folder being renamed
     * @param	newF	the folder representing the new name.
     * @since	JavaMail 1.1
     */
    protected void notifyFolderRenamedListeners(Folder oldF, Folder newF) {
   	if (folderListeners == null) 
	    return;
	
	FolderEvent e = new FolderEvent(this, oldF, newF,FolderEvent.RENAMED);
	queueEvent(e, folderListeners);
    }
}