com.starteam
Class AccessRightsManager

java.lang.Object
  com.starteam.AccessRightsManager

public final class AccessRightsManager
extends java.lang.Object

A generalized access rights cache for all types of StarTeam artifacts and Containers For optimized results, the cache should be pre-loaded with ACLs for each and every relevant artifact (or container)

Access rights information is fetched from the server as necessary, using bulk queries to minimize server traffic, and cached to improve performance of subsequent access tests. From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes and helps optimizing server calls. All access tests are in-memory operations This class is thread-safe and supports a multi reader single writer concurrency pattern

Nested Class Summary

static class

AccessRightsManager.AccessTestResults Represents the results of an access test.

Constructor Summary

AccessRightsManager(Server s)
Creates a new access rights manager for the given server.

Method Summary

AccessRightsManager.AccessTestResults	accessTest(Principal principal, PermissionCollection permissions, EffectiveACE[] acl) Determines whether or not the given principal is granted the given permissions to a securable object with the given access control list.
AccessRightsManager.AccessTestResults	accessTest(Principal principal, PermissionCollection permissions, ISecurable obj) Performs an access test against the given securable object.
AccessRightsManager.AccessTestResults	accessTest(Principal principal, PermissionCollection permissions, ISecurableContainer container, Type type) Performs an access test against the given securable container.
void	discard() Discards cached access rights information.
EffectiveACE[]	getEffectiveRights(ISecurable obj) Gets the effective access control list for the given securable object.
EffectiveACE[]	getEffectiveRights(ISecurableContainer container, Type type) Gets the effective access control list for objects of a given type in a given securable container.
ACE[]	getRights(ISecurable securable) Returns the Access Control List for this securable object.
ACE[]	getRights(ISecurableContainer securable, Type type) Returns the Access Control List for items of the specified type for this container.
boolean	isAccessGranted(Principal principal, PermissionCollection permissions, EffectiveACE[] acl) Determines whether or not the given principal is granted the given permissions to a securable object with the given access control list.
boolean	isAccessGranted(Principal principal, PermissionCollection permissions, ISecurable obj) Determines whether or not the given principal is granted the given permissions to the given securable object.
boolean	isAccessGranted(Principal principal, PermissionCollection permissions, ISecurableContainer container, Type type) Determines whether or not the given principal is granted the given permissions to the given securable container.
boolean	isCached(ISecurable object) returns true if ACLs for the specified securable have already been cached An access rights test against a securable that has not been cached will still succeed since the manager will issue server calls in the content of the test However, the resultant operation would be fairly expensive
boolean	isCached(ISecurableContainer object, Type type) returns true if ACLs for the specified securable container have already been cached An access rights test against a securable container that has not been cached will still succeed since the manager will issue server calls in the content of the test However, the resultant operation would be fairly expensive
void	populate(ISecurable object) Populates the access control list for this securable The cache is maintained in memory until cleared by a call to discard
void	populate(ISecurable[] securables) Populates the access control list for all the members of this securable collection using the fewest server commands possible The cache is maintained in memory until cleared by a call to discard
void	populate(ISecurableContainer[] securables, Type type) Populates the access control list for all the members of this securable container collection using the fewest server commands possible The cache is maintained in memory until cleared by a call to discard
void	populate(ISecurableContainer securable, Type type) Populates the access control list for this securable container
void	populateAll(ISecurable[] securables) Populates the access control lists for all the members of this collections, parent containers if any, and effective access control lists for these members and their parent containers
void	refresh() Refreshes cached access rights information to reflect recent changes to the server.
void	refresh(ISecurable object) refresh a single securable to reflect changes made to the object From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes thereby minimizing server calls.
void	refresh(ISecurable[] objects) refresh a set of securables to reflect changes made to the objects From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes thereby minimizing server calls.
void	refresh(ISecurableContainer[] objects, Type type) refresh a set of securable containers to reflect changes made to the objects From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes thereby optimizing server calls.
void	refresh(ISecurableContainer object, Type type) refresh a single securable container to reflect changes made to the object From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes thereby minimizing server calls.
void	remove(ISecurable object) Remove a securable from this access rights manager Typically, applications will remove securables that have been deleted
void	remove(ISecurable[] objects) Remove a set of securables from this access rights manager
void	remove(ISecurableContainer[] objects, Type type) Remove a set of Securable Containers from this access rights manager
void	remove(ISecurableContainer object, Type type) Remove a Securable Container from this access rights manager

