001 /*
002 * Copyright (c) OSGi Alliance (2001, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.useradmin;
017
018 import org.osgi.framework.InvalidSyntaxException;
019
020 /**
021 * This interface is used to manage a database of named <code>Role</code> objects,
022 * which can be used for authentication and authorization purposes.
023 *
024 * <p>
025 * This version of the User Admin service defines two types of <code>Role</code>
026 * objects: "User" and "Group". Each type of role is represented by an
027 * <code>int</code> constant and an interface. The range of positive integers is
028 * reserved for new types of roles that may be added in the future. When
029 * defining proprietary role types, negative constant values must be used.
030 *
031 * <p>
032 * Every role has a name and a type.
033 *
034 * <p>
035 * A {@link User} object can be configured with credentials (e.g., a password)
036 * and properties (e.g., a street address, phone number, etc.).
037 * <p>
038 * A {@link Group} object represents an aggregation of {@link User} and
039 * {@link Group} objects. In other words, the members of a <code>Group</code>
040 * object are roles themselves.
041 * <p>
042 * Every User Admin service manages and maintains its own namespace of
043 * <code>Role</code> objects, in which each <code>Role</code> object has a unique
044 * name.
045 *
046 * @version $Revision: 5673 $
047 */
048 public interface UserAdmin {
049 /**
050 * Creates a <code>Role</code> object with the given name and of the given
051 * type.
052 *
053 * <p>
054 * If a <code>Role</code> object was created, a <code>UserAdminEvent</code>
055 * object of type {@link UserAdminEvent#ROLE_CREATED} is broadcast to any
056 * <code>UserAdminListener</code> object.
057 *
058 * @param name The <code>name</code> of the <code>Role</code> object to create.
059 * @param type The type of the <code>Role</code> object to create. Must be
060 * either a {@link Role#USER} type or {@link Role#GROUP} type.
061 *
062 * @return The newly created <code>Role</code> object, or <code>null</code> if a
063 * role with the given name already exists.
064 *
065 * @throws IllegalArgumentException if <code>type</code> is invalid.
066 *
067 * @throws SecurityException If a security manager exists and the caller
068 * does not have the <code>UserAdminPermission</code> with name
069 * <code>admin</code>.
070 */
071 public Role createRole(String name, int type);
072
073 /**
074 * Removes the <code>Role</code> object with the given name from this User
075 * Admin service and all groups it is a member of.
076 *
077 * <p>
078 * If the <code>Role</code> object was removed, a <code>UserAdminEvent</code>
079 * object of type {@link UserAdminEvent#ROLE_REMOVED} is broadcast to any
080 * <code>UserAdminListener</code> object.
081 *
082 * @param name The name of the <code>Role</code> object to remove.
083 *
084 * @return <code>true</code> If a <code>Role</code> object with the given name
085 * is present in this User Admin service and could be removed,
086 * otherwise <code>false</code>.
087 *
088 * @throws SecurityException If a security manager exists and the caller
089 * does not have the <code>UserAdminPermission</code> with name
090 * <code>admin</code>.
091 */
092 public boolean removeRole(String name);
093
094 /**
095 * Gets the <code>Role</code> object with the given <code>name</code> from this
096 * User Admin service.
097 *
098 * @param name The name of the <code>Role</code> object to get.
099 *
100 * @return The requested <code>Role</code> object, or <code>null</code> if this
101 * User Admin service does not have a <code>Role</code> object with
102 * the given <code>name</code>.
103 */
104 public Role getRole(String name);
105
106 /**
107 * Gets the <code>Role</code> objects managed by this User Admin service that
108 * have properties matching the specified LDAP filter criteria. See
109 * <code>org.osgi.framework.Filter</code> for a description of the filter
110 * syntax. If a <code>null</code> filter is specified, all Role objects
111 * managed by this User Admin service are returned.
112 *
113 * @param filter The filter criteria to match.
114 *
115 * @return The <code>Role</code> objects managed by this User Admin service
116 * whose properties match the specified filter criteria, or all
117 * <code>Role</code> objects if a <code>null</code> filter is specified.
118 * If no roles match the filter, <code>null</code> will be returned.
119 * @throws InvalidSyntaxException If the filter is not well formed.
120 *
121 */
122 public Role[] getRoles(String filter) throws InvalidSyntaxException;
123
124 /**
125 * Gets the user with the given property <code>key</code>-<code>value</code>
126 * pair from the User Admin service database. This is a convenience method
127 * for retrieving a <code>User</code> object based on a property for which
128 * every <code>User</code> object is supposed to have a unique value (within
129 * the scope of this User Admin service), such as for example a X.500
130 * distinguished name.
131 *
132 * @param key The property key to look for.
133 * @param value The property value to compare with.
134 *
135 * @return A matching user, if <em>exactly</em> one is found. If zero or
136 * more than one matching users are found, <code>null</code> is
137 * returned.
138 */
139 public User getUser(String key, String value);
140
141 /**
142 * Creates an <code>Authorization</code> object that encapsulates the
143 * specified <code>User</code> object and the <code>Role</code> objects it
144 * possesses. The <code>null</code> user is interpreted as the anonymous user.
145 * The anonymous user represents a user that has not been authenticated. An
146 * <code>Authorization</code> object for an anonymous user will be unnamed,
147 * and will only imply groups that user.anyone implies.
148 *
149 * @param user The <code>User</code> object to create an
150 * <code>Authorization</code> object for, or <code>null</code> for the
151 * anonymous user.
152 *
153 * @return the <code>Authorization</code> object for the specified
154 * <code>User</code> object.
155 */
156 public Authorization getAuthorization(User user);
157 }