001 /**
002 *
003 * Copyright 2003-2006 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package javax.mail;
019
020 import java.util.Vector;
021 import javax.mail.event.FolderEvent;
022 import javax.mail.event.FolderListener;
023 import javax.mail.event.StoreEvent;
024 import javax.mail.event.StoreListener;
025
026 /**
027 * Abstract class that represents a message store.
028 *
029 * @version $Rev: 421852 $ $Date: 2006-07-14 03:02:19 -0700 (Fri, 14 Jul 2006) $
030 */
031 public abstract class Store extends Service {
032 private static final Folder[] FOLDER_ARRAY = new Folder[0];
033 private final Vector folderListeners = new Vector(2);
034 private final Vector storeListeners = new Vector(2);
035
036 /**
037 * Constructor specifying session and url of this store.
038 * Subclasses MUST provide a constructor with this signature.
039 *
040 * @param session the session associated with this store
041 * @param name the URL of the store
042 */
043 protected Store(Session session, URLName name) {
044 super(session, name);
045 }
046
047 /**
048 * Retutn a Folder object that represents the root of the namespace for the current user.
049 *
050 * Note that in some store configurations (such as IMAP4) then the root folder may
051 * not be the INBOX folder.
052 *
053 * @return the root Folder
054 * @throws MessagingException if there was a problem accessing the store
055 */
056 public abstract Folder getDefaultFolder() throws MessagingException;
057
058 /**
059 * Return the Folder corresponding to the given name.
060 * The folder may not physically exist; the {@link Folder#exists()} method can be used
061 * to determine if it is real.
062 * @param name the name of the Folder to return
063 * @return the corresponding folder
064 * @throws MessagingException if there was a problem accessing the store
065 */
066 public abstract Folder getFolder(String name) throws MessagingException;
067
068 /**
069 * Return the folder identified by the URLName; the URLName must refer to this Store.
070 * Implementations may use the {@link URLName#getFile()} method to determined the folder name.
071 *
072 * @param name the folder to return
073 * @return the corresponding folder
074 * @throws MessagingException if there was a problem accessing the store
075 */
076 public abstract Folder getFolder(URLName name) throws MessagingException;
077
078 /**
079 * Return the root folders of the personal namespace belonging to the current user.
080 *
081 * The default implementation simply returns an array containing the folder returned by {@link #getDefaultFolder()}.
082 * @return the root folders of the user's peronal namespaces
083 * @throws MessagingException if there was a problem accessing the store
084 */
085 public Folder[] getPersonalNamespaces() throws MessagingException {
086 return new Folder[]{getDefaultFolder()};
087 }
088
089 /**
090 * Return the root folders of the personal namespaces belonging to the supplied user.
091 *
092 * The default implementation simply returns an empty array.
093 *
094 * @param user the user whose namespaces should be returned
095 * @return the root folders of the given user's peronal namespaces
096 * @throws MessagingException if there was a problem accessing the store
097 */
098 public Folder[] getUserNamespaces(String user) throws MessagingException {
099 return FOLDER_ARRAY;
100 }
101
102 /**
103 * Return the root folders of namespaces that are intended to be shared between users.
104 *
105 * The default implementation simply returns an empty array.
106 * @return the root folders of all shared namespaces
107 * @throws MessagingException if there was a problem accessing the store
108 */
109 public Folder[] getSharedNamespaces() throws MessagingException {
110 return FOLDER_ARRAY;
111 }
112
113
114 public void addStoreListener(StoreListener listener) {
115 storeListeners.add(listener);
116 }
117
118 public void removeStoreListener(StoreListener listener) {
119 storeListeners.remove(listener);
120 }
121
122 protected void notifyStoreListeners(int type, String message) {
123 queueEvent(new StoreEvent(this, type, message), storeListeners);
124 }
125
126
127 public void addFolderListener(FolderListener listener) {
128 folderListeners.add(listener);
129 }
130
131 public void removeFolderListener(FolderListener listener) {
132 folderListeners.remove(listener);
133 }
134
135 protected void notifyFolderListeners(int type, Folder folder) {
136 queueEvent(new FolderEvent(this, folder, type), folderListeners);
137 }
138
139 protected void notifyFolderRenamedListeners(Folder oldFolder, Folder newFolder) {
140 queueEvent(new FolderEvent(this, oldFolder, newFolder, FolderEvent.RENAMED), folderListeners);
141 }
142 }