Methods inherited from class java.lang.Object

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

Constructor Detail

AccessRightsManager

public AccessRightsManager(Server s)

Creates a new access rights manager for the given server.

Parameters:

s - The server whose access rights are to be managed.

Method Detail

refresh

public void refresh()

Refreshes cached access rights information to reflect recent changes to the server. From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes thereby minimizing server calls. Prior to 12.0, since access rights were not MPX enabled, a call to refresh issues server calls to update all the access rights in this manager However, most of these calls are issued in bulk

refresh

public void refresh(ISecurable object)

refresh a single securable to reflect changes made to the object From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes thereby minimizing server calls. Prior to 12.0 server, access Rights were not MPX enabled, so access rights changes to a given securable will not propagate to this manager unless explicitly refreshed

Parameters:

object - the securable to refresh in this manager

refresh

public void refresh(ISecurable[] objects)

refresh a set of securables to reflect changes made to the objects From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes thereby minimizing server calls. Prior to 12.0 server, access Rights were not MPX enabled, so access rights changes to securables will not propagate to this manager unless explicitly refreshed

Parameters:

objects - the securables to refresh in this manager

refresh

public void refresh(ISecurableContainer[] objects,
                    Type type)

refresh a set of securable containers to reflect changes made to the objects From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes thereby optimizing server calls. Prior to 12.0 server, access Rights were not MPX enabled, so access rights changes to securable containers will not propagate to this manager unless explicitly refreshed

Parameters:

objects - the securable containers to refresh in this manager

type - the owning type

refresh

public void refresh(ISecurableContainer object,
                    Type type)

refresh a single securable container to reflect changes made to the object From 12.0 release of the server onwards, MPX events are triggered by the server in case of access rights changes thereby minimizing server calls. Prior to 12.0 server, access Rights were not MPX enabled, so access rights changes to a given securable container will not propagate to this manager unless explicitly refreshed

Parameters:

object - the securable container to refresh in this manager

type - the owning type

discard

public void discard()

Discards cached access rights information. Access rights information will be fetched from the server as needed.

getEffectiveRights

public EffectiveACE[] getEffectiveRights(ISecurable obj)

Gets the effective access control list for the given securable object.

The effective access control list completely encompasses all information used by the server to perform an access test for the given object.

This might include an object-level ACL defined for the object itself, or a container-level ACL defined on a parent folder, or on the view or project, as well as implied ACEs resulting from group privileges, object ownership, and so on.

Parameters:

obj - A securable object.

Returns:

The effective access control list for the given securable object.

See Also:

ISecurable, EffectiveACE, AccessRightsManager.isAccessGranted(Principal, PermissionCollection, EffectiveACE[]), AccessRightsManager.accessTest(Principal, PermissionCollection, EffectiveACE[])

getEffectiveRights

public EffectiveACE[] getEffectiveRights(ISecurableContainer container,
                                         Type type)

Gets the effective access control list for objects of a given type in a given securable container.

The effective access control list completely encompasses all information used by the server to perform an access test for the given object.

This might include an object-level ACL defined for the object itself, or a container-level ACL defined on a parent folder, or on the view or project, as well as implied ACEs resulting from group privileges, object ownership, and so on.

Parameters:

container - A securable container.

type - The object type.

Returns:

The effective access control list for the given securable object.

See Also:

ISecurableContainer, EffectiveACE, AccessRightsManager.isAccessGranted(Principal, PermissionCollection, EffectiveACE[]), AccessRightsManager.accessTest(Principal, PermissionCollection, EffectiveACE[])

populateAll

public void populateAll(ISecurable[] securables)

Populates the access control lists for all the members of this collections, parent containers if any, and effective access control lists for these members and their parent containers

