View Javadoc

1   /*
2    * $Id: UserDatabase.java 471754 2006-11-06 14:55:09Z husted $
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  package org.apache.struts.apps.mailreader.dao;
22  
23  
24  /**
25   * <p>A <strong>Data Access Object</strong> (DAO) interface describing
26   * the available operations for retrieving and storing {@link User}s
27   * (and their associated {@link Subscription}s) in some persistence layer
28   * whose characteristics are not specified here.  One or more implementations
29   * will be created to perform the actual I/O that is required.</p>
30   *
31   * @version $Rev: 471754 $ $Date: 2006-11-06 08:55:09 -0600 (Mon, 06 Nov 2006) $
32   * @since Struts 1.1
33   */
34  public interface UserDatabase {
35  
36  
37      // --------------------------------------------------------- Public Methods
38  
39  
40      /**
41       * <p>Create and return a new {@link User} defined in this user database.
42       * </p>
43       *
44       * @param username Username of the new user
45       *
46       * @exception IllegalArgumentException if the specified username
47       *  is not unique
48       */
49      public User createUser(String username);
50  
51  
52      /**
53       * <p>Finalize access to the underlying persistence layer.</p>
54       *
55       * @exception Exception if a database access error occurs
56       */
57      public void close() throws Exception;
58  
59  
60      /**
61       * <p>Return the existing {@link User} with the specified username,
62       * if any; otherwise return <code>null</code>.</p>
63       *
64       * @param username Username of the user to retrieve
65       * @throws ExpiredPasswordException if user password has expired
66       * and must be changed
67       */
68      public User findUser(String username) throws ExpiredPasswordException;
69  
70  
71      /**
72       * <p>Return the set of {@link User}s defined in this user database.</p>
73       */
74      public User[] findUsers();
75  
76  
77      /**
78       * <p>Return true if open() has been called.</p>
79       *
80       * @exception Exception if a database access error occurs
81       */
82      public boolean isOpen();
83  
84  
85      /**
86       * <p>Initiate access to the underlying persistence layer.</p>
87       *
88       * @exception Exception if a database access error occurs
89       */
90      public void open() throws Exception;
91  
92  
93      /**
94       * Remove the specified {@link User} from this database.
95       *
96       * @param user User to be removed
97       *
98       * @exception IllegalArgumentException if the specified user is not
99       *  associated with this database
100      */
101     public void removeUser(User user);
102 
103 
104     /**
105      * <p>Save any pending changes to the underlying persistence layer.</p>
106      *
107      * @exception Exception if a database access error occurs
108      */
109     public void save() throws Exception;
110 
111 
112 }