UserRealm


1   // ========================================================================
2   // $Id: UserRealm.java,v 1.16 2006/02/28 12:45:01 gregwilkins Exp $
3   // Copyright 1996-2004 Mort Bay Consulting Pty. Ltd.
4   // ------------------------------------------------------------------------
5   // Licensed under the Apache License, Version 2.0 (the "License");
6   // you may not use this file except in compliance with the License.
7   // You may obtain a copy of the License at 
8   // http://www.apache.org/licenses/LICENSE-2.0
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.mortbay.http;
17  import java.security.Principal  ;
18  
19  /* ------------------------------------------------------------ */
20  /** User Realm.
21   *
22   * This interface should be specialized to provide specific user
23   * lookup and authentication using arbitrary methods.
24   *
25   * For SSO implementation sof UserRealm should also implement SSORealm.
26   *
27   * @see SSORealm
28   * @version $Id: UserRealm.java,v 1.16 2006/02/28 12:45:01 gregwilkins Exp $
29   * @author Greg Wilkins (gregw)
30   */
31  public interface UserRealm
32  {
33      /* ------------------------------------------------------------ */
34      public String   getName();
35  
36      /* ------------------------------------------------------------ */
37      /** Get the principal for a username.
38       * This method is not guaranteed to return a Principal for non-authenticated users.
39       */
40      public Principal   getPrincipal(String   username);
41      
42      /* ------------------------------------------------------------ */
43      /** Authenticate a users credentials.
44       * Implementations of this method may adorn the calling context to
45       * assoicate it with the authenticated principal (eg ThreadLocals). If
46       * such context associations are made, they should be considered valid
47       * until a UserRealm.deAuthenticate(UserPrincipal) call is made for this
48       * UserPrincipal.
49       * @param username The username. 
50       * @param credentials The user credentials, normally a String password. 
51       * @param request The request to be authenticated. Additional
52       * parameters may be extracted or set on this request as needed
53       * for the authentication mechanism (none required for BASIC and
54       * FORM authentication).
55       * @return The authenticated UserPrincipal.
56       */
57      public Principal   authenticate(String   username,Object   credentials,HttpRequest request);
58  
59      /* ------------------------------------------------------------ */
60      /** Re Authenticate a Principal.
61       * Authenicate a principal that has previously been return from the authenticate method.
62       * 
63       * Implementations of this method may adorn the calling context to
64       * assoicate it with the authenticated principal (eg ThreadLocals). If
65       * such context associations are made, they should be considered valid
66       * until a UserRealm.deAuthenticate(UserPrincipal) call is made for this
67       * UserPrincipal.
68       *
69       * @return True if this user is still authenticated.
70       */
71      public boolean reauthenticate(Principal   user);
72      
73      /* ------------------------------------------------------------ */
74      /** Check if the user is in a role. 
75       * @param role A role name.
76       * @return True if the user can act in that role.
77       */
78      public boolean isUserInRole(Principal   user, String   role);
79      
80      /* ------------------------------------------------------------ */
81      /** Dissassociate the calling context with a Principal.
82       * This method is called when the calling context is not longer
83       * associated with the Principal.  It should be used by an implementation
84       * to remove context associations such as ThreadLocals.
85       * The UserPrincipal object remains authenticated, as it may be
86       * associated with other contexts.
87       * @param user A UserPrincipal allocated from this realm.
88       */
89      public void disassociate(Principal   user);
90      
91      /* ------------------------------------------------------------ */
92      /** Push role onto a Principal.
93       * This method is used to add a role to an existing principal.
94       * @param user An existing UserPrincipal or null for an anonymous user.
95       * @param role The role to add.
96       * @return A new UserPrincipal object that wraps the passed user, but
97       * with the added role.
98       */
99      public Principal   pushRole(Principal   user, String   role);
100 
101 
102     /* ------------------------------------------------------------ */
103     /** Pop role from a Principal.
104      * @param user A UserPrincipal previously returned from pushRole
105      * @return The principal without the role.  Most often this will be the
106      * original UserPrincipal passed.
107      */
108     public Principal   popRole(Principal   user);
109 
110     /* ------------------------------------------------------------ */
111     /** logout a user Principal.
112      * Called by authentication mechanisms (eg FORM) that can detect logout.
113      * @param user A Principal previously returned from this realm
114      */
115     public void logout(Principal   user);
116     
117 }
118
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags