/[classpathx]/mail/source/javax/mail/FetchProfile.java
ViewVC logotype

Contents of /mail/source/javax/mail/FetchProfile.java

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.8 - (show annotations) (download)
Thu Dec 9 17:22:12 2004 UTC (19 years, 5 months ago) by dog
Branch: MAIN
Changes since 1.7: +25 -25 lines
2004-12-08  Chris Burdess  <dog@bluezoo.org>

        * Makefile.am: Fixed relative META-INF.
        * all: Reformatted according to GNU Classpath guidelines.

1 /*
2 * FetchProfile.java
3 * Copyright(C) 2002 The Free Software Foundation
4 *
5 * This file is part of GNU JavaMail, a library.
6 *
7 * GNU JavaMail is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 *(at your option) any later version.
11 *
12 * GNU JavaMail is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this library; if not, write to the Free Software
19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 *
21 * As a special exception, if you link this library with other files to
22 * produce an executable, this library does not by itself cause the
23 * resulting executable to be covered by the GNU General Public License.
24 * This exception does not however invalidate any other reasons why the
25 * executable file might be covered by the GNU General Public License.
26 */
27
28 package javax.mail;
29
30 import java.util.ArrayList;
31
32 /**
33 * Clients use a FetchProfile to list the Message attributes that it
34 * wishes to prefetch from the server for a range of messages.
35 * <p>
36 * Messages obtained from a Folder are light-weight objects that typically
37 * start off as empty references to the actual messages. Such a Message
38 * object is filled in "on-demand" when the appropriate get*() methods are
39 * invoked on that particular Message. Certain server-based message access
40 * protocols(Ex: IMAP) allow batch fetching of message attributes for a
41 * range of messages in a single request. Clients that want to use message
42 * attributes for a range of Messages(Example: to display the top-level
43 * headers in a headerlist) might want to use the optimization provided by
44 * such servers. The FetchProfile allows the client to indicate this desire
45 * to the server.
46 * <p>
47 * Note that implementations are not obligated to support FetchProfiles, since
48 * there might be cases where the backend service does not allow easy,
49 * efficient fetching of such profiles.
50 * <p>
51 * Sample code that illustrates the use of a FetchProfile is given below:
52 * <pre>
53 Message[] msgs = folder.getMessages();
54
55 FetchProfile fp = new FetchProfile();
56 fp.add(FetchProfile.Item.ENVELOPE);
57 fp.add("X-mailer");
58 folder.fetch(msgs, fp);
59 </pre>
60 *
61 * @author <a href="mailto:dog@gnu.org">Chris Burdess</a>
62 * @version 1.3
63 */
64 public class FetchProfile
65 {
66
67 /**
68 * This inner class is the base class of all items that can be requested
69 * in a FetchProfile. The items currently defined here are ENVELOPE,
70 * CONTENT_INFO and FLAGS. The UIDFolder interface defines the UID Item
71 * as well.
72 * <p>
73 * Note that this class only has a protected constructor, thereby
74 * restricting new Item types to either this class or subclasses.
75 * This effectively implements an enumeration of allowed Item types.
76 */
77 public static class Item
78 {
79
80 /**
81 * This is the Envelope item.
82 * <p>
83 * The Envelope is an aggregration of the common attributes of a Message.
84 * Implementations should include the following attributes:
85 * From, To, Cc, Bcc, ReplyTo, Subject and Date.
86 * More items may be included as well.
87 * <p>
88 * For implementations of the IMAP4 protocol(RFC 2060),
89 * the Envelope should include the ENVELOPE data item.
90 * More items may be included too.
91 */
92 public static final Item ENVELOPE = new Item("ENVELOPE");
93
94 /**
95 * This item is for fetching information about the content of the message.
96 * <p>
97 * This includes all the attributes that describe the content of the
98 * message.
99 * Implementations should include the following attributes:
100 * ContentType, ContentDisposition, ContentDescription, Size and LineCount.
101 * Other items may be included as well.
102 */
103 public static final Item CONTENT_INFO = new Item("CONTENT_INFO");
104
105 /**
106 * This is the Flags item.
107 */
108 public static final Item FLAGS = new Item("FLAGS");
109
110 private String name;
111
112 protected Item(String name)
113 {
114 this.name = name;
115 }
116
117 public String toString()
118 {
119 return name;
120 }
121
122 }
123
124
125 private ArrayList items = null;
126 private ArrayList headers = null;
127
128 /**
129 * Create an empty FetchProfile.
130 */
131 public FetchProfile()
132 {
133 }
134
135 /**
136 * Add the given special item as one of the attributes to be prefetched.
137 * @param item the special item to be fetched
138 */
139 public void add(Item item)
140 {
141 if (items == null)
142 {
143 items = new ArrayList();
144 }
145 synchronized (items)
146 {
147 items.add(item);
148 }
149 }
150
151 /**
152 * Add the specified header-field to the list of attributes to be prefetched.
153 * @param header the header to be prefetched
154 */
155 public void add(String header)
156 {
157 if (headers == null)
158 {
159 headers = new ArrayList();
160 }
161 synchronized (headers)
162 {
163 headers.add(header);
164 }
165 }
166
167 /**
168 * Returns true if the fetch profile contains given special item.
169 */
170 public boolean contains(Item item)
171 {
172 return (items != null && items.contains(item));
173 }
174
175 /**
176 * Returns true if the fetch profile contains the given header name.
177 */
178 public boolean contains(String header)
179 {
180 return (headers!=null && headers.contains(header));
181 }
182
183 /**
184 * Get the items set in this profile.
185 */
186 public Item[] getItems()
187 {
188 if (items == null)
189 {
190 return new Item[0];
191 }
192 synchronized (items)
193 {
194 Item[] i = new Item[items.size()];
195 items.toArray(i);
196 return i;
197 }
198 }
199
200 /**
201 * Get the names of the header-fields set in this profile.
202 */
203 public String[] getHeaderNames()
204 {
205 if (headers == null)
206 {
207 return new String[0];
208 }
209 synchronized (headers)
210 {
211 String[] h = new String[headers.size()];
212 headers.toArray(h);
213 return h;
214 }
215 }
216
217 }

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26