Store


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the "License").  You may not use this file except 
5    * in compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * glassfish/bootstrap/legal/CDDLv1.0.txt or 
9    * https://glassfish.dev.java.net/public/CDDLv1.0.html. 
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * HEADER in each file and include the License file at 
15   * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable, 
16   * add the following below this CDDL HEADER, with the 
17   * fields enclosed by brackets "[]" replaced with your 
18   * own identifying information: Portions Copyright [yyyy] 
19   * [name of copyright owner]
20   */
21  
22  /*
23   * @(#)Store.java   1.27 05/08/29
24   *
25   * Copyright 1997-2005 Sun Microsystems, Inc. All Rights Reserved.
26   */
27  
28  package javax.mail;
29  
30  import java.io.*;
31  import java.net.*;
32  import java.util.*;
33  import javax.mail.event.*;
34  
35  /**
36   * An abstract class that models a message store and its
37   * access protocol, for storing and retrieving messages. 
38   * Subclasses provide actual implementations. <p>
39   *
40   * Note that <code>Store</code> extends the <code>Service</code>
41   * class, which provides many common methods for naming stores,
42   * connecting to stores, and listening to connection events.
43   *
44   * @author John Mani
45   * @author Bill Shannon
46   * @version 1.27, 05/08/29
47   *
48   * @see javax.mail.Service
49   * @see javax.mail.event.ConnectionEvent
50   * @see javax.mail.event.StoreEvent
51   */
52  
53  public abstract class Store extends Service   {
54  
55      /**
56       * Constructor.
57       *
58       * @param   session Session object for this Store.
59       * @param   urlname URLName object to be used for this Store
60       */
61      protected Store(Session   session, URLName   urlname) {
62      super(session, urlname);
63      }
64  
65      /**
66       * Returns a Folder object that represents the 'root' of
67       * the default namespace presented to the user by the Store.
68       *
69       * @return the root Folder
70       * @exception IllegalStateException if this Store is not connected.
71       */
72      public abstract Folder   getDefaultFolder() throws MessagingException  ;
73  
74      /**
75       * Return the Folder object corresponding to the given name. Note
76       * that a Folder object is returned even if the named folder does
77       * not physically exist on the Store. The <code>exists()</code> 
78       * method on the folder object indicates whether this folder really
79       * exists. <p>
80       *
81       * Folder objects are not cached by the Store, so invoking this
82       * method on the same name multiple times will return that many
83       * distinct Folder objects.
84       *
85       * @param name  The name of the Folder. In some Stores, name can
86       *          be an absolute path if it starts with the
87       *          hierarchy delimiter. Else it is interpreted
88       *          relative to the 'root' of this namespace.
89       * @return      Folder object
90       * @exception   IllegalStateException if this Store is not connected.
91       * @see         Folder#exists
92       * @see     Folder#create
93       */
94      public abstract Folder   getFolder(String   name)
95              throws MessagingException  ;
96  
97      /**
98       * Return a closed Folder object, corresponding to the given 
99       * URLName. The store specified in the given URLName should
100      * refer to this Store object. <p>
101      *
102      * Implementations of this method may obtain the name of the
103      * actual folder using the <code>getFile()</code> method on
104      * URLName, and use that name to create the folder.
105      * 
106      * @param url   URLName that denotes a folder
107      * @see         URLName
108      * @exception   IllegalStateException if this Store is not connected.
109      * @return      Folder object
110      */
111     public abstract Folder   getFolder(URLName   url)
112             throws MessagingException  ;
113 
114     /**
115      * Return a set of folders representing the <i>personal</i> namespaces
116      * for the current user.  A personal namespace is a set of names that
117      * is considered within the personal scope of the authenticated user.
118      * Typically, only the authenticated user has access to mail folders
119      * in their personal namespace.  If an INBOX exists for a user, it
120      * must appear within the user's personal namespace.  In the
121      * typical case, there should be only one personal namespace for each
122      * user in each Store. <p>
123      *
124      * This implementation returns an array with a single entry containing
125      * the return value of the <code>getDefaultFolder</code> method.
126      * Subclasses should override this method to return appropriate information.
127      *
128      * @exception   IllegalStateException if this Store is not connected.
129      * @return      array of Folder objects
130      * @since       JavaMail 1.2
131      */
132     public Folder  [] getPersonalNamespaces() throws MessagingException   {
133     return new Folder  [] { getDefaultFolder() };
134     }
135 
136     /**
137      * Return a set of folders representing the namespaces for
138      * <code>user</code>.  The namespaces returned represent the
139      * personal namespaces for the user.  To access mail folders in the
140      * other user's namespace, the currently authenticated user must be
141      * explicitly granted access rights.  For example, it is common for
142      * a manager to grant to their secretary access rights to their
143      * mail folders. <p>
144      *
145      * This implementation returns an empty array.  Subclasses should
146      * override this method to return appropriate information.
147      *
148      * @exception   IllegalStateException if this Store is not connected.
149      * @return      array of Folder objects
150      * @since       JavaMail 1.2
151      */
152     public Folder  [] getUserNamespaces(String   user)
153                 throws MessagingException   {
154     return new Folder  [0];
155     }
156 
157     /**
158      * Return a set of folders representing the <i>shared</i> namespaces.
159      * A shared namespace is a namespace that consists of mail folders
160      * that are intended to be shared amongst users and do not exist
161      * within a user's personal namespace. <p>
162      *
163      * This implementation returns an empty array.  Subclasses should
164      * override this method to return appropriate information.
165      *
166      * @exception   IllegalStateException if this Store is not connected.
167      * @return      array of Folder objects
168      * @since       JavaMail 1.2
169      */
170     public Folder  [] getSharedNamespaces() throws MessagingException   {
171     return new Folder  [0];
172     }
173 
174     // Vector of Store listeners
175     private volatile Vector storeListeners = null;
176 
177     /**
178      * Add a listener for StoreEvents on this Store. <p>
179      *
180      * The default implementation provided here adds this listener
181      * to an internal list of StoreListeners.
182      *
183      * @param l         the Listener for Store events
184      * @see             javax.mail.event.StoreEvent
185      */
186     public synchronized void addStoreListener(StoreListener l) {
187     if (storeListeners == null)
188         storeListeners = new Vector();
189     storeListeners.addElement(l);
190     }
191 
192     /**
193      * Remove a listener for Store events. <p>
194      *
195      * The default implementation provided here removes this listener
196      * from the internal list of StoreListeners.
197      *
198      * @param l         the listener
199      * @see             #addStoreListener
200      */
201     public synchronized void removeStoreListener(StoreListener l) {
202     if (storeListeners != null)
203         storeListeners.removeElement(l);
204     }
205 
206     /**
207      * Notify all StoreListeners. Store implementations are
208      * expected to use this method to broadcast StoreEvents. <p>
209      *
210      * The provided default implementation queues the event into
211      * an internal event queue. An event dispatcher thread dequeues
212      * events from the queue and dispatches them to the registered
213      * StoreListeners. Note that the event dispatching occurs
214      * in a separate thread, thus avoiding potential deadlock problems.
215      */
216     protected void notifyStoreListeners(int type, String   message) {
217     if (storeListeners == null)
218         return;
219     
220     StoreEvent e = new StoreEvent(this, type, message);
221     queueEvent(e, storeListeners);
222     }
223 
224     // Vector of folder listeners
225     private volatile Vector folderListeners = null;
226 
227     /**
228      * Add a listener for Folder events on any Folder object 
229      * obtained from this Store. FolderEvents are delivered to
230      * FolderListeners on the affected Folder as well as to 
231      * FolderListeners on the containing Store. <p>
232      *
233      * The default implementation provided here adds this listener
234      * to an internal list of FolderListeners.
235      *
236      * @param l         the Listener for Folder events
237      * @see             javax.mail.event.FolderEvent
238      */
239     public synchronized void addFolderListener(FolderListener l) {
240     if (folderListeners == null)
241         folderListeners = new Vector();
242     folderListeners.addElement(l);
243     }
244 
245     /**
246      * Remove a listener for Folder events. <p>
247      *
248      * The default implementation provided here removes this listener
249      * from the internal list of FolderListeners.
250      *
251      * @param l         the listener
252      * @see             #addFolderListener
253      */
254     public synchronized void removeFolderListener(FolderListener l) {
255     if (folderListeners != null)
256         folderListeners.removeElement(l);
257     }
258 
259     /**
260      * Notify all FolderListeners. Store implementations are
261      * expected to use this method to broadcast Folder events. <p>
262      *
263      * The provided default implementation queues the event into
264      * an internal event queue. An event dispatcher thread dequeues
265      * events from the queue and dispatches them to the registered
266      * FolderListeners. Note that the event dispatching occurs
267      * in a separate thread, thus avoiding potential deadlock problems.
268      *
269      * @param   type    type of FolderEvent
270      * @param   folder  affected Folder
271      * @see     #notifyFolderRenamedListeners
272      */
273     protected void notifyFolderListeners(int type, Folder   folder) {
274     if (folderListeners == null) 
275         return;
276     
277     FolderEvent e = new FolderEvent(this, folder, type);
278     queueEvent(e, folderListeners);
279     }
280 
281     /**
282      * Notify all FolderListeners about the renaming of a folder.
283      * Store implementations are expected to use this method to broadcast 
284      * Folder events indicating the renaming of folders. <p>
285      *
286      * The provided default implementation queues the event into
287      * an internal event queue. An event dispatcher thread dequeues
288      * events from the queue and dispatches them to the registered
289      * FolderListeners. Note that the event dispatching occurs
290      * in a separate thread, thus avoiding potential deadlock problems.
291      *
292      * @param   oldF    the folder being renamed
293      * @param   newF    the folder representing the new name.
294      * @since   JavaMail 1.1
295      */
296     protected void notifyFolderRenamedListeners(Folder   oldF, Folder   newF) {
297     if (folderListeners == null) 
298         return;
299     
300     FolderEvent e = new FolderEvent(this, oldF, newF,FolderEvent.RENAMED);
301     queueEvent(e, folderListeners);
302     }
303 }
304
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags