KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > james > imapserver > Mailbox


1 /***********************************************************************
2  * Copyright (c) 2000-2004 The Apache Software Foundation. *
3  * All rights reserved. *
4  * ------------------------------------------------------------------- *
5  * Licensed under the Apache License, Version 2.0 (the "License"); you *
6  * may not use this file except in compliance with the License. You *
7  * may obtain a copy of the License at: *
8  * *
9  * http://www.apache.org/licenses/LICENSE-2.0 *
10  * *
11  * Unless required by applicable law or agreed to in writing, software *
12  * distributed under the License is distributed on an "AS IS" BASIS, *
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or *
14  * implied. See the License for the specific language governing *
15  * permissions and limitations under the License. *
16  ***********************************************************************/

17
18 package org.apache.james.imapserver;
19
20 import org.apache.avalon.framework.component.Composable;
21 import org.apache.avalon.framework.configuration.Configurable;
22 import org.apache.james.imapserver.AccessControlException;
23 import org.apache.james.imapserver.AuthorizationException;
24 import org.apache.james.core.MimeMessageWrapper;
25
26 import javax.mail.internet.InternetHeaders JavaDoc;
27 import javax.mail.internet.MimeMessage JavaDoc;
28 import java.util.List JavaDoc;
29 import java.util.Map JavaDoc;
30
31 /**
32  * Interface for objects representing an IMAP4rev1 mailbox (folder). Contains
33  * logical information and provides a simple API. There should be one instance
34  * of this class for every open IMAP mailbox.
35  * Implementations may choose to store this object or recreate it on access.
36  * Storing is recommended.
37  * <p>Several methods throw AccessControlException. In normal use, these
38  * shouldn't get thrown because the Host will have checked access before
39  * returning a reference to this mailbox. However, having the methods here
40  * throw this exception allows the acl to be changed while a mailbox is
41  * selected.
42  *
43  * Mailbox Related Flags (rfc2060 name attributes)
44  * \Noinferiors It is not possible for any child levels of hierarchy to
45  * exist under this name; no child levels exist now and none can be created
46  * in the future.
47  * \Noselect It is not possible to use this name as a selectable
48  * mailbox.
49  * \Marked The mailbox has been marked "interesting" by the server;
50  * the mailbox probably contains messages that have been added since the last
51  * time the mailbox was selected.
52  * \Unmarked The mailbox does not contain any additional messages
53  * since the last time the mailbox was selected.
54  *
55  * Message related flags.
56  * The flags allowed per message are specific to each mailbox.
57  * The minimum list (rfc2060 system flags) is:
58  * \Seen Message has been read
59  * \Answered Message has been answered
60  * \Flagged Message is "flagged" for urgent/special attention
61  * \Deleted Message is "deleted" for removal by later EXPUNGE
62  * \Draft Message has not completed composition (marked as a draft).
63  * \Recent Message is "recently" arrived in this mailbox. This session
64  * is the first session to have been notified about this message; subsequent
65  * sessions will not see \Recent set for this message. This flag can not be
66  * altered by the client.
67  * If it is not possible to determine whether or not this session
68  * is the first session to be notified about a message, then that message
69  * SHOULD be considered recent.
70  *
71  * Reference: RFC 2060
72  * @version 0.2 on 04 Aug 2002
73  */