Parameters:

securables - a collection of securable objects

See Also:

AccessRightsManager.populate(ISecurable[]), AccessRightsManager.populate(ISecurableContainer[], Type), AccessRightsManager.getEffectiveRights(ISecurable), AccessRightsManager.getEffectiveRights(ISecurableContainer, Type)

isCached

public boolean isCached(ISecurable object)

returns true if ACLs for the specified securable have already been cached An access rights test against a securable that has not been cached will still succeed since the manager will issue server calls in the content of the test However, the resultant operation would be fairly expensive

Parameters:

object - the securable to test

Returns:

true if ACLS for this securable have been cached

isCached

public boolean isCached(ISecurableContainer object,
                        Type type)

returns true if ACLs for the specified securable container have already been cached An access rights test against a securable container that has not been cached will still succeed since the manager will issue server calls in the content of the test However, the resultant operation would be fairly expensive

Parameters:

object - the securable container to test

type - the owning type

Returns:

true if ACLS for this securable container have been cached

populate

public void populate(ISecurable object)

Populates the access control list for this securable The cache is maintained in memory until cleared by a call to discard

Parameters:

object - a single securable object.

See Also:

AccessRightsManager.getRights(ISecurable), AccessRightsManager.discard()

remove

public void remove(ISecurable object)

Remove a securable from this access rights manager Typically, applications will remove securables that have been deleted

Parameters:

object - the securable to remove from the manager

remove

public void remove(ISecurableContainer object,
                   Type type)

Remove a Securable Container from this access rights manager

Parameters:

object - the securable container to remove from the manager

type - the type associated with the container

remove

public void remove(ISecurableContainer[] objects,
                   Type type)

Remove a set of Securable Containers from this access rights manager

Parameters:

objects - the securable containers to remove from the manager

type - the type associated with the container

remove

public void remove(ISecurable[] objects)

Remove a set of securables from this access rights manager

Parameters:

objects - the securables to remove from the manager

populate

public void populate(ISecurable[] securables)

Populates the access control list for all the members of this securable collection using the fewest server commands possible The cache is maintained in memory until cleared by a call to discard

Parameters:

securables - a collection of securable objects.

See Also:

AccessRightsManager.getRights(ISecurable), AccessRightsManager.discard()

populate

public void populate(ISecurableContainer securable,
                     Type type)

Populates the access control list for this securable container

Parameters:

securable - a securable container

type - the owning type

See Also:

AccessRightsManager.getRights(ISecurableContainer, Type), AccessRightsManager.discard()

populate

public void populate(ISecurableContainer[] securables,
                     Type type)

Populates the access control list for all the members of this securable container collection using the fewest server commands possible The cache is maintained in memory until cleared by a call to discard

Parameters:

securables - a collection of securable containers.

type - the owning type

See Also:

AccessRightsManager.getRights(ISecurableContainer, Type), AccessRightsManager.discard()

getRights

public ACE[] getRights(ISecurable securable)

Returns the Access Control List for this securable object. The access control list is cached, and subsequent calls will be fetched from the cache

Parameters:

securable - A securable object.

Returns:

the access control list for this securable.

See Also:

AccessRightsManager.populate(ISecurable[])

getRights

public ACE[] getRights(ISecurableContainer securable,
                       Type type)

Returns the Access Control List for items of the specified type for this container. The access control list is cached, and subsequent calls will be fetched from the cache

Parameters:

securable - A securable container object

type - the type being controlled by the returned ACL

Returns:

the access control list for this container.

See Also:

AccessRightsManager.populate(ISecurableContainer[], Type), Type

isAccessGranted

public boolean isAccessGranted(Principal principal,
                               PermissionCollection permissions,
                               ISecurable obj)

Determines whether or not the given principal is granted the given permissions to the given securable object.

Determining the effective access control list for a securable object is a reasonably expensive operation. For applications that need to perform multiple access tests on the same securable object, consider using the form of isAccessGranted() that takes the effective ACL as a parameter.

Parameters:

principal - The principal for which the access test is performed.

