KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > gnu > mail > providers > pop3 > POP3Folder


1 /*
2  * POP3Folder.java
3  * Copyright (C) 1999, 2003 Chris Burdess <dog@gnu.org>
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * You also have permission to link it with the Sun Microsystems, Inc.
11  * JavaMail(tm) extension and run that combination.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with this library; if not, write to the Free Software
20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21  */
22 package gnu.mail.providers.pop3;
23
24 import java.util.ArrayList JavaDoc;
25 import java.util.HashMap JavaDoc;
26 import java.util.Iterator JavaDoc;
27 import java.util.List JavaDoc;
28 import java.util.Map JavaDoc;
29 import javax.mail.FetchProfile JavaDoc;
30 import javax.mail.Flags JavaDoc;
31 import javax.mail.Folder JavaDoc;
32 import javax.mail.IllegalWriteException JavaDoc;
33 import javax.mail.Message JavaDoc;
34 import javax.mail.MessagingException JavaDoc;
35 import javax.mail.Store JavaDoc;
36 import javax.mail.event.ConnectionEvent JavaDoc;
37
38 /**
39  * The folder class implementing the POP3 mail protocol.
40  *
41  * @author <a HREF='mailto:dog@dog.net.uk'>Chris Burdess</a>
42  * @author <a HREF='mailto:nferrier@tapsellferrier.co.uk'>Nic Ferrier</a>
43  * @version 1.2
44  */
45 public final class POP3Folder
46      extends Folder JavaDoc
47 {
48
49     Map JavaDoc messages = new HashMap JavaDoc();
50     boolean readonly = false, open = false;
51     int type;
52
53     Folder JavaDoc inbox;
54
55
56     /**
57      * Constructor.
58      *
59      * @param store Description of Parameter
60      * @param type Description of Parameter
61      */
62     protected POP3Folder(Store JavaDoc store, int type)
63     {
64         super(store);
65         this.type = type;
66     }
67
68
69     /**
70      * Returns the name of this folder.
71      *
72      * @return name
73      */
74     public String JavaDoc getName()
75     {
76         switch (type) {
77             case HOLDS_FOLDERS:
78                 return "/";
79             case HOLDS_MESSAGES:
80                 return "INBOX";
81             default:
82                 return "(Unknown)";
83         }
84     }
85
86
87     /**
88      * Returns the full name of this folder.
89      *
90      * @return full name
91      */
92     public String JavaDoc getFullName()
93     {
94         return getName();
95     }
96
97
98     /**
99      * Returns the type of this folder.
100      *
101      * @return type
102      * @exception MessagingException if a messaging error occurred
103      */
104     public int getType()
105         throws MessagingException JavaDoc
106     {
107         return type;
108     }
109
110
111     /**
112      * Indicates whether this folder exists.
113      *
114      * @return Description of the Returned Value
115      * @exception MessagingException if a messaging error occurred
116      */
117     public boolean exists()
118         throws MessagingException JavaDoc
119     {
120         return (type == HOLDS_MESSAGES);
121     }
122
123
124     /**
125      * Indicates whether this folder contains new messages.
126      *
127      * @return Description of the Returned Value
128      * @exception MessagingException if a messaging error occurred
129      */
130     public boolean hasNewMessages()
131         throws MessagingException JavaDoc
132     {
133         return getNewMessageCount() > 0;
134     }
135
136
137     /**
138      * Opens this folder.
139      *
140      * @param mode Description of Parameter
141      * @exception MessagingException if a messaging error occurred
142      */
143     public void open(int mode)
144         throws MessagingException JavaDoc
145     {
146         switch (mode) {
147             case READ_WRITE:
148                 readonly = false;
149                 break;
150             case READ_ONLY:
151                 readonly = true;
152                 break;
153         }
154         open = true;
155         notifyConnectionListeners(ConnectionEvent.OPENED);
156     }
157
158
159     /**
160      * Closes this folder.
161      *
162      * @param expunge if the folder is to be expunged before it is closed
163      * @exception MessagingException if a messaging error occurred
164      */
165     public void close(boolean expunge)
166         throws MessagingException JavaDoc
167     {
168         if (!open) {
169             throw new MessagingException JavaDoc("Folder is not open");
170         }
171         if (expunge) {
172             expunge();
173         }
174         open = false;
175         notifyConnectionListeners(ConnectionEvent.CLOSED);
176     }
177
178
179     /**
180      * Expunges this folder.
181      * This deletes all the messages marked as deleted.
182      *
183      * @return Description of the Returned Value
184      * @exception MessagingException if a messaging error occurred
185      */
186     public Message JavaDoc[] expunge()
187         throws MessagingException JavaDoc
188     {
189         if (!open) {
190             throw new MessagingException JavaDoc("Folder is not open");
191         }
192         if (readonly) {
193             throw new MessagingException JavaDoc("Folder was opened read-only");
194         }
195         POP3Store pstore = (POP3Store) store;
196         List JavaDoc acc = new ArrayList JavaDoc(messages.size());
197         for (Iterator JavaDoc i = messages.values().iterator(); i.hasNext(); ) {
198             Message JavaDoc message = (Message JavaDoc) i.next();
199             Flags JavaDoc flags = message.getFlags();
200             if (flags.contains(Flags.Flag.DELETED)) {
201                 acc.add(message);
202                 pstore.delete(message.getMessageNumber());
203             }
204         }
205         messages.clear();
206
207         Message JavaDoc[] d = new Message JavaDoc[acc.size()];
208         acc.toArray(d);
209         
210         return d;
211     }
212
213
214     /**
215      * Indicates whether this folder is open.
216      *
217      * @return open
218      */
219     public boolean isOpen()
220     {
221         return open;
222     }
223
224
225     /**
226      * Returns the permanent flags for this folder.
227      *
228      * @return permanent flags
229      */
230     public Flags JavaDoc getPermanentFlags()
231     {
232         return new Flags JavaDoc();
233     }
234
235
236     /**
237      * Returns the number of messages in this folder.
238      * This results in a STAT call to the POP3 server, so the latest
239      * count is always delivered.
240      *
241      * @return message count
242      * @exception MessagingException if a messaging error occurred
243      */
244     public int getMessageCount()
245         throws MessagingException JavaDoc
246     {
247         return ((POP3Store) store).getMessageCount();
248     }
249
250
251     /**
252      * Returns the specified message number from this folder.
253      * The message is only retrieved once from the server.
254      * Subsequent getMessage() calls to the same message are cached.
255      * Since POP3 does not provide a mechanism for retrieving only part of
256      * the message (headers, etc), the entire message is retrieved.
257      *
258      * @param msgnum Description of Parameter
259      * @return message
260      * @exception MessagingException if a messaging error occurred
261      */
262     public Message JavaDoc getMessage(int msgnum)
263         throws MessagingException JavaDoc
264     {
265         if (!open) {
266             throw new MessagingException JavaDoc("Folder is not open");
267         }
268         Message JavaDoc message = (Message JavaDoc) messages.get(new Integer JavaDoc(msgnum));
269         if (message == null) {
270             message = ((POP3Store) store).getMessage(this, msgnum);
271             messages.put(new Integer JavaDoc(msgnum), message);
272         }
273         return message;
274     }
275
276
277     /**
278      * You can't append messages to a POP3 folder.
279      *
280      * @param messages Description of Parameter
281      * @exception MessagingException Description of Exception
282      */
283     public void appendMessages(Message JavaDoc[] messages)
284         throws MessagingException JavaDoc
285     {
286         throw new IllegalWriteException JavaDoc();
287     }
288
289
290     /**
291      * Does nothing.
292      * The messages <i>must</i> be fetched in their entirety by getMessage(int) -
293      * this is the nature of the POP3 protocol.
294      *
295      * @param messages Description of Parameter
296      * @param fp Description of Parameter
297      * @exception MessagingException ignore
298      */
299     public void fetch(Message JavaDoc[] messages, FetchProfile JavaDoc fp)
300         throws MessagingException JavaDoc
301     {
302     }
303
304
305     /**
306      * Returns the subfolders for this folder.
307      *
308      * @return Description of the Returned Value
309      * @exception MessagingException Description of Exception
310      */
311     public Folder JavaDoc[] list()
312         throws MessagingException JavaDoc
313     {
314         switch (type) {
315             case HOLDS_FOLDERS:
316                 if (inbox == null) {
317                     inbox = new POP3Folder(store, HOLDS_MESSAGES);
318                 }
319                 Folder JavaDoc[] folders = {inbox};
320                 return folders;
321             default:
322                 throw new MessagingException JavaDoc("This folder can't contain subfolders");
323         }
324     }
325
326
327     /**
328      * Returns the subfolders for this folder.
329      *
330      * @param pattern Description of Parameter
331      * @return Description of the Returned Value
332      * @exception MessagingException Description of Exception
333      */
334     public Folder JavaDoc[] list(String JavaDoc pattern)
335         throws MessagingException JavaDoc
336     {
337         return list();
338     }
339
340
341     /**
342      * POP3 folders can't have parents.
343      *
344      * @return parent
345      * @exception MessagingException Description of Exception
346      */
347     public Folder JavaDoc getParent()
348         throws MessagingException JavaDoc
349     {
350         switch (type) {
351             case HOLDS_MESSAGES:
352                 return ((POP3Store) store).root;
353             default:
354                 throw new MessagingException JavaDoc("Root folders can't have a parent");
355         }
356     }
357
358
359     /**
360      * POP3 folders can't contain subfolders.
361      *
362      * @param s Description of Parameter
363      * @return folder
364      * @exception MessagingException Description of Exception
365      */
366     public Folder JavaDoc getFolder(String JavaDoc s)
367         throws MessagingException JavaDoc
368     {
369         switch (type) {
370             case HOLDS_FOLDERS:
371                 if (inbox == null) {
372                     inbox = new POP3Folder(store, HOLDS_MESSAGES);
373                 }
374                 return inbox;
375             default:
376                 throw new MessagingException JavaDoc("This folder can't contain subfolders");
377         }
378     }
379
380
381     /**
382      * Returns the path separator charcter.
383      *
384      * @return separator
385      * @exception MessagingException Description of Exception
386      */
387     public char getSeparator()
388         throws MessagingException JavaDoc
389     {
390         return '\u0000';
391     }
392
393
394     // -- These must be overridden to throw exceptions --
395
396     /**
397      * POP3 folders can't be created, deleted, or renamed.
398      *
399      * @param i Description of Parameter
400      * @return Description of the Returned Value
401      * @exception MessagingException Description of Exception
402      */
403     public boolean create(int i)
404         throws MessagingException JavaDoc
405     {
406         throw new IllegalWriteException JavaDoc();
407     }
408
409
410     /**
411      * POP3 folders can't be created, deleted, or renamed.
412      *
413      * @param flag Description of Parameter
414      * @return Description of the Returned Value
415      * @exception MessagingException Description of Exception
416      */
417     public boolean delete(boolean flag)
418         throws MessagingException JavaDoc
419     {
420         throw new IllegalWriteException JavaDoc("Folder can't be deleted");
421     }
422
423
424     /**
425      * POP3 folders can't be created, deleted, or renamed.
426      *
427      * @param folder Description of Parameter
428      * @return Description of the Returned Value
429      * @exception MessagingException Description of Exception
430      */
431     public boolean renameTo(Folder JavaDoc folder)
432         throws MessagingException JavaDoc
433     {
434         throw new IllegalWriteException JavaDoc("Folder can't be renamed");
435     }
436
437 }
438
439
Popular Tags