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