1 /* Copyright 2004, 2005, 2006 Acegi Technology Pty Limited
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * 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.springframework.security.acls;
16
17 import org.springframework.security.acls.objectidentity.ObjectIdentity;
18 import org.springframework.security.acls.sid.Sid;
19
20 import java.util.Map;
21
22
23 /**
24 * Provides retrieval of {@link Acl} instances.
25 *
26 * @author Ben Alex
27 * @version $Id: AclService.java 2866 2008-04-05 08:07:20Z benalex $
28 */
29 public interface AclService {
30 //~ Methods ========================================================================================================
31
32 /**
33 * Locates all object identities that use the specified parent. This is useful for administration tools.
34 *
35 * @param parentIdentity to locate children of
36 *
37 * @return the children (or <tt>null</tt> if none were found)
38 */
39 ObjectIdentity[] findChildren(ObjectIdentity parentIdentity);
40
41 /**
42 * Same as {@link #readAclsById(ObjectIdentity[])} except it returns only a single Acl.<p>This method
43 * should not be called as it does not leverage the underlaying implementation's potential ability to filter
44 * <tt>Acl</tt> entries based on a {@link Sid} parameter.</p>
45 *
46 * @param object to locate an {@link Acl} for
47 *
48 * @return the {@link Acl} for the requested {@link ObjectIdentity} (never <tt>null</tt>)
49 *
50 * @throws NotFoundException if an {@link Acl} was not found for the requested {@link ObjectIdentity}
51 */
52 Acl readAclById(ObjectIdentity object) throws NotFoundException;
53
54 /**
55 * Same as {@link #readAclsById(ObjectIdentity[], Sid[])} except it returns only a single Acl.
56 *
57 * @param object to locate an {@link Acl} for
58 * @param sids the security identities for which {@link Acl} information is required
59 * (may be <tt>null</tt> to denote all entries)
60 *
61 * @return the {@link Acl} for the requested {@link ObjectIdentity} (never <tt>null</tt>)
62 *
63 * @throws NotFoundException if an {@link Acl} was not found for the requested {@link ObjectIdentity}
64 */
65 Acl readAclById(ObjectIdentity object, Sid[] sids)
66 throws NotFoundException;
67
68 /**
69 * Obtains all the <tt>Acl</tt>s that apply for the passed <tt>Object</tt>s.<p>The returned map is
70 * keyed on the passed objects, with the values being the <tt>Acl</tt> instances. Any unknown objects will not
71 * have a map key.</p>
72 *
73 * @param objects the objects to find {@link Acl} information for
74 *
75 * @return a map with exactly one element for each {@link ObjectIdentity} passed as an argument (never <tt>null</tt>)
76 *
77 * @throws NotFoundException if an {@link Acl} was not found for each requested {@link ObjectIdentity}
78 */
79 Map readAclsById(ObjectIdentity[] objects) throws NotFoundException;
80
81 /**
82 * Obtains all the <tt>Acl</tt>s that apply for the passed <tt>Object</tt>s, but only for the
83 * security identifies passed.<p>Implementations <em>MAY</em> provide a subset of the ACLs via this method
84 * although this is NOT a requirement. This is intended to allow performance optimisations within implementations.
85 * Callers should therefore use this method in preference to the alternative overloaded version which does not
86 * have performance optimisation opportunities.</p>
87 * <p>The returned map is keyed on the passed objects, with the values being the <tt>Acl</tt>
88 * instances. Any unknown objects (or objects for which the interested <tt>Sid</tt>s do not have entries) will
89 * not have a map key.</p>
90 *
91 * @param objects the objects to find {@link Acl} information for
92 * @param sids the security identities for which {@link Acl} information is required
93 * (may be <tt>null</tt> to denote all entries)
94 *
95 * @return a map with exactly one element for each {@link ObjectIdentity} passed as an argument (never <tt>null</tt>)
96 *
97 * @throws NotFoundException if an {@link Acl} was not found for each requested {@link ObjectIdentity}
98 */
99 Map readAclsById(ObjectIdentity[] objects, Sid[] sids)
100 throws NotFoundException;
101 }