javax.jcr.security
Interface AccessControlManager

public interface AccessControlManager

The AccessControlManager object is accessed via Session.getAccessControlManager(). It provides methods for:

• Access control discovery
• Assigning access control policies

Since:

JCR 2.0

Method Summary

AccessControlPolicyIterator	getApplicablePolicies(java.lang.String absPath) Returns the access control policies that are capable of being applied to the node at absPath.
AccessControlPolicy[]	getEffectivePolicies(java.lang.String absPath) Returns the AccessControlPolicy objects that currently are in effect at the node at absPath.
AccessControlPolicy[]	getPolicies(java.lang.String absPath) Returns the AccessControlPolicy objects that have been set to the node at absPath or an empty array if no policy has been set.
Privilege[]	getPrivileges(java.lang.String absPath) Returns the privileges the session has for absolute path absPath, which must be an existing node.
Privilege[]	getSupportedPrivileges(java.lang.String absPath) Returns the privileges supported for absolute path absPath, which must be an existing node.
boolean	hasPrivileges(java.lang.String absPath, Privilege[] privileges) Returns whether the session has the specified privileges for absolute path absPath, which must be an existing node.
Privilege	privilegeFromName(java.lang.String privilegeName) Returns the privilege with the specified privilegeName.
void	removePolicy(java.lang.String absPath, AccessControlPolicy policy) Removes the specified AccessControlPolicy from the node at absPath.
void	setPolicy(java.lang.String absPath, AccessControlPolicy policy) Binds the policy to the node at absPath.

Method Detail

getSupportedPrivileges

Privilege[] getSupportedPrivileges(java.lang.String absPath)
                                   throws PathNotFoundException,
                                          RepositoryException

Returns the privileges supported for absolute path absPath, which must be an existing node.

This method does not return the privileges held by the session. Instead, it returns the privileges that the repository supports.

Parameters:

absPath - an absolute path.

Returns:

an array of Privileges.

Throws:

PathNotFoundException - if no node at absPath exists or the session does not have sufficient access to retrieve a node at that location.

RepositoryException - if another error occurs.

privilegeFromName

Privilege privilegeFromName(java.lang.String privilegeName)
                            throws AccessControlException,
                                   RepositoryException

Returns the privilege with the specified privilegeName. Since the privilege name is a JCR name, it may be passed in either qualified or expanded form (see specification for details on JCR names).

Parameters:

privilegeName - the name of an existing privilege.

Returns:

the Privilege with the specified privilegeName.

Throws:

AccessControlException - if no privilege with the specified name exists.

RepositoryException - if another error occurs.

hasPrivileges

boolean hasPrivileges(java.lang.String absPath,
                      Privilege[] privileges)
                      throws PathNotFoundException,
                             RepositoryException

Returns whether the session has the specified privileges for absolute path absPath, which must be an existing node.

Testing an aggregate privilege is equivalent to testing each non aggregate privilege among the set returned by calling Privilege.getAggregatePrivileges() for that privilege.

The results reported by the this method reflect the net effect of the currently applied control mechanisms. It does not reflect unsaved access control policies or unsaved access control entries. Changes to access control status caused by these mechanisms only take effect on Session.save() and are only then reflected in the results of the privilege test methods.

Parameters:

absPath - an absolute path.

privileges - an array of Privileges.

Returns:

true if the session has the specified privileges; false otherwise.

Throws:

PathNotFoundException - if no node at absPath exists or the session does not have sufficent access to retrieve a node at that location.

RepositoryException - if another error occurs.

getPrivileges

Privilege[] getPrivileges(java.lang.String absPath)
                          throws PathNotFoundException,
                                 RepositoryException

Returns the privileges the session has for absolute path absPath, which must be an existing node.

The returned privileges are those for which hasPrivileges(java.lang.String, javax.jcr.security.Privilege[]) would return true.

The results reported by the this method reflect the net effect of the currently applied control mechanisms. It does not reflect unsaved access control policies or unsaved access control entries. Changes to access control status caused by these mechanisms only take effect on Session.save() and are only then reflected in the results of the privilege test methods.

Parameters:

absPath - an absolute path.

Returns:

an array of Privileges.

Throws:

PathNotFoundException - if no node at absPath exists or the session does not have sufficient access to retrieve a node at that location.

RepositoryException - if another error occurs.

getPolicies

AccessControlPolicy[] getPolicies(java.lang.String absPath)
                                  throws PathNotFoundException,
                                         AccessDeniedException,
                                         RepositoryException

Returns the AccessControlPolicy objects that have been set to the node at absPath or an empty array if no policy has been set. This method reflects the binding state, including transient policy modifications.

Use getEffectivePolicies(String) in order to determine the policy that effectively applies at absPath.

Parameters:

absPath - an absolute path.

Returns:

an array of AccessControlPolicy objects or an empty array if no policy has been set.

