ImapHost


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.james.services.User;
21  import org.apache.james.imapserver.store.ImapMailbox;
22  import org.apache.james.imapserver.store.MailboxException;
23  
24  import javax.mail.search.SearchTerm  ;
25  import java.util.Collection  ;
26  
27  /**
28   * A host machine that has an IMAP4rev1 messaging server. There should be one
29   * instance of this class per instance of James.
30   * An IMAP messaging system may span more than one host.
31   * <p><code>String</code> parameters representing mailbox names must be the
32   * full hierarchical name of the target, with namespace, as used by the
33   * specified user. Examples:
34   * '#mail.Inbox' or '#shared.finance.Q2Earnings'.
35   * <p>An imap Host must keep track of existing and deleted mailboxes.
36   *
37   * References: rfc 2060, rfc 2193, rfc 2221
38   * @version $Revision: 1.3.2.3 $
39   */
40  public interface ImapHost
41  {
42  
43      String   ROLE = "org.apache.james.imapserver.ImapHost";
44  
45      String   IMAP_HOST = "IMAP_HOST";
46  
47      /**
48       * Returns the hierarchy delimiter for mailboxes on this host.
49       * @return The hierarchy delimiter character.
50       */
51      char getHierarchyDelimiter();
52  
53      /**
54       * Returns a reference to an existing Mailbox. The requested mailbox
55       * must already exists on this server and the requesting user must have at
56       * least lookup rights.
57       *
58       * TODO: should default behaviour be to return null?
59       *
60       * @param user User making the request.
61       * @param mailboxName String name of the target.
62       * @return an Mailbox reference.
63       */
64      ImapMailbox getMailbox( User user, String   mailboxName );
65  
66      /**
67       * Returns a reference to an existing Mailbox.
68       * If mustExist == true, an exception is thrown if the requested mailbox
69       * doesn't exists on this server or the requesting user doesn't have at
70       * least lookup rights. If mustExist == false, simply returns <code>null</code> in
71       * this case.
72       *
73       * @param user User making the request.
74       * @param mailboxName String name of the target.
75       * @param mustExist Specified behaviour where a mailbox is missing or non-viewable.
76       * @return an Mailbox reference.
77       * @throws org.apache.james.imapserver.store.MailboxException if mailbox does not exist locally, and mustExist is true.
78       */
79      ImapMailbox getMailbox( User user, String   mailboxName, boolean mustExist )
80              throws MailboxException;
81  
82      /**
83       * Returns a reference to the user's INBOX. The user must have been
84       * registered on the server by the {@link #createPrivateMailAccount} method.
85       * @param user The user making the request.
86       * @return The user's Inbox.
87       * @throws org.apache.james.imapserver.store.MailboxException if the user doesn't have an inbox on this server.
88       */
89      ImapMailbox getInbox( User user ) throws MailboxException;
90  
91      /**
92       * Registers a user with the ImapHost, creating a personal mail space and
93       * INBOX for that user.
94       * @param user The user to register with the Host.
95       * @throws org.apache.james.imapserver.store.MailboxException if an error occurred creating the user account.
96       */
97      void createPrivateMailAccount( User user ) throws MailboxException;
98  
99      /**
100      * Returns a reference to a newly created Mailbox. The request should
101      * specify a mailbox that does not already exist on this server, that
102      * could exist on this server and that the user has rights to create.
103      * If a system allocates different namespaces to different hosts then a
104      * request to create a mailbox in a namespace not served by this host would
105      * be an error.
106      * It is an error to create a mailbox with the name of a mailbox that has
107      * been deleted, if that name is still in use.
108      *
109      * @param user User making the request.
110      * @param mailboxName String name of the target
111      * @return an Mailbox reference.
112      * @throws org.apache.james.imapserver.store.MailboxException if mailbox already exists, locally or remotely,
113      * or if mailbox cannot be created locally.
114      * @throws AuthorizationException if mailbox could be created locally but
115      * user does not have create rights.
116      */
117     ImapMailbox createMailbox( User user, String   mailboxName )
118             throws AuthorizationException, MailboxException;
119 
120 
121     /**
122      * Deletes an existing MailBox. Specified mailbox must already exist on
123      * this server, and the user must have rights to delete it. (Mailbox delete
124      * rights are implementation defined, one way is if the user would have the
125      * right to create it).
126      *
127      * @param user User making the request.
128      * @param mailboxName String name of the target
129      * @throws org.apache.james.imapserver.store.MailboxException if mailbox does not exist locally or is any
130      * identities INBOX.
131      * @throws AuthorizationException if mailbox exists locally but user does
132      * not have rights to delete it.
133      */
134     void deleteMailbox( User user, String   mailboxName )
135             throws MailboxException, AuthorizationException;
136 
137 
138     /**
139      * Renames an existing MailBox. The specified mailbox must already
140      * exist locally, the requested name must not exist locally already but
141      * must be able to be created locally and the user must have rights to
142      * delete the existing mailbox and create a mailbox with the new name.
143      * Any inferior hierarchical names must also be renamed.
144      * If INBOX is renamed, the contents of INBOX are transferred to a new
145      * folder with the new name, but INBOX is not deleted. If INBOX has
146      * inferior mailboxes these are not renamed.
147      * It is an error to create a mailbox with the name of a mailbox that has
148      * been deleted, if that name is still in use.
149      *
150      * @param user User making the request.
151      * @param oldMailboxName String name of the existing mailbox
152      * @param newMailboxName String target new name
153      * @throws org.apache.james.imapserver.store.MailboxException if mailbox does not exist locally, or there
154      * is an existing mailbox with the new name.
155      * @throws AuthorizationException if user does not have rights to delete
156      * the existing mailbox or create the new mailbox.
157      */
158     void renameMailbox( User user,
159                         String   oldMailboxName,
160                         String   newMailboxName )
161             throws MailboxException, AuthorizationException;
162 
163     /**
164      * Returns an collection of mailboxes on this host. The specified
165      * user must have at least lookup rights for each mailbox returned.
166      * If the subscribedOnly flag is set, only mailboxes to which the
167      * specified user is currently subscribed should be returned.
168      * Implementations that may export circular hierarchies SHOULD restrict the
169      * levels of hierarchy returned. The depth suggested by rfc 2683 is 20
170      * hierarchy levels.
171      * <p>The reference name must be non-empty. If the mailbox name is empty,
172      * implementations must not throw either exception but must return a single
173      * String (described below) if the reference name specifies a local mailbox
174      * accessible to the user and a one-character String containing the
175      * hierarchy delimiter of the referenced namespace, otherwise.
176      * <p>Each String returned should be a space seperated triple of name
177      * attributes, hierarchy delimiter and full mailbox name.   The mailbox
178      * name should include the namespace and be relative to the specified user.
179      * <p> RFC comments: Implementations SHOULD return quickly. They SHOULD
180      * NOT go to excess trouble to calculate\Marked or \Unmarked status.
181      * <p>JAMES comment: By elimination, implementations should usually include
182      * \Noinferiors or \Noselect, if appropriate. Also, if the reference name
183      * and mailbox name resolve to a single local mailbox, implementations
184      * should establish all attributes.
185      *
186      * @param user User making the request
187      * @param mailboxPattern String name of a mailbox possible including a
188      * wildcard.
189      * @return Collection of mailboxes matching the pattern.
190      * @throws org.apache.james.imapserver.store.MailboxException if the referenceName is not local or if
191      * referenceName and mailbox name resolve to a single mailbox which does
192      * not exist locally.
193      */
194     Collection   listMailboxes( User user,
195                               String   mailboxPattern )
196             throws MailboxException;
197 
198     /**
199      * Returns an collection of mailboxes on this host. The specified
200      * user must have at least lookup rights for each mailbox returned.
201      * If the subscribedOnly flag is set, only mailboxes to which the
202      * specified user is currently subscribed should be returned.
203      * Implementations that may export circular hierarchies SHOULD restrict the
204      * levels of hierarchy returned. The depth suggested by rfc 2683 is 20
205      * hierarchy levels.
206      * <p>The reference name must be non-empty. If the mailbox name is empty,
207      * implementations must not throw either exception but must return a single
208      * String (described below) if the reference name specifies a local mailbox
209      * accessible to the user and a one-character String containing the
210      * hierarchy delimiter of the referenced namespace, otherwise.
211      * <p>Each String returned should be a space seperated triple of name
212      * attributes, hierarchy delimiter and full mailbox name.   The mailbox
213      * name should include the namespace and be relative to the specified user.
214      * <p> RFC comments: Implementations SHOULD return quickly. They SHOULD
215      * NOT go to excess trouble to calculate\Marked or \Unmarked status.
216      * <p>JAMES comment: By elimination, implementations should usually include
217      * \Noinferiors or \Noselect, if appropriate. Also, if the reference name
218      * and mailbox name resolve to a single local mailbox, implementations
219      * should establish all attributes.
220      * <p> Note that servers cannot unilaterally remove mailboxes from the
221      * subscribed list. A request that attempts to list a deleted, but subscribed,
222      * mailbox must return that mailbox with the \Noselect attribute.
223      *
224      * @param user User making the request
225      * @param mailboxPattern String name of a mailbox possible including a
226      * wildcard.
227      * @return Collection of mailboxes matching the pattern.
228      * @throws org.apache.james.imapserver.store.MailboxException if the referenceName is not local or if
229      * referenceName and mailbox name resolve to a single mailbox which does
230      * not exist locally.
231      */
232     Collection   listSubscribedMailboxes( User user,
233                                         String   mailboxPattern)
234             throws MailboxException;
235 
236     /**
237      * Subscribes a user to a mailbox. The mailbox must exist locally and the
238      * user must have at least lookup rights to it.
239      *
240      * @param user User making the request
241      * @param mailbox String representation of a mailbox name.
242      * @throws org.apache.james.imapserver.store.MailboxException if the mailbox does not exist locally (for the user).
243      */
244     void subscribe( User user, String   mailbox )
245             throws MailboxException;
246 
247     /**
248      * Unsubscribes from a given mailbox.
249      *
250      * @param user String representation of an email address
251      * @param mailbox String representation of a mailbox name.
252      */
253     void unsubscribe( User user, String   mailbox )
254             throws MailboxException;
255 
256     int[] expunge( ImapMailbox mailbox ) throws MailboxException;
257 
258     long[] search( SearchTerm   searchTerm, ImapMailbox mailbox );
259 
260     void copyMessage( long uid, ImapMailbox currentMailbox, ImapMailbox toMailbox )
261             throws MailboxException;
262 
263 
264 }
265 
266
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags