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