com.sssw.rts.acl
Class AgoAcl

java.lang.Object
 |
 +--com.sssw.rts.acl.AgoAcl

All Implemented Interfaces:

Acl, Owner

public class AgoAcl

extends Object

implements Acl

Represents the access rights to a SilverStream object as an Access Control List. Note that not all SilverStream access rights are representable as an access control list -- only those that constitute "simple expressions".

An AgoAcl can be constructed "from scratch" -- e.g. by an application that is preparing to set security on an object -- or from the security expressions obtained from an already-stored object. In the latter case, the Acl is constructed with a MetaData tree containing the entire security information for the object (all types).

See Also:

Acl, AclEntry, AgoAclEntry

Constructor Summary

AgoAcl()

Method Summary

boolean	addEntry(Principal caller, AclEntry entry) Adds an ACL entry to this ACL.
boolean	addOwner(Principal caller, Principal owner) Adds an owner.
boolean	checkPermission(Principal principal, Permission permission) Checks whether or not the specified principal has the specified permission.
boolean	deleteOwner(Principal caller, Principal owner) Deletes an owner.
Enumeration	entries() Returns an enumeration of the entries in this ACL.
String	getName() Returns the name of this ACL.
Enumeration	getPermissions(Principal user) Returns an enumeration for the set of allowed permissions for the specified principal (representing an entity such as an individual or a group).
boolean	isOwner(Principal owner) Returns true if the given principal is an owner of the ACL.
boolean	removeEntry(Principal caller, AclEntry entry) Removes an ACL entry from this ACL.
void	setName(Principal caller, String name) Sets the name of this ACL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AgoAcl

public AgoAcl()

Method Detail

addOwner

public boolean addOwner(Principal caller,
                        Principal owner)
                 throws NotOwnerException

Adds an owner. Only owners can modify ACL contents. The caller principal must be an owner of the ACL in order to invoke this method. That is, only an owner can add another owner. The initial owner is configured at ACL construction time.

Specified by:

addOwner in interface Owner

Parameters:

caller - the principal invoking this method. It must be an owner of the ACL.

owner - the owner that should be added to the list of owners.

Returns:

true if successful, false if owner is already an owner.

Throws:

NotOwnerException - if the caller principal is not an owner of the ACL.

Usage:

This method is from java.security.acl.Owner.

Example:

// Create an ACL object.
 AgoAcl acl = ...
 // Set the caller.
 Principal prAclCaller = ...
 // Set the ACL owner.
 Principal prAclOwner = ...
 // Add an owner to the ACL.
 boolean success = acl.addOwner(prAclCaller, prAclOwner);
 

deleteOwner

public boolean deleteOwner(Principal caller,
                           Principal owner)
                    throws NotOwnerException,
                           LastOwnerException

Deletes an owner. If this is the last owner in the ACL, an exception is raised.

The caller principal must be an owner of the ACL in order to invoke this method.

Specified by:

deleteOwner in interface Owner

Parameters:

caller - the principal invoking this method. It must be an owner of the ACL.

owner - the owner to be removed from the list of owners.

Returns:

true if the owner is removed, false if the owner is not part of the list of owners.

Throws:

NotOwnerException - if the caller principal is not an owner of the ACL.

LastOwnerException - if there is only one owner left, so that deleteOwner would leave the ACL owner-less.

Usage:

This method is from java.security.acl.Owner

Example:

// Create an ACL object.
 AgoAcl acl = ...
 // Set the caller.
 Principal prAclCaller = ...
 // Set the ACL owner.
 Principal prAclOwner = ...
 // Add an owner to the ACL.
 boolean success = acl.addOwner(prAclCaller, prAclOwner);
 // ... some processing
 // Delete the ACL owner
 success = acl.deleteOwner(prAclCaller, prAclOwner);
 

isOwner

public boolean isOwner(Principal owner)

Returns true if the given principal is an owner of the ACL.

Specified by:

isOwner in interface Owner

Parameters:

owner - the principal to be checked to determine whether or not it is an owner.

Returns:

true if the passed principal is in the list of owners, false if not.

Usage:

This method is from java.security.acl.Owner.

Example:

// Create an ACL object.
 AgoAcl acl = ...
 // ... set up the ACL
 // Set a Principal
 Principal pr = ...
 // See if the specified Principal is the owner of the ACL.
 boolean isOwner = acl.isOwner(pr);
 

setName

public void setName(Principal caller,
                    String name)
             throws NotOwnerException

Sets the name of this ACL.

Specified by:

setName in interface Acl

Parameters:

caller - the principal invoking this method. It must be an owner of this ACL.

name - the name to be given to this ACL.

Throws:

NotOwnerException - if the caller principal is not an owner of this ACL.

Usage:

This method is from java.security.acl.Acl

Example:

// Set the caller
 Principal prAclCaller = ...
 // Set the name of the ACL
 acl.setName(prAclCaller, "ACL1");
 

