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 java.util.Dictionary;
019
020 /**
021 * A <code>User</code> role managed by a User Admin service.
022 *
023 * <p>
024 * In this context, the term "user" is not limited to just human
025 * beings. Instead, it refers to any entity that may have any number of
026 * credentials associated with it that it may use to authenticate itself.
027 * <p>
028 * In general, <code>User</code> objects are associated with a specific User Admin
029 * service (namely the one that created them), and cannot be used with other
030 * User Admin services.
031 * <p>
032 * A <code>User</code> object may have credentials (and properties, inherited from
033 * the {@link Role} class) associated with it. Specific
034 * {@link UserAdminPermission} objects are required to read or change a
035 * <code>User</code> object's credentials.
036 * <p>
037 * Credentials are <code>Dictionary</code> objects and have semantics that are
038 * similar to the properties in the <code>Role</code> class.
039 *
040 * @version $Revision: 5673 $
041 */
042 public interface User extends Role {
043 /**
044 * Returns a <code>Dictionary</code> of the credentials of this <code>User</code>
045 * object. Any changes to the returned <code>Dictionary</code> object will
046 * change the credentials of this <code>User</code> object. This will cause a
047 * <code>UserAdminEvent</code> object of type
048 * {@link UserAdminEvent#ROLE_CHANGED} to be broadcast to any
049 * <code>UserAdminListeners</code> objects.
050 *
051 * <p>
052 * Only objects of type <code>String</code> may be used as credential keys,
053 * and only objects of type <code>String</code> or of type <code>byte[]</code>
054 * may be used as credential values. Any other types will cause an exception
055 * of type <code>IllegalArgumentException</code> to be raised.
056 *
057 * <p>
058 * In order to retrieve a credential from the returned <code>Dictionary</code>
059 * object, a {@link UserAdminPermission} named after the credential name (or
060 * a prefix of it) with action <code>getCredential</code> is required.
061 * <p>
062 * In order to add or remove a credential from the returned
063 * <code>Dictionary</code> object, a {@link UserAdminPermission} named after
064 * the credential name (or a prefix of it) with action
065 * <code>changeCredential</code> is required.
066 *
067 * @return <code>Dictionary</code> object containing the credentials of this
068 * <code>User</code> object.
069 */
070 public Dictionary getCredentials();
071
072 /**
073 * Checks to see if this <code>User</code> object has a credential with the
074 * specified <code>key</code> set to the specified <code>value</code>.
075 *
076 * <p>
077 * If the specified credential <code>value</code> is not of type
078 * <code>String</code> or <code>byte[]</code>, it is ignored, that is,
079 * <code>false</code> is returned (as opposed to an
080 * <code>IllegalArgumentException</code> being raised).
081 *
082 * @param key The credential <code>key</code>.
083 * @param value The credential <code>value</code>.
084 *
085 * @return <code>true</code> if this user has the specified credential;
086 * <code>false</code> otherwise.
087 *
088 * @throws SecurityException If a security manager exists and the caller
089 * does not have the <code>UserAdminPermission</code> named after the
090 * credential key (or a prefix of it) with action
091 * <code>getCredential</code>.
092 */
093 public boolean hasCredential(String key, Object value);
094 }