Package: UIDFolder

UIDFolder

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 java.util.NoSuchElementException;
20:
21: /**
22: * The <code>UIDFolder</code> interface is implemented by Folders
23: * that can support the "disconnected" mode of operation, by providing
24: * unique-ids for messages in the folder. This interface is based on
25: * the IMAP model for supporting disconnected operation. <p>
26: *
27: * A Unique identifier (UID) is a positive long value, assigned to
28: * each message in a specific folder. Unique identifiers are assigned
29: * in a strictly <strong>ascending</strong> fashion in the mailbox.
30: * That is, as each message is added to the mailbox it is assigned a
31: * higher UID than the message(s) which were added previously. Unique
32: * identifiers persist across sessions. This permits a client to
33: * resynchronize its state from a previous session with the server. <p>
34: *
35: * Associated with every mailbox is a unique identifier validity value.
36: * If unique identifiers from an earlier session fail to persist to
37: * this session, the unique identifier validity value
38: * <strong>must</strong> be greater than the one used in the earlier
39: * session. <p>
40: *
41: * Refer to <A HREF="http://www.ietf.org/rfc/rfc2060.txt">RFC 2060</A>
42: * for more information.
43: *
44: * All the Folder objects returned by the default IMAP provider implement
45: * the UIDFolder interface. Use it as follows:
46: * <blockquote><pre>
47: *
48: *         Folder f = store.getFolder("whatever");
49: *         UIDFolder uf = (UIDFolder)f;
50: *         long uid = uf.getUID(msg);
51: *
52: * </pre></blockquote>
53: *
54: * @author Bill Shannon
55: * @author John Mani
56: */
57:
58: public interface UIDFolder {
59:
60: /**
61: * A fetch profile item for fetching UIDs.
62: * This inner class extends the <code>FetchProfile.Item</code>
63: * class to add new FetchProfile item types, specific to UIDFolders.
64: * The only item currently defined here is the <code>UID</code> item.
65: *
66: * @see FetchProfile
67: */
68: class FetchProfileItem extends FetchProfile.Item {
69: protected FetchProfileItem(String name) {
70: super(name);
71: }
72:
73: /**
74: * UID is a fetch profile item that can be included in a
75: * <code>FetchProfile</code> during a fetch request to a Folder.
76: * This item indicates that the UIDs for messages in the specified
77: * range are desired to be prefetched. <p>
78: *
79: * An example of how a client uses this is below:
80: * <blockquote><pre>
81: *
82: *         FetchProfile fp = new FetchProfile();
83: *         fp.add(UIDFolder.FetchProfileItem.UID);
84: *         folder.fetch(msgs, fp);
85: *
86: * </pre></blockquote>
87: */
88: public static final FetchProfileItem UID =
89: new FetchProfileItem("UID");
90: }
91:
92: /**
93: * This is a special value that can be used as the <code>end</code>
94: * parameter in <code>getMessagesByUID(start, end)</code>, to denote the
95: * UID of the last message in the folder.
96: *
97: * @see #getMessagesByUID
98: */
99: long LASTUID = -1;
100:
101: /**
102: * The largest value possible for a UID, a 32-bit unsigned integer.
103: * This can be used to fetch all new messages by keeping track of the
104: * last UID that was seen and using:
105: * <blockquote><pre>
106: *
107: *         Folder f = store.getFolder("whatever");
108: *         UIDFolder uf = (UIDFolder)f;
109: *         Message[] newMsgs =
110: *                 uf.getMessagesByUID(lastSeenUID + 1, UIDFolder.MAXUID);
111: *
112: * </pre></blockquote>
113: *
114: * @since JavaMail 1.6
115: */
116: long MAXUID = 0xffffffffL; // max 32-bit unsigned int
117:
118: /**
119: * Returns the UIDValidity value associated with this folder. <p>
120: *
121: * Clients typically compare this value against a UIDValidity
122: * value saved from a previous session to insure that any cached
123: * UIDs are not stale.
124: *
125: * @return UIDValidity
126: * @throws MessagingException for failures
127: */
128: long getUIDValidity() throws MessagingException;
129:
130: /**
131: * Get the Message corresponding to the given UID. If no such
132: * message exists, <code>null</code> is returned.
133: *
134: * @param uid UID for the desired message
135: * @return the Message object. <code>null</code> is returned
136: * if no message corresponding to this UID is obtained.
137: * @throws MessagingException for failures
138: */
139: Message getMessageByUID(long uid) throws MessagingException;
140:
141: /**
142: * Get the Messages specified by the given range. The special
143: * value LASTUID can be used for the <code>end</code> parameter
144: * to indicate the UID of the last message in the folder. <p>
145: *
146: * Note that <code>end</code> need not be greater than <code>start</code>
147: * the order of the range doesn't matter.
148: * Note also that, unless the folder is empty, use of LASTUID ensures
149: * that at least one message will be returned - the last message in the
150: * folder.
151: *
152: * @param start start UID
153: * @param end end UID
154: * @return array of Message objects
155: * @throws MessagingException for failures
156: * @see #LASTUID
157: */
158: Message[] getMessagesByUID(long start, long end)
159: throws MessagingException;
160:
161: /**
162: * Get the Messages specified by the given array of UIDs. If any UID is
163: * invalid, <code>null</code> is returned for that entry. <p>
164: *
165: * Note that the returned array will be of the same size as the specified
166: * array of UIDs, and <code>null</code> entries may be present in the
167: * array to indicate invalid UIDs.
168: *
169: * @param uids array of UIDs
170: * @return array of Message objects
171: * @throws MessagingException for failures
172: */
173: Message[] getMessagesByUID(long[] uids)
174: throws MessagingException;
175:
176: /**
177: * Get the UID for the specified message. Note that the message
178: * <strong>must</strong> belong to this folder. Otherwise
179: * java.util.NoSuchElementException is thrown.
180: *
181: * @param message Message from this folder
182: * @return UID for this message
183: * @throws NoSuchElementException if the given Message
184: * is not in this Folder.
185: * @throws MessagingException for other failures
186: */
187: long getUID(Message message) throws MessagingException;
188:
189: /**
190: * Returns the predicted UID that will be assigned to the
191: * next message that is appended to this folder.
192: * Messages might be appended to the folder after this value
193: * is retrieved, causing this value to be out of date.
194: * This value might only be updated when a folder is first opened.
195: * Note that messages may have been appended to the folder
196: * while it was open and thus this value may be out of
197: * date. <p>
198: *
199: * If the value is unknown, -1 is returned.
200: *
201: * @return the UIDNEXT value, or -1 if unknown
202: * @throws MessagingException for failures
203: * @since JavaMail 1.6
204: */
205: long getUIDNext() throws MessagingException;
206: }