View Javadoc
1   /*
2    * $Id$
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *  http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  
23  package org.apache.struts.apps.mailreader.dao;
24  
25  
26  /**
27   * <p>A <strong>Data Access Object</strong> (DAO) interface describing
28   * the available operations for retrieving and storing {@link User}s
29   * (and their associated {@link Subscription}s) in some persistence layer
30   * whose characteristics are not specified here.  One or more implementations
31   * will be created to perform the actual I/O that is required.</p>
32   *
33   * @author Craig R. McClanahan
34   * @version $Rev$ $Date$
35   * @since Struts 1.1
36   */
37  
38  public interface UserDatabase {
39  
40  
41      // --------------------------------------------------------- Public Methods
42  
43  
44      /**
45       * <p>Create and return a new {@link User} defined in this user database.
46       * </p>
47       *
48       * @param username Username of the new user
49       *
50       * @exception IllegalArgumentException if the specified username
51       *  is not unique
52       */
53      public User createUser(String username);
54  
55  
56      /**
57       * <p>Finalize access to the underlying persistence layer.</p>
58       *
59       * @exception Exception if a database access error occurs
60       */
61      public void close() throws Exception;
62  
63  
64      /**
65       * <p>Return the existing {@link User} with the specified username,
66       * if any; otherwise return <code>null</code>.</p>
67       *
68       * @param username Username of the user to retrieve
69       * @throws ExpiredPasswordException if user password has expired
70       * and must be changed
71       */
72      public User findUser(String username) throws ExpiredPasswordException;
73  
74  
75      /**
76       * <p>Return the set of {@link User}s defined in this user database.</p>
77       */
78      public User[] findUsers();
79  
80  
81      /**
82       * <p>Return true if open() has been called.</p>
83       *
84       * @exception Exception if a database access error occurs
85       */
86      public boolean isOpen();
87  
88  
89      /**
90       * <p>Initiate access to the underlying persistence layer.</p>
91       *
92       * @exception Exception if a database access error occurs
93       */
94      public void open() throws Exception;
95  
96  
97      /**
98       * Remove the specified {@link User} from this database.
99       *
100      * @param user User to be removed
101      *
102      * @exception IllegalArgumentException if the specified user is not
103      *  associated with this database
104      */
105     public void removeUser(User user);
106 
107 
108     /**
109      * <p>Save any pending changes to the underlying persistence layer.</p>
110      *
111      * @exception Exception if a database access error occurs
112      */
113     public void save() throws Exception;
114 
115 
116 }