/*******************************************************************************
* Copyright (c) 2001, 2008 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.equinox.internal.useradmin;
import java.util.Enumeration;
import java.util.Vector;
import org.osgi.service.prefs.BackingStoreException;
/**
* A named grouping of roles.
* <p>
* Whether or not a given authorization context implies a Group role
* depends on the members of that role.
* <p>
* A Group role can have two kinds of member roles: <i>basic</i> and
* <i>required</i>.
* A Group role is implied by an authorization context if all of
* its required member roles are implied
* and at least one of its basic member roles is implied.
* <p>
* A Group role must contain at least one basic member role in order
* to be implied. In other words, a Group without any basic member
* roles is never implied by any authorization context.
* <p>
* A User role always implies itself.
* <p>
* No loop detection is performed when adding members to groups, which
* means that it is possible to create circular implications. Loop
* detection is instead done when roles are checked. The semantics is that
* if a role depends on itself (i.e., there is an implication loop), the
* role is not implied.
* <p>
* The rule that a group must have at least one basic member to be implied
* is motivated by the following example:
*
* <pre>
* group foo
* required members: marketing
* basic members: alice, bob
* </pre>
*
* Privileged operations that require membership in "foo" can be performed
* only by alice and bob, who are in marketing.
* <p>
* If alice and bob ever transfer to a different department, anybody in
* marketing will be able to assume the "foo" role, which certainly must be
* prevented.
* Requiring that "foo" (or any Group role for that matter) must have at least
* one basic member accomplishes that.
* <p>
* However, this would make it impossible for a group to be implied by just
* its required members. An example where this implication might be useful
* is the following declaration: "Any citizen who is an adult is allowed to
* vote."
* An intuitive configuration of "voter" would be:
*
* <pre>
* group voter
* required members: citizen, adult
* basic members:
* </pre>
*
* However, according to the above rule, the "voter" role could never be
* assumed by anybody, since it lacks any basic members.
* In order to address this deficiency a predefined role named
* "user.anyone" can be specified, which is always implied.
* The desired implication of the "voter" group can then be achieved by
* specifying "user.anyone" as its basic member, as follows:
*
* <pre>
* group voter
* required members: citizen, adult
* basic members: user.anyone
* </pre>
*/
public class Group extends User implements org.osgi.service.useradmin.Group {
protected Vector requiredMembers;
protected Vector basicMembers;
protected Group(String name, UserAdmin useradmin) {
super(name, useradmin);
this.useradmin = useradmin;
basicMembers = new Vector();
requiredMembers = new Vector();
}
/**
* Adds the specified role as a basic member to this Group.
*
* @param role The role to add as a basic member.
*
* @return <code>true</code> if the given role could be added as a basic
* member,
* and <code>false</code> if this Group already contains a role whose name
* matches that of the specified role.
*
* @throws SecurityException If a security manager exists and the caller
* does not have the <tt>UserAdminPermission</tt> with name <tt>admin</tt>.
*/
public boolean addMember(org.osgi.service.useradmin.Role role) {
useradmin.checkAlive();
useradmin.checkAdminPermission();
//only need to check for null for the public methods
if (role == null) {
return (false);
}
synchronized (useradmin) {
if (basicMembers.contains(role)) {
return (false);
}
return (addMember(role, true));
}
}
// When we are loading from storage this method is called directly. We
// do not want to write to storage when we are loading form storage.
protected boolean addMember(org.osgi.service.useradmin.Role role, boolean store) {
((org.eclipse.equinox.internal.useradmin.Role) role).addImpliedRole(this);
if (store) {
try {
useradmin.userAdminStore.addMember(this, (org.eclipse.equinox.internal.useradmin.Role) role);
} catch (BackingStoreException ex) {
return (false);
}
}
basicMembers.addElement(role);
return (true);
}
/**
* Adds the specified role as a required member to this Group.
*
* @param role The role to add as a required member.
*
* @return <code>true</code> if the given role could be added as a required
* member, and <code>false</code> if this Group already contains a role
* whose name matches that of the specified role.
*
* @throws SecurityException If a security manager exists and the caller
* does not have the <tt>UserAdminPermission</tt> with name <tt>admin</tt>.
*/
public boolean addRequiredMember(org.osgi.service.useradmin.Role role) {
useradmin.checkAlive();
useradmin.checkAdminPermission();
if (role == null) {
return (false);
}
synchronized (useradmin) {
if (requiredMembers.contains(role)) {
return (false);
}
return (addRequiredMember(role, true));
}
}
protected boolean addRequiredMember(org.osgi.service.useradmin.Role role, boolean store) {
((org.eclipse.equinox.internal.useradmin.Role) role).addImpliedRole(this);
if (store) {
try {
useradmin.userAdminStore.addRequiredMember(this, (org.eclipse.equinox.internal.useradmin.Role) role);
} catch (BackingStoreException ex) {
return (false);
}
}
requiredMembers.addElement(role);
return (true);
}
/**
* Removes the specified role from this Group.
*
* @param role The role to remove from this Group.
*
* @return <code>true</code> if the role could be removed,
* otherwise <code>false</code>.
*
* @throws SecurityException If a security manager exists and the caller
* does not have the <tt>UserAdminPermission</tt> with name <tt>admin</tt>.
*/
public boolean removeMember(org.osgi.service.useradmin.Role role) {
useradmin.checkAlive();
useradmin.checkAdminPermission();
if (role == null) {
return (false);
}
synchronized (useradmin) {
try {
useradmin.userAdminStore.removeMember(this, (org.eclipse.equinox.internal.useradmin.Role) role);
} catch (BackingStoreException ex) {
return (false);
}
//The role keeps track of which groups it is a member of so it can remove itself from
//the group if it is deleted. In this case, this group is being removed from the role's
//list.
((org.eclipse.equinox.internal.useradmin.Role) role).removeImpliedRole(this);
// We don't know if the Role to be removed is a basic orrequired member, or both. We
// simply try to remove it from both.
boolean removeRequired = requiredMembers.removeElement(role);
boolean removeBasic = basicMembers.removeElement(role);
return (removeRequired || removeBasic);
}
}
/**
* Gets the basic members of this Group.
*
* @return The basic members of this Group, or <code>null</code> if this
* Group does not contain any basic members.
*/
public org.osgi.service.useradmin.Role[] getMembers() {
useradmin.checkAlive();
synchronized (useradmin) {
if (basicMembers.isEmpty()) {
return (null);
}
Role[] roles = new Role[basicMembers.size()];
basicMembers.copyInto(roles);
return (roles);
}
}
/**
* Gets the required members of this Group.
*
* @return The required members of this Group, or <code>null</code> if this
* Group does not contain any required members.
*/
public org.osgi.service.useradmin.Role[] getRequiredMembers() {
useradmin.checkAlive();
synchronized (useradmin) {
if (requiredMembers.isEmpty()) {
return (null);
}
Role[] roles = new Role[requiredMembers.size()];
requiredMembers.copyInto(roles);
return (roles);
}
}
/**
* Returns the type of this role.
*
* @return The role's type.
*/
public int getType() {
useradmin.checkAlive();
return (org.osgi.service.useradmin.Role.GROUP);
}
protected boolean isImpliedBy(Role role, Vector checkLoop) {
if (checkLoop.contains(name)) {
//we have a circular dependency
return (false);
}
if (name.equals(role.getName())) //A User always implies itself. A Group is a User.
{
return (true);
}
checkLoop.addElement(name);
Vector requiredCheckLoop = (Vector) checkLoop.clone();
Vector basicCheckLoop = (Vector) checkLoop.clone();
Enumeration e = requiredMembers.elements();
//check to see if we imply all of the 0 or more required roles
Role requiredRole;
while (e.hasMoreElements()) {
requiredRole = (Role) e.nextElement();
if (!requiredRole.isImpliedBy(role, requiredCheckLoop)) {
return (false);
}
}
//check to see if we imply any of the basic roles (there must be at least one)
e = basicMembers.elements();
Role basicRole;
while (e.hasMoreElements()) {
basicRole = (Role) e.nextElement();
if (basicRole.isImpliedBy(role, basicCheckLoop)) {
return (true);
}
}
return (false);
}
}