org.osgi.service.useradmin.UserAdmin Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2001, 2008). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.service.useradmin;
import org.osgi.framework.InvalidSyntaxException;
/**
* This interface is used to manage a database of named Role objects,
* which can be used for authentication and authorization purposes.
*
*
* This version of the User Admin service defines two types of Role
* objects: "User" and "Group". Each type of role is represented by an
* int constant and an interface. The range of positive integers is
* reserved for new types of roles that may be added in the future. When
* defining proprietary role types, negative constant values must be used.
*
*
* Every role has a name and a type.
*
*
* A {@link User} object can be configured with credentials (e.g., a password)
* and properties (e.g., a street address, phone number, etc.).
*
* A {@link Group} object represents an aggregation of {@link User} and
* {@link Group} objects. In other words, the members of a Group
* object are roles themselves.
*
* Every User Admin service manages and maintains its own namespace of
* Role objects, in which each Role object has a unique
* name.
*
* @version $Revision: 5673 $
*/
public interface UserAdmin {
/**
* Creates a Role object with the given name and of the given
* type.
*
*
* If a Role object was created, a UserAdminEvent
* object of type {@link UserAdminEvent#ROLE_CREATED} is broadcast to any
* UserAdminListener object.
*
* @param name The name of the Role object to create.
* @param type The type of the Role object to create. Must be
* either a {@link Role#USER} type or {@link Role#GROUP} type.
*
* @return The newly created Role object, or null if a
* role with the given name already exists.
*
* @throws IllegalArgumentException if type is invalid.
*
* @throws SecurityException If a security manager exists and the caller
* does not have the UserAdminPermission with name
* admin.
*/
public Role createRole(String name, int type);
/**
* Removes the Role object with the given name from this User
* Admin service and all groups it is a member of.
*
*
* If the Role object was removed, a UserAdminEvent
* object of type {@link UserAdminEvent#ROLE_REMOVED} is broadcast to any
* UserAdminListener object.
*
* @param name The name of the Role object to remove.
*
* @return true If a Role object with the given name
* is present in this User Admin service and could be removed,
* otherwise false.
*
* @throws SecurityException If a security manager exists and the caller
* does not have the UserAdminPermission with name
* admin.
*/
public boolean removeRole(String name);
/**
* Gets the Role object with the given name from this
* User Admin service.
*
* @param name The name of the Role object to get.
*
* @return The requested Role object, or null if this
* User Admin service does not have a Role object with
* the given name.
*/
public Role getRole(String name);
/**
* Gets the Role objects managed by this User Admin service that
* have properties matching the specified LDAP filter criteria. See
* org.osgi.framework.Filter for a description of the filter
* syntax. If a null filter is specified, all Role objects
* managed by this User Admin service are returned.
*
* @param filter The filter criteria to match.
*
* @return The Role objects managed by this User Admin service
* whose properties match the specified filter criteria, or all
* Role objects if a null filter is specified.
* If no roles match the filter, null will be returned.
* @throws InvalidSyntaxException If the filter is not well formed.
*
*/
public Role[] getRoles(String filter) throws InvalidSyntaxException;
/**
* Gets the user with the given property key-value
* pair from the User Admin service database. This is a convenience method
* for retrieving a User object based on a property for which
* every User object is supposed to have a unique value (within
* the scope of this User Admin service), such as for example a X.500
* distinguished name.
*
* @param key The property key to look for.
* @param value The property value to compare with.
*
* @return A matching user, if exactly one is found. If zero or
* more than one matching users are found, null is
* returned.
*/
public User getUser(String key, String value);
/**
* Creates an Authorization object that encapsulates the
* specified User object and the Role objects it
* possesses. The null user is interpreted as the anonymous user.
* The anonymous user represents a user that has not been authenticated. An
* Authorization object for an anonymous user will be unnamed,
* and will only imply groups that user.anyone implies.
*
* @param user The User object to create an
* Authorization object for, or null for the
* anonymous user.
*
* @return the Authorization object for the specified
* User object.
*/
public Authorization getAuthorization(User user);
}