01: /* Copyright 2004, 2005, 2006 Acegi Technology Pty Limited
02: *
03: * Licensed under the Apache License, Version 2.0 (the "License");
04: * you may not use this file except in compliance with the License.
05: * You may obtain a copy of the License at
06: *
07: * http://www.apache.org/licenses/LICENSE-2.0
08: *
09: * Unless required by applicable law or agreed to in writing, software
10: * distributed under the License is distributed on an "AS IS" BASIS,
11: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12: * See the License for the specific language governing permissions and
13: * limitations under the License.
14: */
15: package org.acegisecurity.acls;
16:
17: import org.acegisecurity.acls.objectidentity.ObjectIdentity;
18: import org.acegisecurity.acls.sid.Sid;
19:
20: import java.util.Map;
21:
22: /**
23: * Provides retrieval of {@link Acl} instances.
24: *
25: * @author Ben Alex
26: * @version $Id: AclService.java 1784 2007-02-24 21:00:24Z luke_t $
27: */
28: public interface AclService {
29: //~ Methods ========================================================================================================
30:
31: /**
32: * Locates all object identities that use the specified parent. This is useful for administration tools.
33: *
34: * @param parentIdentity to locate children of
35: *
36: * @return the children (or <code>null</code> if none were found)
37: */
38: ObjectIdentity[] findChildren(ObjectIdentity parentIdentity);
39:
40: /**
41: * Same as {@link #readAclsById(ObjectIdentity[])} except it returns only a single Acl.<p>This method
42: * should not be called as it does not leverage the underlaying implementation's potential ability to filter
43: * <code>Acl</code> entries based on a {@link Sid} parameter.</p>
44: *
45: * @param object DOCUMENT ME!
46: *
47: * @return DOCUMENT ME!
48: *
49: * @throws NotFoundException DOCUMENT ME!
50: */
51: Acl readAclById(ObjectIdentity object) throws NotFoundException;
52:
53: /**
54: * Same as {@link #readAclsById(ObjectIdentity[], Sid[])} except it returns only a single Acl.
55: *
56: * @param object DOCUMENT ME!
57: * @param sids DOCUMENT ME!
58: *
59: * @return DOCUMENT ME!
60: *
61: * @throws NotFoundException DOCUMENT ME!
62: */
63: Acl readAclById(ObjectIdentity object, Sid[] sids)
64: throws NotFoundException;
65:
66: /**
67: * Obtains all the <code>Acl</code>s that apply for the passed <code>Object</code>s.<p>The returned map is
68: * keyed on the passed objects, with the values being the <code>Acl</code> instances. Any unknown objects will not
69: * have a map key.</p>
70: *
71: * @param objects the objects to find ACL information for
72: *
73: * @return a map with zero or more elements (never <code>null</code>)
74: *
75: * @throws NotFoundException DOCUMENT ME!
76: */
77: Map readAclsById(ObjectIdentity[] objects) throws NotFoundException;
78:
79: /**
80: * Obtains all the <code>Acl</code>s that apply for the passed <code>Object</code>s, but only for the
81: * security identifies passed.<p>Implementations <em>MAY</em> provide a subset of the ACLs via this method
82: * although this is NOT a requirement. This is intended to allow performance optimisations within implementations.
83: * Callers should therefore use this method in preference to the alternative overloaded version which does not
84: * have performance optimisation opportunities.</p>
85: * <p>The returned map is keyed on the passed objects, with the values being the <code>Acl</code>
86: * instances. Any unknown objects (or objects for which the interested <code>Sid</code>s do not have entries) will
87: * not have a map key.</p>
88: *
89: * @param objects the objects to find ACL information for
90: * @param sids the security identities for which ACL information is required (may be <code>null</code> to denote
91: * all entries)
92: *
93: * @return a map with zero or more elements (never <code>null</code>)
94: *
95: * @throws NotFoundException DOCUMENT ME!
96: */
97: Map readAclsById(ObjectIdentity[] objects, Sid[] sids)
98: throws NotFoundException;
99: }
|