KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > mortbay > http > 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 JavaDoc;
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 JavaDoc 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 JavaDoc getPrincipal(String JavaDoc 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 JavaDoc authenticate(String JavaDoc username,Object JavaDoc 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 JavaDoc 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 JavaDoc user, String JavaDoc 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 JavaDoc 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 JavaDoc pushRole(Principal JavaDoc user, String JavaDoc 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 JavaDoc popRole(Principal JavaDoc 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 JavaDoc user);
116     
117 }
118
Popular Tags