KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > useradmin > UserAdmin


1 /*
2  * $Header: /cvshome/build/org.osgi.service.useradmin/src/org/osgi/service/useradmin/UserAdmin.java,v 1.12 2006/07/12 21:21:33 hargrave Exp $
3  *
4  * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package org.osgi.service.useradmin;
19
20 import org.osgi.framework.InvalidSyntaxException;
21
22 /**
23  * This interface is used to manage a database of named <code>Role</code> objects,
24  * which can be used for authentication and authorization purposes.
25  *
26  * <p>
27  * This version of the User Admin service defines two types of <code>Role</code>
28  * objects: "User" and "Group". Each type of role is represented by an
29  * <code>int</code> constant and an interface. The range of positive integers is
30  * reserved for new types of roles that may be added in the future. When
31  * defining proprietary role types, negative constant values must be used.
32  *
33  * <p>
34  * Every role has a name and a type.
35  *
36  * <p>
37  * A {@link User} object can be configured with credentials (e.g., a password)
38  * and properties (e.g., a street address, phone number, etc.).
39  * <p>
40  * A {@link Group} object represents an aggregation of {@link User} and
41  * {@link Group} objects. In other words, the members of a <code>Group</code>
42  * object are roles themselves.
43  * <p>
44  * Every User Admin service manages and maintains its own namespace of
45  * <code>Role</code> objects, in which each <code>Role</code> object has a unique
46  * name.
47  *
48  * @version $Revision: 1.12 $
49  */
50 public interface UserAdmin {
51     /**
52      * Creates a <code>Role</code> object with the given name and of the given
53      * type.
54      *
55      * <p>
56      * If a <code>Role</code> object was created, a <code>UserAdminEvent</code>
57      * object of type {@link UserAdminEvent#ROLE_CREATED} is broadcast to any
58      * <code>UserAdminListener</code> object.
59      *
60      * @param name The <code>name</code> of the <code>Role</code> object to create.
61      * @param type The type of the <code>Role</code> object to create. Must be
62      * either a {@link Role#USER} type or {@link Role#GROUP} type.
63      *
64      * @return The newly created <code>Role</code> object, or <code>null</code> if a
65      * role with the given name already exists.
66      *
67      * @throws IllegalArgumentException if <code>type</code> is invalid.
68      *
69      * @throws SecurityException If a security manager exists and the caller
70      * does not have the <code>UserAdminPermission</code> with name
71      * <code>admin</code>.
72      */
73     public Role createRole(String JavaDoc name, int type);
74
75     /**
76      * Removes the <code>Role</code> object with the given name from this User
77      * Admin service.
78      *
79      * <p>
80      * If the <code>Role</code> object was removed, a <code>UserAdminEvent</code>
81      * object of type {@link UserAdminEvent#ROLE_REMOVED} is broadcast to any
82      * <code>UserAdminListener</code> object.
83      *
84      * @param name The name of the <code>Role</code> object to remove.
85      *
86      * @return <code>true</code> If a <code>Role</code> object with the given name
87      * is present in this User Admin service and could be removed,
88      * otherwise <code>false</code>.
89      *
90      * @throws SecurityException If a security manager exists and the caller
91      * does not have the <code>UserAdminPermission</code> with name
92      * <code>admin</code>.
93      */
94     public boolean removeRole(String JavaDoc name);
95
96     /**
97      * Gets the <code>Role</code> object with the given <code>name</code> from this
98      * User Admin service.
99      *
100      * @param name The name of the <code>Role</code> object to get.
101      *
102      * @return The requested <code>Role</code> object, or <code>null</code> if this
103      * User Admin service does not have a <code>Role</code> object with
104      * the given <code>name</code>.
105      */
106     public Role getRole(String JavaDoc name);
107
108     /**
109      * Gets the <code>Role</code> objects managed by this User Admin service that
110      * have properties matching the specified LDAP filter criteria. See
111      * <code>org.osgi.framework.Filter</code> for a description of the filter
112      * syntax. If a <code>null</code> filter is specified, all Role objects
113      * managed by this User Admin service are returned.
114      *
115      * @param filter The filter criteria to match.
116      *
117      * @return The <code>Role</code> objects managed by this User Admin service
118      * whose properties match the specified filter criteria, or all
119      * <code>Role</code> objects if a <code>null</code> filter is specified.
120      * If no roles match the filter, <code>null</code> will be returned.
121      * @throws InvalidSyntaxException If the filter is not well formed.
122      *
123      */
124     public Role[] getRoles(String JavaDoc filter) throws InvalidSyntaxException;
125
126     /**
127      * Gets the user with the given property <code>key</code>-<code>value</code>
128      * pair from the User Admin service database. This is a convenience method
129      * for retrieving a <code>User</code> object based on a property for which
130      * every <code>User</code> object is supposed to have a unique value (within
131      * the scope of this User Admin service), such as for example a X.500
132      * distinguished name.
133      *
134      * @param key The property key to look for.
135      * @param value The property value to compare with.
136      *
137      * @return A matching user, if <em>exactly</em> one is found. If zero or
138      * more than one matching users are found, <code>null</code> is
139      * returned.
140      */
141     public User getUser(String JavaDoc key, String JavaDoc value);
142
143     /**
144      * Creates an <code>Authorization</code> object that encapsulates the
145      * specified <code>User</code> object and the <code>Role</code> objects it
146      * possesses. The <code>null</code> user is interpreted as the anonymous user.
147      * The anonymous user represents a user that has not been authenticated. An
148      * <code>Authorization</code> object for an anonymous user will be unnamed,
149      * and will only imply groups that user.anyone implies.
150      *
151      * @param user The <code>User</code> object to create an
152      * <code>Authorization</code> object for, or <code>null</code> for the
153      * anonymous user.
154      *
155      * @return the <code>Authorization</code> object for the specified
156      * <code>User</code> object.
157      */
158     public Authorization getAuthorization(User user);
159 }
160
Popular Tags