permissions - The set of permission flags to be tested.

obj - The securable object against which the test is performed.

Returns:

true if the principal is granted all the requested permissions; false if at least one of the requested permissions is denied.

See Also:

ISecurable, AccessRightsManager.getEffectiveRights(ISecurable), AccessRightsManager.isAccessGranted(Principal,PermissionCollection,EffectiveACE[])

isAccessGranted

public boolean isAccessGranted(Principal principal,
                               PermissionCollection permissions,
                               ISecurableContainer container,
                               Type type)

Determines whether or not the given principal is granted the given permissions to the given securable container.

Determining the effective access control list for a securable container is a reasonably expensive operation. For applications that need to perform multiple access tests on the same securable object, consider using the form of isAccessGranted() that takes the effective ACL as a parameter.

Parameters:

principal - The principal for which the access test is performed.

permissions - The set of permission flags to be tested.

container - The securable container against which the test is performed.

type - The type of object for which the test is performed.

Returns:

true if the principal is granted all the requested permissions; false if at least one of the requested permissions is denied.

See Also:

ISecurable, AccessRightsManager.getEffectiveRights(ISecurableContainer,Type), AccessRightsManager.isAccessGranted(Principal,PermissionCollection,EffectiveACE[])

isAccessGranted

public boolean isAccessGranted(Principal principal,
                               PermissionCollection permissions,
                               EffectiveACE[] acl)

Determines whether or not the given principal is granted the given permissions to a securable object with the given access control list.

Parameters:

principal - The principal for which the access test is performed.

permissions - The set of permission flags to be tested.

acl - The access control list against which the test is performed.

Returns:

true if the principal is granted all the requested permissions; false if at least one of the requested permissions is denied.

See Also:

EffectiveACE, AccessRightsManager.getEffectiveRights(ISecurable)

accessTest

public AccessRightsManager.AccessTestResults accessTest(Principal principal,
                                                        PermissionCollection permissions,
                                                        ISecurable obj)

Performs an access test against the given securable object.

Determining the effective access control list for a securable object is a reasonably expensive operation. For applications that need to perform multiple access tests on the same securable object, consider using the form of accessTest() that takes the effective ACL as a parameter.

Parameters:

principal - The principalID of the principal for which the access test is performed.

permissions - The set of permission flags to be tested.

obj - The securable object against which the test is performed.

Returns:

A detailed explanation of the results of the access test.

See Also:

ISecurable, AccessRightsManager.AccessTestResults, AccessRightsManager.getEffectiveRights(ISecurable), AccessRightsManager.accessTest(Principal,PermissionCollection,EffectiveACE[])

accessTest

public AccessRightsManager.AccessTestResults accessTest(Principal principal,
                                                        PermissionCollection permissions,
                                                        ISecurableContainer container,
                                                        Type type)

Performs an access test against the given securable container.

Determining the effective access control list for a securable object is a reasonably expensive operation. For applications that need to perform multiple access tests on the same securable object, consider using the form of accessTest() that takes the effective ACL as a parameter.

Parameters:

principal - The principal for which the access test is performed.

permissions - The set of permission flags to be tested.

container - The securable container against which the test is performed.

type - The type of object for which the test is performed.

Returns:

A detailed explanation of the results of the access test.

See Also:

ISecurable, AccessRightsManager.AccessTestResults, AccessRightsManager.getEffectiveRights(ISecurableContainer,Type), AccessRightsManager.accessTest(Principal,PermissionCollection,EffectiveACE[])

accessTest

public AccessRightsManager.AccessTestResults accessTest(Principal principal,
                                                        PermissionCollection permissions,
                                                        EffectiveACE[] acl)

Determines whether or not the given principal is granted the given permissions to a securable object with the given access control list.

Parameters:

principal - The principal for which the access test is performed.

permissions - The set of permission flags to be tested.

acl - The access control list against which the test is performed.

Returns:

A detailed explanation of the results of the access test.

See Also:

EffectiveACE, AccessRightsManager.AccessTestResults, AccessRightsManager.getEffectiveRights(ISecurable)