Throws:

PathNotFoundException - if no node at absPath exists or the session does not have sufficient access to retrieve a node at that location.

AccessDeniedException - if the session lacks READ_ACCESS_CONTROL privilege for the absPath node.

RepositoryException - if another error occurs.

getEffectivePolicies

AccessControlPolicy[] getEffectivePolicies(java.lang.String absPath)
                                           throws PathNotFoundException,
                                                  AccessDeniedException,
                                                  RepositoryException

Returns the AccessControlPolicy objects that currently are in effect at the node at absPath. This may be policies set through this API or some implementation specific (default) policies.

Parameters:

absPath - an absolute path.

Returns:

an array of AccessControlPolicy objects.

Throws:

PathNotFoundException - if no node at absPath exists or the session does not have sufficient access to retrieve a node at that location.

AccessDeniedException - if the session lacks READ_ACCESS_CONTROL privilege for the absPath node.

RepositoryException - if another error occurs.

getApplicablePolicies

AccessControlPolicyIterator getApplicablePolicies(java.lang.String absPath)
                                                  throws PathNotFoundException,
                                                         AccessDeniedException,
                                                         RepositoryException

Returns the access control policies that are capable of being applied to the node at absPath.

Parameters:

absPath - an absolute path.

Returns:

an AccessControlPolicyIterator over the applicable access control policies or an empty iterator if no policies are applicable.

Throws:

PathNotFoundException - if no node at absPath exists or the session does not have sufficient access to retrieve a node at that location.

AccessDeniedException - if the session lacks READ_ACCESS_CONTROL privilege for the absPath node.

RepositoryException - if another error occurs.

setPolicy

void setPolicy(java.lang.String absPath,
               AccessControlPolicy policy)
               throws PathNotFoundException,
                      AccessControlException,
                      AccessDeniedException,
                      LockException,
                      VersionException,
                      RepositoryException

Binds the policy to the node at absPath.

The behavior of the call acm.setPolicy(absPath, policy) differs depending on how the policy object was originally acquired.

If policy was acquired through acm.getApplicablePolicies(absPath) then that policy object is added to the node at absPath.

On the other hand, if policy was acquired through acm.getPolicies(absPath) then that policy object (usually after being altered) replaces its former version on the node at absPath.

This is session-write method and therefore the access control policy is only dispatched on save and will only take effect upon persist.

A VersionException will be thrown either immediately, on dispatch or on persists, if the node at absPath is read-only due to a checked-in node. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately, on dispatch or on persists, if a lock prevents the operation. Implementations may differ on when this validation is performed.

Parameters:

absPath - an absolute path.

policy - the AccessControlPolicy to be applied.

Throws:

PathNotFoundException - if no node at absPath exists or the session does not have sufficient access to retrieve a node at that location.

AccessControlException - if the policy is not applicable.

AccessDeniedException - if the session lacks MODIFY_ACCESS_CONTROL privilege for the absPath node.

LockException - if a lock applies at the node at absPath and this implementation performs this validation immediately.

VersionException - if the node at absPath is read-only due to a checked-in node and this implementation performs this validation immediately.

RepositoryException - if another error occurs.

removePolicy

void removePolicy(java.lang.String absPath,
                  AccessControlPolicy policy)
                  throws PathNotFoundException,
                         AccessControlException,
                         AccessDeniedException,
                         LockException,
                         VersionException,
                         RepositoryException

Removes the specified AccessControlPolicy from the node at absPath.

An AccessControlPolicy can only be removed if it was bound to the specified node through this API before. The effect of the removal only takes place upon Session.save(). Note, that an implementation default or any other effective AccessControlPolicy that has not been applied to the node before may never be removed using this method.

A PathNotFoundException is thrown if no node at absPath exists or the session does not have privilege to retrieve the node.

An AccessControlException is thrown if the policy to remove does not exist at the node at absPath.

An AccessDeniedException is thrown if the session lacks MODIFY_ACCESS_CONTROL privilege for the absPath node.

An LockException is thrown either immediately, on dispatch or on persists, if the node at absPath is locked. Implementations may differ on when this validation is performed.

An VersionException is thrown either immediately, on dispatch or on persists, if the node at absPath is read-only due to a checked-in node.Implementations may differ on when this validation is performed.

A RepositoryException is thrown if another error occurs.

Parameters:

absPath - an absolute path.

policy - the policy to be removed.

Throws:

PathNotFoundException - if no node at absPath exists or the session does not have sufficient access to retrieve a node at that location.

AccessControlException - if no policy exists.

AccessDeniedException - if the session lacks MODIFY_ACCESS_CONTROL privilege for the absPath node.

LockException - if a lock applies at the node at absPath and this implementation performs this validation immediately instead of waiting until save.

VersionException - if the node at absPath is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - if another error occurs.