74 public interface Mailbox
75     extends Configurable, Composable {
76
77     String JavaDoc SYSTEM_FLAGS = "\\Seen \\Answered \\Flagged \\Deleted \\Draft";
78     String JavaDoc RECENT_FLAG = "\\Recent";
79
80     /**
81      * Returns name of this mailbox relative to its parent in the mailbox
82      * hierarchy.
83      * Example: 'NewIdeas'
84      *
85      * @return String name of mailbox relative to its immeadiate parent in
86      * the mailbox hierarchy.
87      */

88     String JavaDoc getName();
89
90     /**
91      * Returns absolute, that is user-independent, hierarchical name of
92      * mailbox (including namespace)
93      * Example: '#mail.fred.flintstone.apache.James.NewIdeas'
94      *
95      * @return String name of mailbox in absolute form
96      */

97     String JavaDoc getAbsoluteName();
98
99     /** Returns namespace starting with namespace token.
100      * Example: '#mail'
101      *
102      * @return String containing user-independent namespace of this mailbox.
103      */

104     // public String getNamespace();
105

106     /** Returns true if the argument is the relative or absolute name of
107      * this mailbox
108      *
109      * @param name possible name for this Mailbox
110      * @return true if name matches either getName() or getAbsoluteName()
111      */

112     boolean matchesName(String JavaDoc name);
113
114     /**
115      * Returns the current unique id validity value of this mailbox.
116      *
117      * @return int current 32 bit unique id validity value of this mailbox
118      */

119     int getUIDValidity();
120
121     /**
122      * Returns the 32 bit uid available for the next message.
123      *
124      * @return int the next UID that would be used.
125      */

126     int getNextUID();
127
128     /**
129      * Returns mailbox size in octets. Should only include actual messages
130      * and not any implementation-specific data, such as message attributes.
131      *
132      * @return int mailbox size in octets
133      */

134     int getMailboxSize();
135
136     /**
137      * Indicates if child folders may be created. It does not indicate which
138      * users can create child folders.
139      *
140      * @return boolean TRUE if inferiors aree allowed
141      */

142     boolean getInferiorsAllowed();
143
144     /**
145      * Indicates if this folder may be selected by the specified user.
146      * Requires both that the mailbox is not NotSelectableByAnyone and that the
147      * user has at least read rights. It does not indicate whether user
148      * can write to mailbox
149      *
150      * @param username String represnting user
151      * @return boolean TRUE if specified user can Select mailbox.
152      * @throws AccessControlException if username does not have lookup rights
153      */

154     boolean isSelectable(String JavaDoc username) throws AccessControlException;
155
156     /**
157      * Indicates that messages have been added since this mailbox was last
158      * selected by any user.
159      *
160      * @return boolean TRUE if new messages since any user last selected
161      * mailbox
162      */

163     boolean isMarked();
164
165     /**
166      * Returns all flags supported by this mailbox.
167      * e.g. \Answered \Deleted
168      *
169      * @return String a space seperated list of message flags which are
170      * supported by this mailbox.
171      */

172     String JavaDoc getSupportedFlags();
173
174     /**
175      * Indicates if specified user can change any flag on a permanent basis,
176      * except for \Recent which can never be changed by a user.
177      *
178      * @param username String represnting user
179      * @return true if specified user can change all flags permanently.
180      * @throws AccessControlException if username does not have lookup rights
181      */

182     boolean allFlags(String JavaDoc username) throws AccessControlException;
183
184     /**
185      * Indicates which flags this user can change permanently. If allFlags()
186      * returns true for this user, then this method must have the same return
187      * value as getSupportedFlags.
188      *
189      * @param username String represnting user
190      * @return String a space seperated list of message flags which this user
191      * can set permanently
192      */

193     String JavaDoc getPermanentFlags( String JavaDoc username )
194         throws AccessControlException;
195
196     /**
197      * Indicates number of messages in folder
198      *
199      * @return int number of messages
200      */

201     int getExists();
202
203     /**
204      * Indicates no of messages with \Recent flag set
205      *
206      * @return int no of messages with \Recent flag set
207      */

208     int getRecent();
209
210
211     /**
212      * Remove \Recent flag from all messages in mailbox. Should be called
213      * whenever a user session finishes.
214      */

215     void unsetRecent();
216
217     /**
218      * Indicates the oldest unseen message for the specified user.
219      *
220      * @return int Message Sequence Number of first message without \Seen
221      * flag set for this User.
222      * <br> -1 means all messages have \Seen flag set for this user.
223      * <br> 0 means no message (Seen or unseen) in this mailbox.
224      */

225     int getOldestUnseen( String JavaDoc user );
226
227    /**
228      * Indicates the number of unseen messages for the specified user.
229      *
230      * @return int number of messages without \Seen flag set for this User.
231      */

232     int getUnseen( String JavaDoc user );
233
234     /**
235      * Indicates state in which the mailbox will be opened by specified user.
236      * A return value of true indicates Read Only, false indicates Read-Write
237      * and an AccessControlException is thrown if user does not have read
238      * rights.
239      * <p>Implementations decide if Read Only means only lookup and read
240      * rights (lr) or lookup, read and keep seen rights (lrs). This may even
241      * vary between mailboxes.
242      *
243      * @param username String represnting user
244      * @return true if specified user can only open the mailbox Read-Only.
245      * @throws AccessControlException if the user can not open this mailbox
246      * at least Read-Only.
247      */

248     boolean isReadOnly( String JavaDoc username )
249         throws AccessControlException;
250
251     /**
252      * Mailbox Events are used to inform registered listeners of events in the
253      * Mailbox.
254      * Example if mail is delivered to an Inbox or if another user appends/
255      * deletes a message.
256      */

257     void addMailboxEventListener( MailboxEventListener mel );
258     void removeMailboxEventListener( MailboxEventListener mel );
259
260     /**
261      * Stores a message in this mailbox. User must have insert rights.
262      *
263      * @param mail the message to be stored
264      * @param username String represnting user
265      * @return boolean true if successful
266      * @throws AccessControlException if username does not have lookup rights for this mailbox.
267      * @throws AuthorizationException if username has lookup rights but does not have insert rights.
268      */

269     boolean store( MimeMessage JavaDoc message, String JavaDoc username )
270         throws AccessControlException, AuthorizationException, IllegalArgumentException JavaDoc;
271
272     /**
273      * Stores a message in this mailbox, using passed MessageAttributes and
274      * Flags. User must have insert rights.
275      *
276      * @param mail the message to be stored
277      * @param username String represnting user
278      * @param attrs non-null MessageAttributes for use with this Message
279      * @param flags a Flags object for this message
280      * @return boolean true if successful
281      * @throws AccessControlException if username does not have lookup rights
282      * for this mailbox.
283      * @throws AuthorizationException if username has lookup rights but does
284      * not have insert rights.
285      */

286     boolean store( MimeMessage JavaDoc message,
287                    String JavaDoc username,
288                    MessageAttributes attrs,
289                    Flags flags )
290         throws AccessControlException, AuthorizationException, IllegalArgumentException JavaDoc;
291
292     /**
293      * Retrieves a message given a message sequence number.
294      *
295      * @param msn the message sequence number
296      * @param username String represnting user
297      * @return a Mail object containing the message, null if no message with
298      * the given msn.
299      * @throws AccessControlException if user does not have lookup rights for
300      * this mailbox.
301      * @throws AuthorizationException if user has lookup rights but does not
302      * have read rights.
303      */

304     MimeMessageWrapper retrieve( int msn, String JavaDoc user )
305         throws AccessControlException, AuthorizationException;
306
307     /**
308      * Retrieves a message given a unique identifier.
309      *
310      * @param uid the unique identifier of a message
311      * @param username String represnting user
312      * @return a Mail object containing the message, null if no message with
313      * the given msn.
314      * @throws AccessControlException if user does not have read rights for
315      * this mailbox.
316      * @throws AuthorizationException if user has lookup rights but does not
317      * have read rights.
318      */

319     MimeMessageWrapper retrieveUID( int uid, String JavaDoc user )
320         throws AccessControlException, AuthorizationException;
321
322     /**
323      * Marks a message for deletion given a message sequence number.
324      *
325      * @param msn the message sequence number
326      * @param username String represnting user
327      * @return boolean true if successful.
328      * @throws AccessControlException if user does not have read rights for
329      * this mailbox.
330      * @throws AuthorizationException if user has lookup rights but does not
331      * have delete rights.
332      */

333     boolean markDeleted( int msn, String JavaDoc user )
334         throws AccessControlException, AuthorizationException;
335
336     /**
337      * Marks a message for deletion given a unique identifier.
338      *
339      * @param uidunique identifier
340      * @param username String represnting user
341      * @return boolean true if successful, false if failed including no
342      * message with the given uid.
343      * @throws AccessControlException if user does not have read rights for
344      * this mailbox.
345      * @throws AuthorizationException if user has lookup rights but does not
346      * have delete rights.
347      */

348     boolean markDeletedUID( int uid, String JavaDoc user )
349         throws AccessControlException, AuthorizationException;
350
351     /**
352      * Returns the message attributes for a message.
353      *
354      * @param msn message sequence number
355      * @param username String represnting user
356      * @return MessageAttributes for message, null if no such message.
357      * Changing the MessageAttributes object must not affect the actual
358      * MessageAttributes.
359      * @throws AccessControlException if user does not have read rights for
360      * this mailbox.
361      * @throws AuthorizationException if user has lookup rights but does not
362      * have delete rights.
363      */

364     MessageAttributes getMessageAttributes( int msn, String JavaDoc user )
365         throws AccessControlException, AuthorizationException;
366
367     /**
368      * Returns the message attributes for a message.
369      *
370      * @param uid unique identifier
371      * @param username String represnting user
372      * @return MessageAttributes for message, null if no such message.
373      * Changing the MessageAttributes object must not affect the actual
374      * MessageAttributes.
375      * @throws AccessControlException if user does not have read rights for
376      * this mailbox.
377      * @throws AuthorizationException if user has lookup rights but does not
378      * have delete rights.
379      */

380     MessageAttributes getMessageAttributesUID( int uid, String JavaDoc user )
381         throws AccessControlException, AuthorizationException;
382
383     /**
384      * Updates the attributes of a message.
385      *
386      * @param MessageAttributes of a message already in this Mailbox
387      * @throws AccessControlException if user does not have read rights for
388      * this mailbox.
389      * @throws AuthorizationException if user has lookup rights but does not
390      * have delete rights.
391      */

392     boolean updateMessageAttributes( MessageAttributes attrs, String JavaDoc user )
393         throws AccessControlException, AuthorizationException;
394
395     /**
396      * Get the IMAP-formatted String of flags for specified message.
397      *
398      * @param msn message sequence number for a message in this mailbox
399      * @param username String represnting user
400      * @return flags for this message and user, null if no such message.
401      * @throws AccessControlException if user does not have lookup rights for
402      * this mailbox.
403      * @throws AuthorizationException if user has lookup rights but does not
404      * have read rights.
405      */

406     String JavaDoc getFlags( int msn, String JavaDoc user )
407         throws AccessControlException, AuthorizationException;
408
409    /**
410      * Get the IMAP-formatted String of flags for specified message.
411      *
412      * @param uid UniqueIdentifier for a message in this mailbox
413      * @param username String represnting user
414      * @return flags for this message and user, null if no such message.
415      * @throws AccessControlException if user does not have lookup rights for
416      * this mailbox.
417      * @throws AuthorizationException if user has lookup rights but does not
418      * have read rights.
419      */

420     String JavaDoc getFlagsUID(int uid, String JavaDoc user)
421         throws AccessControlException, AuthorizationException;
422
423     /**
424      * Updates the flags of a message.
425      *
426      * @param msn message sequence number for a message in this mailbox
427      * @param username String represnting user
428      * @param request IMAP formatted string of flag request
429      * @throws AccessControlException if user does not have read rights for
430      * this mailbox.
431      * @throws AuthorizationException if user has lookup rights but does not
432      * have delete rights.
433      */

434     boolean setFlags( int msn, String JavaDoc user, String JavaDoc request )
435         throws AccessControlException, AuthorizationException, IllegalArgumentException JavaDoc;
436
437     /**
438      * Updates the flags of a message.
439      *
440      * @param uid UniqueIdentifier for a message in this mailbox
441      * @param username String represnting user
442      * @param request IMAP formatted string of flag request
443      * @throws AccessControlException if user does not have read rights for
444      * this mailbox.
445      * @throws AuthorizationException if user has lookup rights but does not
446      * have delete rights.
447      */

448     boolean setFlagsUID( int uid, String JavaDoc user, String JavaDoc request )
449         throws AccessControlException, AuthorizationException, IllegalArgumentException JavaDoc;
450
451     /**
452      * Returns the Internet Headers for a message. These are the top-level
453      * headers only, ie not MIME part headers or headers of encapsulated
454      * messages.
455      *
456      * @param msn message sequence number
457      * @param username String represnting user
458      * @return InternetHeaders for message, null if no such message.
459      * Changing the InternetHeaders object must not affect the actual
460      * InternetHeaders of the underlying message.
461      * @throws AccessControlException if user does not have read rights for
462      * this mailbox.
463      * @throws AuthorizationException if user has lookup rights but does not
464      * have delete rights.
465      */

466     InternetHeaders JavaDoc getInternetHeaders( int msn, String JavaDoc user )
467         throws AccessControlException, AuthorizationException;
468
469     /**
470      * Returns the Internet Headers for a message. These are the top-level
471      * headers only, ie not MIME part headers or headers of encapsulated
472      * messages.
473      *
474      * @param uid UniqueIdentifier for a message in this mailbox
475      * @param username String represnting user
476      * @return InternetHeaders for message, null if no such message.
477      * Changing the InternetHeaders object must not affect the actual
478      * InternetHeaders of the underlying message.
479      * @throws AccessControlException if user does not have read rights for
480      * this mailbox.
481      * @throws AuthorizationException if user has lookup rights but does not
482      * have delete rights.
483      */

484     InternetHeaders JavaDoc getInternetHeadersUID( int uid, String JavaDoc user )
485         throws AccessControlException, AuthorizationException;
486
487     /**
488      * Removes all messages marked Deleted. User must have delete rights.
489      *
490      * @param username String representing user
491      * @return true if successful
492      * @throws AccessControlException if user does not have read rights for
493      * this mailbox.
494      * @throws AuthorizationException if user has delete rights but does not
495      * have delete rights.
496      */

497     boolean expunge( String JavaDoc user )
498         throws AccessControlException, AuthorizationException, IllegalArgumentException JavaDoc;
499     
500     /**
501      * Renames this Mailbox to a new name.
502      *
503      * @param username String representing user
504      * @param newmailboxname String representing the new Mailbox Name
505      * @return true if successful
506      * @throws MailboxException if the Mailbox can't be renamed
507      * @throws AuthorizationException if user has no write rights
508      */

509     boolean renameMailbox(String JavaDoc username, String JavaDoc newmailboxname)
510         throws MailboxException, AuthorizationException;
511     
512     boolean renameSubMailbox(String JavaDoc username, String JavaDoc oldname, String JavaDoc newmailboxname);
513     /**
514      * Establishes if specified user has lookup rights for this mailbox.
515      *
516      * @param username String represnting user
517      * @return true if user has at least lookup rights
518      */

519     boolean hasLookupRights( String JavaDoc user );
520
521     /**
522      * Establishes if specified user has create rights for this mailbox.
523      *
524      * @param username String represnting user
525      * @return true if user has at create rights
526      * @throws AccessControlException if user does not have lookup rights for
527      * this mailbox.
528      */

529     boolean hasCreateRights( String JavaDoc user )
530         throws AccessControlException;
531
532     /**
533      * Lists uids of messages in mailbox indexed by MSN.
534      *
535      * @param username String represnting user
536      * @return List of Integers wrapping uids of message
537      */

538     List JavaDoc listUIDs( String JavaDoc user );
539
540     /**
541      * Returns true once this Mailbox has been checkpointed.
542      * This may include resolving in-memory state with disk state.
543      * Implementations not requiring checkpointing should return immeadiately.
544      *
545      * @return true if check completes normally, false otherwise.
546      */

547     boolean checkpoint();
548
549     /**
550      * Mark this mailbox as not selectable by anyone.
551      * Example folders at the roots of hierarchies, e. #mail for each user.
552      *
553      * @param state true if folder is not selectable by anyone
554      */

555     void setNotSelectableByAnyone( boolean state );
556
557     boolean isNotSelectableByAnyone();
558
559     /**
560      * Gets map of users to number of unseen messages. User key will only be
561      * present if getOldestUnseen() has been called, usually as a result of
562      * an IMAP SELECT or EXAMINE.
563      */

564     Map JavaDoc getUnseenByUser();
565
566     /**
567      * Returns true if the named user is subscribed to this Mailbox.
568      */

569     boolean isSubscribed( String JavaDoc userName );
570
571     /**
572      * Subscribes a user to this Mailbox.
573      */

574     void subscribe( String JavaDoc userName );
575
576     /**
577      * Unsubscrive a user from this Mailbox.
578      */

579     void unsubscribe( String JavaDoc userName );
580
581 }
582
583
584
Popular Tags