getName

public String getName()

Returns the name of this ACL.

Specified by:

getName in interface Acl

Returns:

the name of this ACL.

Usage:

This method is from java.security.acl.Acl.

Example:

String aclName = acl.getName();

addEntry

public boolean addEntry(Principal caller,
                        AclEntry entry)
                 throws NotOwnerException

Adds an ACL entry to this ACL. An entry associates a principal (e.g., an individual or a group) with a set of permissions. Each principal can have at most one positive ACL entry (specifying permissions to be granted to the principal) and one negative ACL entry (specifying permissions to be denied). If there is already an ACL entry of the same type (negative or positive) already in the ACL, false is returned.

Specified by:

addEntry in interface Acl

Parameters:

caller - the principal invoking this method. It must be an owner of this ACL.

entry - the ACL entry to be added to this ACL.

Returns:

true on success, false if an entry of the same type (positive or negative) for the same principal is already present in this ACL.

Throws:

NotOwnerException - if the caller principal is not an owner of this ACL.

Usage:

This method is from java.security.acl.Acl.

Example:

// Get the owner for the ACL.
 Principal owner = server.getCurrentPrincipal();
 
 // Add the "world" entry to the ACL.
 AclEntry world = server.createAclEntry();
 Principal w = server.getWorldPrincipal();
 world.setPrincipal(w);
 world.addPermission(AgoPermission.READ);
 acl.addEntry(owner, world);
 
 // Create an ACL entry
 AclEntry entry = server.createAclEntry();
 
 // Set the principal into the ACL entry
 Principal pr = server.parseUser("nightghost");
 entry.setPrincipal(pr);
 
 // Add the permission for the principal into the ACL entry
 entry.addPermission(AgoPermission.WRITE);
 
 // Add the entry to the ACL
 boolean success = acl.addEntry(owner, entry);
 

removeEntry

public boolean removeEntry(Principal caller,
                           AclEntry entry)
                    throws NotOwnerException

Removes an ACL entry from this ACL.

Specified by:

removeEntry in interface Acl

Parameters:

caller - the principal invoking this method. It must be an owner of this ACL.

entry - the ACL entry to be removed from this ACL.

Returns:

true on success, false if the entry is not part of this ACL.

Throws:

NotOwnerException - if the caller principal is not an owner of this Acl.

Usage:

This method is from java.security.acl.Acl.

Example:

boolean success = acl.removeEntry(owner, entry);

getPermissions

public Enumeration getPermissions(Principal user)

Returns an enumeration for the set of allowed permissions for the specified principal (representing an entity such as an individual or a group).

Specified by:

getPermissions in interface Acl

Parameters:

user - the principal whose permission set is to be returned.

Returns:

the permission set specifying the permissions the principal is allowed.

Usage:

The set of allowed permissions is calculated as follows:

• If there is no entry in this Access Control List for the specified principal, an empty permission set is returned.

• Otherwise, the principal's group permission sets are determined. (A principal can belong to one or more groups, where a group is a group of principals, represented by the Group interface.) The group positive permission set is the union of all the positive permissions of each group that the principal belongs to. The group negative permission set is the union of all the negative permissions of each group that the principal belongs to. If there is a specific permission that occurs in both the positive permission set and the negative permission set, it is removed from both.

  The individual positive and negative permission sets are also determined. The positive permission set contains the permissions specified in the positive ACL entry (if any) for the principal. Similarly, the negative permission set contains the permissions specified in the negative ACL entry (if any) for the principal. The individual positive (or negative) permission set is considered to be null if there is not a positive (negative) ACL entry for the principal in this ACL.

  The set of permissions granted to the principal is then calculated using the simple rule that individual permissions always override the group permissions. That is, the principal's individual negative permission set (specific denial of permissions) overrides the group positive permission set, and the principal's individual positive permission set overrides the group negative permission set.

This method is from java.security.acl.Acl.

Example:

Principal pr = ...
 Enumeration e = acl.getPermissions(pr);

entries

public Enumeration entries()

Returns an enumeration of the entries in this ACL. Each element in the enumeration is of type AclEntry.

Specified by:

entries in interface Acl

Returns:

an enumeration of the entries in this ACL.

Usage:

This method is from java.security.acl.Acl.

Example:

Enumeration e = acl.entries();

checkPermission

public boolean checkPermission(Principal principal,
                               Permission permission)

Checks whether or not the specified principal has the specified permission. If it does, true is returned, otherwise false is returned.

Specified by:

checkPermission in interface Acl

Parameters:

principal - the principal, assumed to be a valid authenticated Principal

permission - the permission to be checked for

Returns:

true if the principal has the specified permission, false otherwise

Usage:

This method checks whether the passed permission is a member of the allowed permission set of the specified principal. The allowed permission set is determined by the same algorithm as is used by the getPermissions method.

This method is from java.security.acl.Acl.

See Also:

AgoAcl.getPermissions(Principal)