View Javadoc

1   /* Copyright 2004 Acegi Technology Pty Limited
2    *
3    * Licensed under the Apache License, Version 2.0 (the "License");
4    * you may not use this file except in compliance with the License.
5    * You may obtain a copy of the License at
6    *
7    *     http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed under the License is distributed on an "AS IS" BASIS,
11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12   * See the License for the specific language governing permissions and
13   * limitations under the License.
14   */
15  
16  package org.acegisecurity.providers.dao;
17  
18  import org.acegisecurity.userdetails.User;
19  import org.acegisecurity.userdetails.UserDetails;
20  
21  
22  /***
23   * Provides a cache of {@link User} objects.
24   * 
25   * <P>
26   * Implementations should provide appropriate methods to set their cache
27   * parameters (eg time-to-live) and/or force removal of entities before their
28   * normal expiration. These are not part of the <code>UserCache</code>
29   * interface contract because they vary depending on the type of caching
30   * system used (eg in-memory vs disk vs cluster vs hybrid).
31   * </p>
32   *
33   * @author Ben Alex
34   * @version $Id: UserCache.java,v 1.6 2005/11/29 13:10:08 benalex Exp $
35   */
36  public interface UserCache {
37      //~ Methods ================================================================
38  
39      /***
40       * Obtains a {@link UserDetails} from the cache.
41       *
42       * @param username the {@link User#getUsername()} used to place the user in
43       *        the cache
44       *
45       * @return the populated <code>UserDetails</code> or <code>null</code> if
46       *         the user could not be found or if the cache entry has expired
47       */
48      public UserDetails getUserFromCache(String username);
49  
50      /***
51       * Places a {@link UserDetails} in the cache. The <code>username</code> is
52       * the key used to subsequently retrieve the <code>UserDetails</code>.
53       *
54       * @param user the fully populated <code>UserDetails</code> to place in the
55       *        cache
56       */
57      public void putUserInCache(UserDetails user);
58  
59      /***
60       * Removes the specified user from the cache. The <code>username</code> is
61       * the key used to remove the user. If the user is not found, the method
62       * should simply return (not thrown an exception).
63       * 
64       * <P>
65       * Some cache implementations may not support eviction from the cache,  in
66       * which case they should provide appropriate behaviour to alter the user
67       * in either its documentation, via an exception, or through a log
68       * message.
69       * </p>
70       *
71       * @param username to be evicted from the cache
72       */
73      public void removeUserFromCache(String username);
74  }