Package: UIDFolder$FetchProfileItem

UIDFolder$FetchProfileItem

name	instruction	branch	complexity	line	method
UIDFolder.FetchProfileItem(String)	M: 4 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 2 C: 0 0%	M: 1 C: 0 0%
static {...}	M: 6 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%

Coverage

1: /*
2: * Copyright (c) 1997, 2021 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><p>
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: public static 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: public static final 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><p>
113: *
114: * @since JavaMail 1.6
115: */
116: public static final 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: * @exception        MessagingException for failures
127: */
128: public 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: * @exception        MessagingException for failures
138: */
139: public 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: * @exception        MessagingException for failures
156: * @see                 #LASTUID
157: */
158: public 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: * @exception        MessagingException for failures
172: */
173: public 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: * @exception        NoSuchElementException if the given Message
184: *                        is not in this Folder.
185: * @exception        MessagingException for other failures
186: */
187: public 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. <p>
200: *
201: * @return                the UIDNEXT value, or -1 if unknown
202: * @exception        MessagingException for failures
203: * @since                JavaMail 1.6
204: */
205: public long getUIDNext() throws MessagingException;
206: }