1 /**
2 *
3 * Copyright 2003-2006 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package javax.mail;
19
20 import java.util.Vector;
21 import javax.mail.event.FolderEvent;
22 import javax.mail.event.FolderListener;
23 import javax.mail.event.StoreEvent;
24 import javax.mail.event.StoreListener;
25
26 /**
27 * Abstract class that represents a message store.
28 *
29 * @version $Rev: 421852 $ $Date: 2006-07-14 03:02:19 -0700 (Fri, 14 Jul 2006) $
30 */
31 public abstract class Store extends Service {
32 private static final Folder[] FOLDER_ARRAY = new Folder[0];
33 private final Vector folderListeners = new Vector(2);
34 private final Vector storeListeners = new Vector(2);
35
36 /**
37 * Constructor specifying session and url of this store.
38 * Subclasses MUST provide a constructor with this signature.
39 *
40 * @param session the session associated with this store
41 * @param name the URL of the store
42 */
43 protected Store(Session session, URLName name) {
44 super(session, name);
45 }
46
47 /**
48 * Retutn a Folder object that represents the root of the namespace for the current user.
49 *
50 * Note that in some store configurations (such as IMAP4) then the root folder may
51 * not be the INBOX folder.
52 *
53 * @return the root Folder
54 * @throws MessagingException if there was a problem accessing the store
55 */
56 public abstract Folder getDefaultFolder() throws MessagingException;
57
58 /**
59 * Return the Folder corresponding to the given name.
60 * The folder may not physically exist; the {@link Folder#exists()} method can be used
61 * to determine if it is real.
62 * @param name the name of the Folder to return
63 * @return the corresponding folder
64 * @throws MessagingException if there was a problem accessing the store
65 */
66 public abstract Folder getFolder(String name) throws MessagingException;
67
68 /**
69 * Return the folder identified by the URLName; the URLName must refer to this Store.
70 * Implementations may use the {@link URLName#getFile()} method to determined the folder name.
71 *
72 * @param name the folder to return
73 * @return the corresponding folder
74 * @throws MessagingException if there was a problem accessing the store
75 */
76 public abstract Folder getFolder(URLName name) throws MessagingException;
77
78 /**
79 * Return the root folders of the personal namespace belonging to the current user.
80 *
81 * The default implementation simply returns an array containing the folder returned by {@link #getDefaultFolder()}.
82 * @return the root folders of the user's peronal namespaces
83 * @throws MessagingException if there was a problem accessing the store
84 */
85 public Folder[] getPersonalNamespaces() throws MessagingException {
86 return new Folder[]{getDefaultFolder()};
87 }
88
89 /**
90 * Return the root folders of the personal namespaces belonging to the supplied user.
91 *
92 * The default implementation simply returns an empty array.
93 *
94 * @param user the user whose namespaces should be returned
95 * @return the root folders of the given user's peronal namespaces
96 * @throws MessagingException if there was a problem accessing the store
97 */
98 public Folder[] getUserNamespaces(String user) throws MessagingException {
99 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 }