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