KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > mail > FetchProfile


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  * @(#)FetchProfile.java 1.9 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.Vector JavaDoc;
31
32 /**
33  * Clients use a FetchProfile to list the Message attributes that
34  * it wishes to prefetch from the server for a range of messages.<p>
35  *
36  * Messages obtained from a Folder are light-weight objects that
37  * typically start off as empty references to the actual messages.
38  * Such a Message object is filled in "on-demand" when the appropriate
39  * get*() methods are invoked on that particular Message. Certain
40  * server-based message access protocols (Ex: IMAP) allow batch
41  * fetching of message attributes for a range of messages in a single
42  * request. Clients that want to use message attributes for a range of
43  * Messages (Example: to display the top-level headers in a headerlist)
44  * might want to use the optimization provided by such servers. The
45  * <code>FetchProfile</code> allows the client to indicate this desire
46  * to the server. <p>
47  *
48  * Note that implementations are not obligated to support
49  * FetchProfiles, since there might be cases where the backend service
50  * does not allow easy, efficient fetching of such profiles. <p>
51  *
52  * Sample code that illustrates the use of a FetchProfile is given
53  * below: <p>
54  * <blockquote>
55  * <pre>
56  *
57  * Message[] msgs = folder.getMessages();
58  *
59  * FetchProfile fp = new FetchProfile();
60  * fp.add(FetchProfile.Item.ENVELOPE);
61  * fp.add("X-mailer");
62  * folder.fetch(msgs, fp);
63  *
64  * </pre></blockquote><p>
65  *
66  * @see javax.mail.Folder#fetch
67  * @author John Mani
68  * @author Bill Shannon
69  */

70
71 public class FetchProfile {
72
73     private Vector JavaDoc specials; // specials
74
private Vector JavaDoc headers; // vector of header names
75

76     /**
77      * This inner class is the base class of all items that
78      * can be requested in a FetchProfile. The items currently
79      * defined here are <code>ENVELOPE</code>, <code>CONTENT_INFO</code>
80      * and <code>FLAGS</code>. The <code>UIDFolder</code> interface
81      * defines the <code>UID</code> Item as well. <p>
82      *
83      * Note that this class only has a protected constructor, therby
84      * restricting new Item types to either this class or subclasses.
85      * This effectively implements a enumeration of allowed Item types.
86      *
87      * @see UIDFolder
88      */

89
90     public static class Item {
91     /**
92      * This is the Envelope item. <p>
93      *
94      * The Envelope is an aggregration of the common attributes
95      * of a Message. Implementations should include the following
96      * attributes: From, To, Cc, Bcc, ReplyTo, Subject and Date.
97      * More items may be included as well. <p>
98      *
99      * For implementations of the IMAP4 protocol (RFC 2060), the
100      * Envelope should include the ENVELOPE data item. More items
101      * may be included too.
102      */

103     public static final Item ENVELOPE = new Item("ENVELOPE");
104
105     /**
106      * This item is for fetching information about the
107      * content of the message. <p>
108      *
109      * This includes all the attributes that describe the content
110      * of the message. Implementations should include the following
111      * attributes: ContentType, ContentDisposition,
112      * ContentDescription, Size and LineCount. Other items may be
113      * included as well.
114      */

115     public static final Item CONTENT_INFO = new Item("CONTENT_INFO");
116
117     /**
118      * This is the Flags item.
119      */

120     public static final Item FLAGS = new Item("FLAGS");
121
122     private String JavaDoc name;
123
124     /**
125      * Constructor for an item. The name is used only for debugging.
126      */

127     protected Item(String JavaDoc name) {
128         this.name = name;
129     }
130     }
131
132     /**
133      * Create an empty FetchProfile.
134      */

135     public FetchProfile() {
136     specials = null;
137     headers = null;
138     }
139     
140     /**
141      * Add the given special item as one of the attributes to
142      * be prefetched.
143      *
144      * @param item the special item to be fetched
145      * @see FetchProfile.Item#ENVELOPE
146      * @see FetchProfile.Item#CONTENT_INFO
147      * @see FetchProfile.Item#FLAGS
148      */

149     public void add(Item item) {
150     if (specials == null)
151         specials = new Vector JavaDoc();
152     specials.addElement(item);
153     }
154
155     /**
156      * Add the specified header-field to the list of attributes
157      * to be prefetched.
158      *
159      * @param headerName header to be prefetched
160      */

161     public void add(String JavaDoc headerName) {
162     if (headers == null)
163         headers = new Vector JavaDoc();
164     headers.addElement(headerName);
165     }
166
167     /**
168      * Returns true if the fetch profile contains given special item.
169      */

170     public boolean contains(Item item) {
171     return specials != null && specials.contains(item);
172     }
173
174     /**
175      * Returns true if the fetch profile contains given header name.
176      */

177     public boolean contains(String JavaDoc headerName) {
178     return headers != null && headers.contains(headerName);
179     }
180
181     /**
182      * Get the items set in this profile.
183      *
184      * @return items set in this profile
185      */

186     public Item[] getItems() {
187     if (specials == null)
188         return new Item[0];
189
190     Item[] s = new Item[specials.size()];
191     specials.copyInto(s);
192     return s;
193     }
194
195     /**
196      * Get the names of the header-fields set in this profile.
197      *
198      * @return headers set in this profile
199      */

200     public String JavaDoc[] getHeaderNames() {
201     if (headers == null)
202         return new String JavaDoc[0];
203
204     String JavaDoc[] s = new String JavaDoc[headers.size()];
205     headers.copyInto(s);
206     return s;
207     }
208 }
209
Popular Tags