Host


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.imapserver.AccessControlException;
21  import org.apache.james.imapserver.AuthorizationException;
22  
23  import java.util.Collection  ;
24  import java.util.List  ;
25  
26  /**
27   * A host machine that has an IMAP4rev1 messaging server. There should be one
28   * instance of this class per instance of James.
29   * An IMAP messaging system may span more than one host.
30   * <p><code>String</code> parameters representing mailbox names must be the
31   * full hierarchical name of the target, with namespace, as used by the
32   * specified user. Examples:
33   * '#mail.Inbox' or '#shared.finance.Q2Earnings'.
34   * <p>An imap Host must keep track of existing and deleted mailboxes.
35   *
36   * References: rfc 2060, rfc 2193, rfc 2221
37   * @version 0.1 on 14 Dec 2000
38   * @see FolderRecord
39   * @see RecordRepository
40   */
41  public interface Host
42  {
43  
44      String   ROLE = "org.apache.james.imapserver.Host";
45  
46      String   IMAP_HOST = "IMAP_HOST";
47  
48      /**
49       * Establishes whether this host is the Home Server for the specified user.
50       * Used during login to decide whether a LOGIN_REFERRAL has to be sent to
51       * the client.
52       *
53       * @param username an email address
54       * @return true if inbox (and private mailfolders) are accessible through
55       * this host.
56       */
57      boolean isHomeServer( String   username );
58  
59      /**
60       * Establishes if the specified user can access any mailboxes on this host.
61       * Used during login process to decide what sort of LOGIN-REFERRAL must be
62       * sent to client.
63       *
64       * @param username an email address
65       * @return true if the specified user has at least read access to any
66       * mailboxes on this host.
67       */
68      boolean hasLocalAccess( String   username );
69  
70      /**
71       * Returns a reference to an existing Mailbox. The requested mailbox
72       * must already exists on this server and the requesting user must have at
73       * least lookup rights.
74       *
75       * @param user email address on whose behalf the request is made.
76       * @param mailboxName String name of the target.
77       * @return an Mailbox reference.
78       * @throws AccessControlException if the user does not have at least
79       * lookup rights.
80       * @throws MailboxException if mailbox does not exist locally.
81       */
82      ACLMailbox getMailbox( String   user, String   mailboxName )
83              throws AccessControlException, MailboxException;
84  
85  
86      /**
87       * Returns a reference to a newly created Mailbox. The request should
88       * specify a mailbox that does not already exist on this server, that
89       * could exist on this server and that the user has rights to create.
90       * If a system allocates different namespaces to different hosts then a
91       * request to create a mailbox in a namespace not served by this host would
92       * be an error.
93       * It is an error to create a mailbox with the name of a mailbox that has
94       * been deleted, if that name is still in use.
95       *
96       * @param user email address on whose behalf the request is made.
97       * @param mailboxName String name of the target
98       * @return an Mailbox reference.
99       * @throws MailboxException if mailbox already exists, locally or remotely,
100      * or if mailbox cannot be created locally.
101      * @throws AccessControlException if the user does not have lookup rights
102      * for parent or any needed ancestor folder
103      * lookup rights.
104      * @throws AuthorizationException if mailbox could be created locally but
105      * user does not have create rights.
106      * @see FolderRecord
107      */
108     ACLMailbox createMailbox( String   user, String   mailboxName )
109             throws AccessControlException, AuthorizationException, MailboxException;
110 
111 
112     /**
113      * Deletes an existing MailBox. Specified mailbox must already exist on
114      * this server, and the user must have rights to delete it. (Mailbox delete
115      * rights are implementation defined, one way is if the user would have the
116      * right to create it).
117      * Implementations must track deleted mailboxes
118      *
119      * @param user email address on whose behalf the request is made.
120      * @param mailboxName String name of the target
121      * @return true if mailbox deleted successfully
122      * @throws MailboxException if mailbox does not exist locally or is any
123      * identities INBOX.
124      * @throws AuthorizationException if mailbox exists locally but user does
125      * not have rights to delete it.
126      * @see FolderRecord
127      */
128     boolean deleteMailbox( String   user, String   mailboxName )
129             throws MailboxException, AuthorizationException, AccessControlException;
130 
131 
132     /**
133      * Renames an existing MailBox. The specified mailbox must already
134      * exist locally, the requested name must not exist locally already but
135      * must be able to be created locally and the user must have rights to
136      * delete the existing mailbox and create a mailbox with the new name.
137      * Any inferior hierarchical names must also be renamed.
138      * If INBOX is renamed, the contents of INBOX are transferred to a new
139      * folder with the new name, but INBOX is not deleted. If INBOX has
140      * inferior mailboxes these are not renamed.
141      * It is an error to create a mailbox with the name of a mailbox that has
142      * been deleted, if that name is still in use.
143      * Implementations must track deleted mailboxes
144      *
145      * @param user email address on whose behalf the request is made.
146      * @param oldMailboxName String name of the existing mailbox
147      * @param newMailboxName String target new name
148      * @return true if rename completed successfully
149      * @throws MailboxException if mailbox does not exist locally, or there
150      * is an existing mailbox with the new name.
151      * @throws AuthorizationException if user does not have rights to delete
152      * the existing mailbox or create the new mailbox.
153      * @see FolderRecord
154      */
155     boolean renameMailbox( String   user,
156                            String   oldMailboxName,
157                            String   newMailboxName )
158             throws MailboxException, AuthorizationException;
159 
160     /**
161      * Releases a reference to a mailbox, allowing Host to do any housekeeping.
162      *
163      * @param username String user who has finished with this mailbox
164      * @param mbox a non-null reference to an ACL Mailbox.
165      */
166     void releaseMailbox( String   user, ACLMailbox mbox );
167 
168     /**
169      * Returns the namespace which should be used for this user unless they
170      * expicitly request another.
171      *
172      * @param username String an email address
173      * @return a String of a namespace
174      */
175     String   getDefaultNamespace( String   username );
176 
177 
178     /**
179      * Return UIDValidity for named mailbox. Implementations should track
180      * existing and deleted folders.
181      *
182      * @param mailbox String name of the existing mailbox
183      * @return  an integer containing the current UID Validity value.
184      */
185     //  public int getUIDValidity(String mailbox);
186 
187 
188     /**
189      * Returns an iterator over an unmodifiable collection of Strings
190      * representing mailboxes on this host and their attributes. The specified
191      * user must have at least lookup rights for each mailbox returned.
192      * If the subscribedOnly flag is set, only mailboxes to which the
193      * specified user is currently subscribed should be returned.
194      * Implementations that may export circular hierarchies SHOULD restrict the
195      * levels of hierarchy returned. The depth suggested by rfc 2683 is 20
196      * hierarchy levels.
197      * <p>The reference name must be non-empty. If the mailbox name is empty,
198      * implementations must not throw either exception but must return a single
199      * String (described below) if the reference name specifies a local mailbox
200      * accessible to the user and a one-character String containing the
201      * hierarchy delimiter of the referenced namespace, otherwise.
202      * <p>Each String returned should be a space seperated triple of name
203      * attributes, hierarchy delimiter and full mailbox name.   The mailbox
204      * name should include the namespace and be relative to the specified user.
205      * <p> RFC comments: Implementations SHOULD return quickly. They SHOULD
206      * NOT go to excess trouble to calculate\Marked or \Unmarked status.
207      * <p>JAMES comment: By elimination, implementations should usually include
208      * \Noinferiors or \Noselect, if appropriate. Also, if the reference name
209      * and mailbox name resolve to a single local mailbox, implementations
210      * should establish all attributes.
211      * <p> Note that servers cannot unilaterally remove mailboxes from the
212      * subscribed list. A request with the subscribedOnly flag set that
213      * attempts to list a deleted mailbox must return that mailbox with the
214      * \Noselect attribute.
215      *
216      * @param username String non-empty email address of requester
217      * @param referenceName String non-empty name, including namespace, of a
218      * mailbox or level of mailbox hierarchy, relative to user.
219      * @param mailboxName String name of a mailbox possible including a
220      * wildcard.
221      * @param subscribedOnly only return mailboxes currently subscribed.
222      * @return Collection of strings representing a set of mailboxes.
223      * @throws AccessControlException if the user does not have at least
224      * lookup rights to at least one mailbox in the set requested.
225      * @throws MailboxException if the referenceName is not local or if
226      * referenceName and mailbox name resolve to a single mailbox which does
227      * not exist locally.
228      */
229     Collection   listMailboxes( String   username,
230                               String   referenceName,
231                               String   mailboxName,
232                               boolean subscribedOnly )
233             throws MailboxException, AccessControlException;
234 
235     /**
236      * Subscribes a user to a mailbox. The mailbox must exist locally and the
237      * user must have at least lookup rights to it.
238      *
239      * @param username String representation of an email address
240      * @param mailbox String representation of a mailbox name.
241      * @return true if subscribe completes successfully
242      * @throws AccessControlException if the mailbox exists but the user does
243      * not have lookup rights.
244      * @throws MailboxException if the mailbox does not exist locally.
245      */
246     boolean subscribe( String   username, String   mailbox )
247             throws MailboxException, AccessControlException;
248 
249     /**
250      * Unsubscribes from a given mailbox.
251      *
252      * @param username String representation of an email address
253      * @param mailbox String representation of a mailbox name.
254      * @return true if unsubscribe completes successfully
255      */
256     boolean unsubscribe( String   username, String   mailbox )
257             throws MailboxException, AccessControlException;
258 
259     /**
260      * Returns a string giving the status of a mailbox on requested criteria.
261      * Currently defined staus items are:
262      * MESSAGES - Nummber of messages in mailbox
263      * RECENT - Number of messages with \Recent flag set
264      * UIDNEXT - The UID that will be assigned to the next message entering
265      * the mailbox
266      * UIDVALIDITY - The current UIDValidity value for the mailbox
267      * UNSEEN - The number of messages which do not have the \Seen flag set.
268      *
269      * @param username String non-empty email address of requester
270      * @param mailboxName String name of a mailbox (no wildcards allowed).
271      * @param dataItems Vector of one or more Strings each of a single
272      * status item.
273      * @return String consisting of space seperated pairs:
274      * dataItem-space-number.
275      * @throws AccessControlException if the user does not have at least
276      * lookup rights to the mailbox requested.
277      * @throws MailboxException if the mailboxName does not exist locally.
278      */
279     String   getMailboxStatus( String   username,
280                              String   mailboxName,
281                              List   dataItems )
282             throws MailboxException, AccessControlException;
283 
284 
285     boolean createPrivateMailAccount( String   username );
286 }
287 
288
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags