KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > catalina > Realm


1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */

17
18
19 package org.apache.catalina;
20
21 import java.beans.PropertyChangeListener JavaDoc;
22 import java.io.IOException JavaDoc;
23 import java.security.Principal JavaDoc;
24 import java.security.cert.X509Certificate JavaDoc;
25
26 import org.apache.catalina.connector.Request;
27 import org.apache.catalina.connector.Response;
28 import org.apache.catalina.deploy.SecurityConstraint;
29 /**
30  * A <b>Realm</b> is a read-only facade for an underlying security realm
31  * used to authenticate individual users, and identify the security roles
32  * associated with those users. Realms can be attached at any Container
33  * level, but will typically only be attached to a Context, or higher level,
34  * Container.
35  *
36  * @author Craig R. McClanahan
37  * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
38  */

39
40 public interface Realm {
41
42
43     // ------------------------------------------------------------- Properties
44

45
46     /**
47      * Return the Container with which this Realm has been associated.
48      */

49     public Container getContainer();
50
51
52     /**
53      * Set the Container with which this Realm has been associated.
54      *
55      * @param container The associated Container
56      */

57     public void setContainer(Container container);
58
59
60     /**
61      * Return descriptive information about this Realm implementation and
62      * the corresponding version number, in the format
63      * <code>&lt;description&gt;/&lt;version&gt;</code>.
64      */

65     public String JavaDoc getInfo();
66
67
68     // --------------------------------------------------------- Public Methods
69

70     
71     /**
72      * Add a property change listener to this component.
73      *
74      * @param listener The listener to add
75      */

76     public void addPropertyChangeListener(PropertyChangeListener JavaDoc listener);
77
78
79     /**
80      * Return the Principal associated with the specified username and
81      * credentials, if there is one; otherwise return <code>null</code>.
82      *
83      * @param username Username of the Principal to look up
84      * @param credentials Password or other credentials to use in
85      * authenticating this username
86      */

87     public Principal JavaDoc authenticate(String JavaDoc username, String JavaDoc credentials);
88
89
90     /**
91      * Return the Principal associated with the specified username and
92      * credentials, if there is one; otherwise return <code>null</code>.
93      *
94      * @param username Username of the Principal to look up
95      * @param credentials Password or other credentials to use in
96      * authenticating this username
97      */

98     public Principal JavaDoc authenticate(String JavaDoc username, byte[] credentials);
99
100
101     /**
102      * Return the Principal associated with the specified username, which
103      * matches the digest calculated using the given parameters using the
104      * method described in RFC 2069; otherwise return <code>null</code>.
105      *
106      * @param username Username of the Principal to look up
107      * @param digest Digest which has been submitted by the client
108      * @param nonce Unique (or supposedly unique) token which has been used
109      * for this request
110      * @param realm Realm name
111      * @param md5a2 Second MD5 digest used to calculate the digest :
112      * MD5(Method + ":" + uri)
113      */

114     public Principal JavaDoc authenticate(String JavaDoc username, String JavaDoc digest,
115                                   String JavaDoc nonce, String JavaDoc nc, String JavaDoc cnonce,
116                                   String JavaDoc qop, String JavaDoc realm,
117                                   String JavaDoc md5a2);
118
119
120     /**
121      * Return the Principal associated with the specified chain of X509
122      * client certificates. If there is none, return <code>null</code>.
123      *
124      * @param certs Array of client certificates, with the first one in
125      * the array being the certificate of the client itself.
126      */

127     public Principal JavaDoc authenticate(X509Certificate JavaDoc certs[]);
128     
129     
130     /**
131      * Execute a periodic task, such as reloading, etc. This method will be
132      * invoked inside the classloading context of this container. Unexpected
133      * throwables will be caught and logged.
134      */

135     public void backgroundProcess();
136
137
138     /**
139      * Return the SecurityConstraints configured to guard the request URI for
140      * this request, or <code>null</code> if there is no such constraint.
141      *
142      * @param request Request we are processing
143      */

144     public SecurityConstraint [] findSecurityConstraints(Request request,
145                                                      Context context);
146     
147     
148     /**
149      * Perform access control based on the specified authorization constraint.
150      * Return <code>true</code> if this constraint is satisfied and processing
151      * should continue, or <code>false</code> otherwise.
152      *
153      * @param request Request we are processing
154      * @param response Response we are creating
155      * @param constraint Security constraint we are enforcing
156      * @param context The Context to which client of this class is attached.
157      *
158      * @exception IOException if an input/output error occurs
159      */

160     public boolean hasResourcePermission(Request request,
161                                          Response response,
162                                          SecurityConstraint [] constraint,
163                                          Context context)
164         throws IOException JavaDoc;
165     
166     
167     /**
168      * Return <code>true</code> if the specified Principal has the specified
169      * security role, within the context of this Realm; otherwise return
170      * <code>false</code>.
171      *
172      * @param principal Principal for whom the role is to be checked
173      * @param role Security role to be checked
174      */

175     public boolean hasRole(Principal JavaDoc principal, String JavaDoc role);
176
177         /**
178      * Enforce any user data constraint required by the security constraint
179      * guarding this request URI. Return <code>true</code> if this constraint
180      * was not violated and processing should continue, or <code>false</code>
181      * if we have created a response already.
182      *
183      * @param request Request we are processing
184      * @param response Response we are creating
185      * @param constraint Security constraint being checked
186      *
187      * @exception IOException if an input/output error occurs
188      */

189     public boolean hasUserDataPermission(Request request,
190                                          Response response,
191                                          SecurityConstraint []constraint)
192         throws IOException JavaDoc;
193     
194     /**
195      * Remove a property change listener from this component.
196      *
197      * @param listener The listener to remove
198      */

199     public void removePropertyChangeListener(PropertyChangeListener JavaDoc listener);
200
201
202 }
203
Popular Tags