001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr.security;
005:
006: import javax.jcr.PathNotFoundException;
007: import javax.jcr.RepositoryException;
008: import javax.jcr.AccessDeniedException;
009: import java.security.Principal;
010:
011: /**
012: * The <code>AccessControlManager</code> object is accessed via
013: * {@link javax.jcr.Session#getAccessControlManager()}. It provides methods for:
014: * <ul>
015: * <li>Access control discovery</li>
016: * <li>Assigning access control policies</li>
017: * <li>Assigning access control entries</li>
018: * </ul>
019: *
020: * @since JCR 2.0
021: */
022: public interface AccessControlManager {
023:
024: /**
025: * Returns the privileges supported for absolute path <code>absPath</code>,
026: * which must be an existing node.
027: * <p/>
028: * This method does not return the privileges held by the session. Instead,
029: * it returns the privileges that the repository supports.
030: *
031: * @param absPath an absolute path
032: * @return an array of <code>Privilege</code>s
033: * @throws PathNotFoundException if no node at <code>absPath</code> exists
034: * or the session does not have privilege to retrieve the node.
035: * @throws RepositoryException if another error occurs.
036: */
037: Privilege[] getSupportedPrivileges(String absPath)
038: throws PathNotFoundException, RepositoryException;
039:
040: /**
041: * Returns whether the session has the specified privileges for absolute
042: * path <code>absPath</code>, which must be an existing node.
043: * <p/>
044: * Testing an aggregate privilege is equivalent to testing each nonaggregate
045: * privilege among the set returned by calling
046: * <code>Privilege.getAggregatePrivileges()</code> for that privilege.
047: * <p/>
048: * The results reported by the this method reflect the net
049: * <i>effect</i> of the currently applied control mechanisms. It does not reflect
050: * unsaved access control policies or unsaved access control entries (see XX).
051: * Changes to access control status caused by these mechanisms only take effect
052: * on <code>Session.save()</code> and are only then reflected in the results of
053: * the privilege test methods.
054: *
055: * @param absPath an absolute path
056: * @param privileges an array of <code>Privilege</code>s
057: * @return <code>true</code> if the session has the specified privileges;
058: * <code>false</code> otherwise.
059: * @throws PathNotFoundException if no node at <code>absPath</code> exists
060: * or the session does not have privilege to retrieve the node.
061: * @throws RepositoryException if another error occurs.
062: */
063: boolean hasPrivileges(String absPath, Privilege[] privileges)
064: throws PathNotFoundException, RepositoryException;
065:
066: /**
067: * Returns the privileges the session has for absolute path absPath, which
068: * must be an existing node.
069: * <p/>
070: * The returned privileges are those for which {@link #hasPrivileges} would
071: * return <code>true</code>.
072: * <p/>
073: * The results reported by the this method reflect the net
074: * <i>effect</i> of the currently applied control mechanisms. It does not reflect
075: * unsaved access control policies or unsaved access control entries (see XX).
076: * Changes to access control status caused by these mechanisms only take effect
077: * on <code>Session.save()</code> and are only then reflected in the results of
078: * the privilege test methods.
079: *
080: * @param absPath an absolute path
081: * @return an array of <code>Privilege</code>s
082: * @throws PathNotFoundException if no node at <code>absPath</code> exists
083: * or the session does not have privilege to retrieve the node.
084: * @throws RepositoryException if another error occurs.
085: */
086: Privilege[] getPrivileges(String absPath)
087: throws PathNotFoundException, RepositoryException;
088:
089: /**
090: * Returns the access control policies that are capable of being applied to
091: * the node at <code>absPath</code>.
092: *
093: * @param absPath an absolute path
094: * @return an <code>AccessControlPolicyIterator</code> over the applicable
095: * access control policies
096: * @throws PathNotFoundException if no node at <code>absPath</code> exists
097: * or the session does not have privilege to retrieve the node.
098: * @throws AccessDeniedException if the session lacks
099: * <code>GET_ACCESS_CONTROL</code> privilege for the
100: * <code>absPath</code> node.
101: * @throws RepositoryException if another error occurs.
102: */
103: AccessControlPolicyIterator getSupportedPolicies(String absPath)
104: throws PathNotFoundException, AccessDeniedException,
105: RepositoryException;
106:
107: /**
108: * Binds the <code>policy</code> to the node at <code>absPath</code>.
109: * <p/>
110: * Only one policy may be bound at a time. If more than one policy per node is
111: * required, the implementation should provide an appropriate aggregate policy
112: * among those returned by <code>getSupportedPolicies(absPath)</code>
113: * The access control policy does not take effect until a <code>save</code> is performed.
114: * <p/>
115: * If the node has existing access control entries that were bound to it though the JCR API
116: * these entries may be deleted upon execution of the <code>addPolicy</code> call.
117: * Any implementation-specific (non-JCR) access control settings may be changed in response to
118: * a successful call to <code>addPolicy</code>.
119: *
120: * @param absPath an absolute path
121: * @param policy the <code>AccessControlPolicy</code> to be applied
122: * @throws PathNotFoundException if no node at <code>absPath</code> exists
123: * or the session does not have privilege to retrieve the node.
124: * @throws PolicyNotFoundException if no policy exists.
125: * @throws AccessDeniedException if the session lacks
126: * <code>GET_ACCESS_CONTROL</code> privilege for the
127: * <code>absPath</code> node.
128: * @throws RepositoryException if another error occurs.
129: */
130: void addPolicy(String absPath, AccessControlPolicy policy)
131: throws PathNotFoundException, PolicyNotFoundException,
132: AccessDeniedException, RepositoryException;
133:
134: /**
135: * Returns the <code>AccessControlPolicy</code> that currently applies to
136: * the node at <code>absPath</code>.
137: *
138: * @param absPath an absolute path
139: * @return an <code>AccessControlPolicy</code> object
140: * @throws PathNotFoundException if no node at <code>absPath</code> exists
141: * or the session does not have privilege to retrieve the node.
142: * @throws AccessDeniedException if the session lacks
143: * <code>GET_ACCESS_CONTROL</code> privilege for the
144: * <code>absPath</code> node.
145: * @throws RepositoryException if another error occurs.
146: */
147: AccessControlPolicy getPolicy(String absPath)
148: throws PathNotFoundException, AccessDeniedException,
149: RepositoryException;
150:
151: /**
152: * Performs a best-effort search for the policy in effect on the node at absPath.
153: * Since finding the effective policy may be impractical or impossible in certain
154: * implementations, a return value of <code>null</code> may mean either that a policy exists
155: * but the implementation cannot find it, or that there is no effective policy on the node.
156: *
157: * @param absPath an absolute path
158: * @return an <code>AccessControlPolicy</code> object
159: * @throws PathNotFoundException if no node at <code>absPath</code> exists
160: * or the session does not have privilege to retrieve the node.
161: * @throws AccessDeniedException if the session lacks
162: * <code>GET_ACCESS_CONTROL</code> privilege for the
163: * <code>absPath</code> node.
164: * @throws RepositoryException if another error occurs.
165: */
166: AccessControlPolicy getEffectivePolicy(String absPath)
167: throws PathNotFoundException, AccessDeniedException,
168: RepositoryException;
169:
170: /**
171: * Removes the currently applied <code>AccessControlPolicy</code> from the
172: * node at <code>absPath</code> and returns it.
173: * <p/>
174: * An <code>AccessControlPolicy</code> can only be removed if it was previously
175: * bound to the specified node through this API before. The effect of the removal
176: * only takes place upon <code>Session.save()</code>.
177: *
178: * @param absPath an absolute path
179: * @return the removed <code>AccessControlPolicy</code>
180: * @throws PathNotFoundException if no node at <code>absPath</code> exists
181: * or the session does not have privilege to retrieve the node.
182: * @throws PolicyNotFoundException if no policy exists.
183: * @throws AccessDeniedException if the session lacks
184: * <code>MODIFY_ACCESS_CONTROL</code> privilege for the
185: * <code>absPath</code> node.
186: * @throws RepositoryException if another error occurs.
187: */
188: AccessControlPolicy removePolicy(String absPath)
189: throws PathNotFoundException, PolicyNotFoundException,
190: AccessDeniedException, RepositoryException;
191:
192: /**
193: * Returns all access control entries assigned to the node at <code>absPath</code>.
194: * <p/>
195: * This method is only guaranteed to return an <code>AccessControlEntry</code>
196: * if that <code>AccessControlEntry</code> has been assigned <i>through this API</i>.
197: *
198: * @param absPath an absolute path
199: * @return all access control entries assigned to the specified node
200: * @throws PathNotFoundException if no node at <code>absPath</code> exists
201: * or the session does not have privilege to retrieve the node.
202: * @throws AccessDeniedException if the session lacks
203: * <code>jcr:getAccessControlPolicy</code> privilege for the
204: * <code>absPath</code> node.
205: * @throws RepositoryException if another error occurs.
206: */
207: AccessControlEntry[] getAccessControlEntries(String absPath)
208: throws PathNotFoundException, AccessDeniedException,
209: RepositoryException;
210:
211: /**
212: * Adds the access control entry consisting of the specified
213: * <code>principal</code> and the specified <code>privileges</code> to the
214: * node at <code>absPath</code>.
215: * <p/>
216: * This method returns the <code>AccessControlEntry</code> object constructed from the
217: * specified <code>principal</code> and contains at least the given <code>privileges</code>.
218: * An implementation may return a resulting ACE that combines the given <code>privileges</code>
219: * with those added by a previous call to <code>addAccessControlEntry</code> for the same
220: * <code>Principal</code>. However, a call to <code>addAccessControlEntry</code> for a given
221: * <code>Principal</code> can never remove a <code>Privilege</code> added by a previous call
222: * to <code>addAccessControlEntry</code>.
223: * <p/>
224: * The access control entry does not take effect until a <code>save</code>
225: * is performed.
226: * <p/>
227: * This method is guaranteed to affect only the privileges of the specified
228: * <code>principal</code>.
229: * <p/>
230: * This method <i>may</i> affect the privileges granted to that principal with
231: * respect to nodes other than that specified. However, if it does, it is
232: * guaranteed to only affect the privileges of those other nodes in the
233: * same way as it affects the privileges of the specified node.
234: *
235: * @param absPath an absolute path
236: * @param principal a <code>Principal</code>
237: * @param privileges an array of <code>Privilege</code>s
238: * @return the <code>AccessControlEntry</code> object constructed from the
239: * specified <code>principal</code> and <code>privileges</code>.
240: * @throws PathNotFoundException if no node at <code>absPath</code> exists
241: * or the session does not have privilege to retrieve the node.
242: * @throws PrincipalNotFoundException if the specified principal does not exist.
243: * @throws AccessDeniedException if the session lacks
244: * <code>jcr:setAccessControlPolicy</code> privilege for the
245: * <code>absPath</code> node.
246: * @throws RepositoryException if another error occurs.
247: */
248: AccessControlEntry addAccessControlEntry(String absPath,
249: Principal principal, Privilege[] privileges)
250: throws PathNotFoundException, PrincipalNotFoundException,
251: AccessDeniedException, RepositoryException;
252:
253: /**
254: * Removes the specified <code>AccessControlEntry</code> from the node at
255: * <code>absPath</code>.
256: * <p/>
257: * This method is guaranteed to affect only the privileges of the principal
258: * defined within the passed <code>AccessControlEntry</code>.
259: * <p/>
260: * This method <i>may</i> affect the privileges granted to that principal
261: * with respect to nodes other than that specified. However, if it does,
262: * it is guaranteed to only affect the privileges of those other nodes in
263: * the same way as it affects the privileges of the specified node.
264: * <p/>
265: * Only exactly those entries explicitly added though this API can be
266: * removed through this API. The effect of the removal only takes place
267: * upon <code>Session.save()</code>.
268: *
269: * @param absPath an absolute path
270: * @param ace the access control entry to be removed
271: * @throws PathNotFoundException if no node at <code>absPath</code> exists
272: * or the session does not have privilege to retrieve the node.
273: * @throws AccessControlEntryNotFoundException
274: * if the specified entry is not
275: * present on the specified node.
276: * @throws AccessDeniedException if the session lacks
277: * <code>jcr:setAccessControlPolicy</code> privilege for the
278: * <code>absPath</code> node.
279: * @throws RepositoryException if another error occurs.
280: */
281: void removeAccessControlEntry(String absPath, AccessControlEntry ace)
282: throws PathNotFoundException,
283: AccessControlEntryNotFoundException, AccessDeniedException,
284: RepositoryException;
285: }
|