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  ;
27  import javax.mail.internet.MimeMessage  ;
28  import java.util.List  ;
29  import java.util.Map  ;
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   SYSTEM_FLAGS = "\\Seen \\Answered \\Flagged \\Deleted \\Draft";
78      String   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   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   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   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   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   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   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   getPermanentFlags( String   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   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   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   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   message, String   username )
270         throws AccessControlException, AuthorizationException, IllegalArgumentException  ;
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   message,
287                    String   username,
288                    MessageAttributes attrs,
289                    Flags flags )
290         throws AccessControlException, AuthorizationException, IllegalArgumentException  ;
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   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   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   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   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   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   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   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   getFlags( int msn, String   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   getFlagsUID(int uid, String   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   user, String   request )
435         throws AccessControlException, AuthorizationException, IllegalArgumentException  ;
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   user, String   request )
449         throws AccessControlException, AuthorizationException, IllegalArgumentException  ;
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   getInternetHeaders( int msn, String   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   getInternetHeadersUID( int uid, String   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   user )
498         throws AccessControlException, AuthorizationException, IllegalArgumentException  ;
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   username, String   newmailboxname)
510         throws MailboxException, AuthorizationException;
511     
512     boolean renameSubMailbox(String   username, String   oldname, String   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   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   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   listUIDs( String   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   getUnseenByUser();
565 
566     /**
567      * Returns true if the named user is subscribed to this Mailbox.
568      */
569     boolean isSubscribed( String   userName );
570 
571     /**
572      * Subscribes a user to this Mailbox.
573      */
574     void subscribe( String   userName );
575 
576     /**
577      * Unsubscrive a user from this Mailbox.
578      */
579     void unsubscribe( String   userName );
580 
581 }
582 
583 
584
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags