KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > mail > UIDFolder


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  * @(#)UIDFolder.java 1.11 05/08/29
24  *
25  * Copyright 1997-2005 Sun Microsystems, Inc. All Rights Reserved.
26  */
27
28 package javax.mail;
29
30 import java.util.NoSuchElementException JavaDoc;
31
32 /**
33  * The <code>UIDFolder</code> interface is implemented by Folders
34  * that can support the "disconnected" mode of operation, by providing
35  * unique-ids for messages in the folder. This interface is based on
36  * the IMAP model for supporting disconnected operation. <p>
37  *
38  * A Unique identifier (UID) is a positive long value, assigned to
39  * each message in a specific folder. Unique identifiers are assigned
40  * in a strictly <strong>ascending</strong> fashion in the mailbox.
41  * That is, as each message is added to the mailbox it is assigned a
42  * higher UID than the message(s) which were added previously. Unique
43  * identifiers persist across sessions. This permits a client to
44  * resynchronize its state from a previous session with the server. <p>
45  *
46  * Associated with every mailbox is a unique identifier validity value.
47  * If unique identifiers from an earlier session fail to persist to
48  * this session, the unique identifier validity value
49  * <strong>must</strong> be greater than the one used in the earlier
50  * session. <p>
51  *
52  * Refer to RFC 2060 <A HREF="http://www.ietf.org/rfc/rfc2060.txt">
53  * http://www.ietf.org/rfc/rfc2060.txt</A> for more information.
54  *
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 JavaDoc {
69     protected FetchProfileItem(String JavaDoc 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: <p>
80      * <blockquote><pre>
81      *
82      * FetchProfile fp = new FetchProfile();
83      * fp.add(UIDFolder.FetchProfileItem.UID);
84      * folder.fetch(msgs, fp);
85      *
86      * </pre></blockquote><p>
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>getMessages(start, end)</code>, to denote the
95      * last UID in this folder.
96      *
97      * @see #getMessagesByUID
98      */
99     public final static long LASTUID = -1;
100
101     /**
102      * Returns the UIDValidity value associated with this folder. <p>
103      *
104      * Clients typically compare this value against a UIDValidity
105      * value saved from a previous session to insure that any cached
106      * UIDs are not stale.
107      *
108      * @return UIDValidity
109      */
110     public long getUIDValidity() throws MessagingException JavaDoc;
111
112     /**
113      * Get the Message corresponding to the given UID. If no such
114      * message exists, <code>null</code> is returned.
115      *
116      * @param uid UID for the desired message
117      * @return the Message object. <code>null</code> is returned
118      * if no message corresponding to this UID is obtained.
119      * @exception MessagingException
120      */
121     public Message JavaDoc getMessageByUID(long uid) throws MessagingException JavaDoc;
122
123     /**
124      * Get the Messages specified by the given range. The special
125      * value LASTUID can be used for the <code>end</code> parameter
126      * to indicate the last available UID.
127      *
128      * @param start start UID
129      * @param end end UID
130      * @return array of Message objects
131      * @exception MessagingException
132      * @see #LASTUID
133      */
134     public Message JavaDoc[] getMessagesByUID(long start, long end)
135                 throws MessagingException JavaDoc;
136
137     /**
138      * Get the Messages specified by the given array of UIDs. If any UID is
139      * invalid, <code>null</code> is returned for that entry. <p>
140      *
141      * Note that the returned array will be of the same size as the specified
142      * array of UIDs, and <code>null</code> entries may be present in the
143      * array to indicate invalid UIDs.
144      *
145      * @param uids array of UIDs
146      * @return array of Message objects
147      * @exception MessagingException
148      */
149     public Message JavaDoc[] getMessagesByUID(long[] uids)
150                 throws MessagingException JavaDoc;
151
152     /**
153      * Get the UID for the specified message. Note that the message
154      * <strong>must</strong> belong to this folder. Otherwise
155      * java.util.NoSuchElementException is thrown.
156      *
157      * @param message Message from this folder
158      * @return UID for this message
159      * @exception NoSuchElementException if the given Message
160      * is not in this Folder.
161      */
162     public long getUID(Message JavaDoc message) throws MessagingException JavaDoc;
163 }
164
Popular Tags