1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can obtain
10 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
12 * language governing permissions and limitations under the License.
13 *
14 * When distributing the software, include this License Header Notice in each
15 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
16 * Sun designates this particular file as subject to the "Classpath" exception
17 * as provided by Sun in the GPL Version 2 section of the License file that
18 * accompanied this code. If applicable, add the following below the License
19 * Header, with the fields enclosed by brackets [] replaced by your own
20 * identifying information: "Portions Copyrighted [year]
21 * [name of copyright owner]"
22 *
23 * Contributor(s):
24 *
25 * If you wish your version of this file to be governed by only the CDDL or
26 * only the GPL Version 2, indicate your decision by adding "[Contributor]
27 * elects to include this software in this distribution under the [CDDL or GPL
28 * Version 2] license." If you don't indicate a single choice of license, a
29 * recipient has the option to distribute your version of this file under
30 * either the CDDL, the GPL Version 2 or to extend the choice of license to
31 * its licensees as provided above. However, if you add GPL Version 2 code
32 * and therefore, elected the GPL Version 2 license, then the option applies
33 * only if the new code is made subject to such option by the copyright
34 * holder.
35 */
36
37 /*
38 * @(#)UIDFolder.java 1.14 07/05/04
39 */
40
41 package javax.mail;
42
43 import java.util.NoSuchElementException;
44
45 /**
46 * The <code>UIDFolder</code> interface is implemented by Folders
47 * that can support the "disconnected" mode of operation, by providing
48 * unique-ids for messages in the folder. This interface is based on
49 * the IMAP model for supporting disconnected operation. <p>
50 *
51 * A Unique identifier (UID) is a positive long value, assigned to
52 * each message in a specific folder. Unique identifiers are assigned
53 * in a strictly <strong>ascending</strong> fashion in the mailbox.
54 * That is, as each message is added to the mailbox it is assigned a
55 * higher UID than the message(s) which were added previously. Unique
56 * identifiers persist across sessions. This permits a client to
57 * resynchronize its state from a previous session with the server. <p>
58 *
59 * Associated with every mailbox is a unique identifier validity value.
60 * If unique identifiers from an earlier session fail to persist to
61 * this session, the unique identifier validity value
62 * <strong>must</strong> be greater than the one used in the earlier
63 * session. <p>
64 *
65 * Refer to RFC 2060 <A HREF="http://www.ietf.org/rfc/rfc2060.txt">
66 * http://www.ietf.org/rfc/rfc2060.txt</A> for more information.
67 *
68 * @author John Mani
69 */
70
71 public interface UIDFolder {
72
73 /**
74 * A fetch profile item for fetching UIDs.
75 * This inner class extends the <code>FetchProfile.Item</code>
76 * class to add new FetchProfile item types, specific to UIDFolders.
77 * The only item currently defined here is the <code>UID</code> item.
78 *
79 * @see FetchProfile
80 */
81 public static class FetchProfileItem extends FetchProfile.Item {
82 protected FetchProfileItem(String name) {
83 super(name);
84 }
85
86 /**
87 * UID is a fetch profile item that can be included in a
88 * <code>FetchProfile</code> during a fetch request to a Folder.
89 * This item indicates that the UIDs for messages in the specified
90 * range are desired to be prefetched. <p>
91 *
92 * An example of how a client uses this is below: <p>
93 * <blockquote><pre>
94 *
95 * FetchProfile fp = new FetchProfile();
96 * fp.add(UIDFolder.FetchProfileItem.UID);
97 * folder.fetch(msgs, fp);
98 *
99 * </pre></blockquote><p>
100 */
101 public static final FetchProfileItem UID =
102 new FetchProfileItem("UID");
103 }
104
105 /**
106 * This is a special value that can be used as the <code>end</code>
107 * parameter in <code>getMessagesByUID(start, end)</code>, to denote the
108 * UID of the last message in the folder.
109 *
110 * @see #getMessagesByUID
111 */
112 public final static long LASTUID = -1;
113
114 /**
115 * Returns the UIDValidity value associated with this folder. <p>
116 *
117 * Clients typically compare this value against a UIDValidity
118 * value saved from a previous session to insure that any cached
119 * UIDs are not stale.
120 *
121 * @return UIDValidity
122 */
123 public long getUIDValidity() throws MessagingException;
124
125 /**
126 * Get the Message corresponding to the given UID. If no such
127 * message exists, <code>null</code> is returned.
128 *
129 * @param uid UID for the desired message
130 * @return the Message object. <code>null</code> is returned
131 * if no message corresponding to this UID is obtained.
132 * @exception MessagingException
133 */
134 public Message getMessageByUID(long uid) throws MessagingException;
135
136 /**
137 * Get the Messages specified by the given range. The special
138 * value LASTUID can be used for the <code>end</code> parameter
139 * to indicate the UID of the last message in the folder.
140 *
141 * @param start start UID
142 * @param end end UID
143 * @return array of Message objects
144 * @exception MessagingException
145 * @see #LASTUID
146 */
147 public Message[] getMessagesByUID(long start, long end)
148 throws MessagingException;
149
150 /**
151 * Get the Messages specified by the given array of UIDs. If any UID is
152 * invalid, <code>null</code> is returned for that entry. <p>
153 *
154 * Note that the returned array will be of the same size as the specified
155 * array of UIDs, and <code>null</code> entries may be present in the
156 * array to indicate invalid UIDs.
157 *
158 * @param uids array of UIDs
159 * @return array of Message objects
160 * @exception MessagingException
161 */
162 public Message[] getMessagesByUID(long[] uids)
163 throws MessagingException;
164
165 /**
166 * Get the UID for the specified message. Note that the message
167 * <strong>must</strong> belong to this folder. Otherwise
168 * java.util.NoSuchElementException is thrown.
169 *
170 * @param message Message from this folder
171 * @return UID for this message
172 * @exception NoSuchElementException if the given Message
173 * is not in this Folder.
174 */
175 public long getUID(Message message) throws MessagingException;
176 }
Save This Page