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 * The base interface for <code>Role</code> objects managed by the User Admin
022 * service.
023 *
024 * <p>
025 * This interface exposes the characteristics shared by all <code>Role</code>
026 * classes: a name, a type, and a set of properties.
027 * <p>
028 * Properties represent public information about the <code>Role</code> object that
029 * can be read by anyone. Specific {@link UserAdminPermission} objects are
030 * required to change a <code>Role</code> object's properties.
031 * <p>
032 * <code>Role</code> object properties are <code>Dictionary</code> objects. Changes
033 * to these objects are propagated to the User Admin service and made
034 * persistent.
035 * <p>
036 * Every User Admin service contains a set of predefined <code>Role</code> objects
037 * that are always present and cannot be removed. All predefined <code>Role</code>
038 * objects are of type <code>ROLE</code>. This version of the
039 * <code>org.osgi.service.useradmin</code> package defines a single predefined
040 * role named "user.anyone", which is inherited by any other role.
041 * Other predefined roles may be added in the future. Since
042 * "user.anyone" is a <code>Role</code> object that has properties
043 * associated with it that can be read and modified. Access to these properties
044 * and their use is application specific and is controlled using
045 * <code>UserAdminPermission</code> in the same way that properties for other
046 * <code>Role</code> objects are.
047 *
048 * @version $Revision: 5673 $
049 */
050 public interface Role {
051 /**
052 * The name of the predefined role, user.anyone, that all users and groups
053 * belong to.
054 * @since 1.1
055 */
056 public static final String USER_ANYONE = "user.anyone";
057 /**
058 * The type of a predefined role.
059 *
060 * <p>
061 * The value of <code>ROLE</code> is 0.
062 */
063 public static final int ROLE = 0;
064 /**
065 * The type of a {@link User} role.
066 *
067 * <p>
068 * The value of <code>USER</code> is 1.
069 */
070 public static final int USER = 1;
071 /**
072 * The type of a {@link Group} role.
073 *
074 * <p>
075 * The value of <code>GROUP</code> is 2.
076 */
077 public static final int GROUP = 2;
078
079 /**
080 * Returns the name of this role.
081 *
082 * @return The role's name.
083 */
084 public String getName();
085
086 /**
087 * Returns the type of this role.
088 *
089 * @return The role's type.
090 */
091 public int getType();
092
093 /**
094 * Returns a <code>Dictionary</code> of the (public) properties of this
095 * <code>Role</code> object. Any changes to the returned <code>Dictionary</code>
096 * will change the properties of this <code>Role</code> object. This will
097 * cause a <code>UserAdminEvent</code> object of type
098 * {@link UserAdminEvent#ROLE_CHANGED} to be broadcast to any
099 * <code>UserAdminListener</code> objects.
100 *
101 * <p>
102 * Only objects of type <code>String</code> may be used as property keys, and
103 * only objects of type <code>String</code> or <code>byte[]</code> may be used
104 * as property values. Any other types will cause an exception of type
105 * <code>IllegalArgumentException</code> to be raised.
106 *
107 * <p>
108 * In order to add, change, or remove a property in the returned
109 * <code>Dictionary</code>, a {@link UserAdminPermission} named after the
110 * property name (or a prefix of it) with action <code>changeProperty</code>
111 * is required.
112 *
113 * @return <code>Dictionary</code> containing the properties of this
114 * <code>Role</code> object.
115 */
116 public Dictionary getProperties();
117 }