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 |
} |