KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > outerj > daisy > repository > acl > AccessManager


1 /*
2  * Copyright 2004 Outerthought bvba and Schaubroeck nv
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.outerj.daisy.repository.acl;
17
18 import org.outerj.daisy.repository.Document;
19 import org.outerj.daisy.repository.RepositoryException;
20 import org.outerj.daisy.repository.VariantKey;
21
22 /**
23  * Provides functionality for maintaining the ACL (Access Control List) and
24  * checking permissions.
25  *
26  * <p>See Daisy's documentation for background information on the ACL system.
27  *
28  * <p>Basically, instead of associating an ACL with each document in the
29  * repository, there is one global ACL. Which ACL entries applies to which
30  * documents is based on conditions selecting documents based on eg
31  * their document type or collection membership. The structure of the
32  * ACL is thus as follows:
33  *
34  * <pre>
35  * object expression
36  * acl entry
37  * acl entry
38  * ...
39  * object expression
40  * acl entry
41  * acl entry
42  * ...
43  * ...
44  * </pre>
45  *
46  * <p>wherin the "object expression" is the expression selecting a set
47  * of documents. Each "acl entry" specifies for a certain subject
48  * (user, role or everyone) the allowed action (deny/grant) for a
49  * certain operation (read/write).
50  *
51  * <p>Two ACL's are managed: a staging ACL and a live ACL. Only
52  * the staging ACL can be directly modified, the live ACL can
53  * be updated by replacing it with the staging ACL.
54  *
55  * <p>About access to these functions: all users can read the ACL,
56  * only the Administrator can save (modify) it. All users can retrieve
57  * access information (ie using the getAclInfo* methods) for themselves,
58  * the Administrator can retrieve this information for whatever user.
59  */
60 public interface AccessManager {
61     /**
62      * Gets the currently active, live ACL. This ACL is not modifiable.
63      * To make modifications to the ACL, first modify the staging ACL, and then
64      * put the staging version live by callling {@link #copyLiveToStaging()}.
65      */
66     public Acl getLiveAcl() throws RepositoryException;
67
68     /**
69      * Gets the staging ACL.
70      */
71     public Acl getStagingAcl() throws RepositoryException;
72
73     /**
74      * Puts the staging ACL live.
75      */
76     public void copyStagingToLive() throws RepositoryException;
77
78     /**
79      * Reverts changes to the staging ACL.
80      */
81     public void copyLiveToStaging() throws RepositoryException;
82
83     /**
84      * Gets ACL info for the current user, by evaluating the (live) ACL rules
85      * on the given document object.
86      */
87     public AclResultInfo getAclInfo(Document document) throws RepositoryException;
88
89     /**
90      * Gets ACL info for the specified user acting in the specified role, for the specified
91      * document variant, by evaluating the live ACL.
92      */
93     public AclResultInfo getAclInfoOnLive(long userId, long[] roleIds, long documentId, long branchId, long languageId) throws RepositoryException;
94
95     /**
96      * Gets ACL info for the specified user acting in the specified role, for the specified
97      * document variant, by evaluating the live ACL.
98      */
99     public AclResultInfo getAclInfoOnLive(long userId, long[] roleIds, VariantKey key) throws RepositoryException;
100
101     /**
102      * Gets the ACL info for the branch "main" and language "default" of the document. This method
103      * is mainly provided for backwards compatibility.
104      */
105     public AclResultInfo getAclInfoOnLive(long userId, long[] roleIds, long documentId) throws RepositoryException;
106
107     /**
108      * Gets ACL info for the specified user acting in the specified role, for the specified
109      * document variant, by evaluating the staging ACL.
110      */
111     public AclResultInfo getAclInfoOnStaging(long userId, long[] roleIds, long documentId, long branchId, long languageId) throws RepositoryException;
112
113     /**
114      * Gets ACL info for the specified user acting in the specified role, for the specified
115      * document variant, by evaluating the staging ACL.
116      */
117     public AclResultInfo getAclInfoOnStaging(long userId, long[] roleIds, VariantKey key) throws RepositoryException;
118
119     /**
120      * Gets the ACL info for the branch "main" and language "default" of the document. This method
121      * is mainly provided for backwards compatibility.
122      */
123     public AclResultInfo getAclInfoOnStaging(long userId, long[] roleIds, long documentId) throws RepositoryException;
124
125     /**
126      * Checks the ACL using the supplied document object. The current content of the
127      * document is used during ACL evaluation, even if it includes unsaved changes.
128      * This allows to check the ACL result before saving the document.
129      *
130      * <p>This method does not work in the remote API implementation.
131      */
132     public AclResultInfo getAclInfoOnLive(long userId, long[] roleIds, Document document) throws RepositoryException;
133
134     /**
135      * Equivalent of {@link #getAclInfoOnLive(long, long[], org.outerj.daisy.repository.Document)}.
136      */
137     public AclResultInfo getAclInfoOnStaging(long userId, long[] roleIds, Document document) throws RepositoryException;
138
139     /**
140      * Filters the given list of document type ids to the ones for which the user
141      * is potentially able to create new documents. This does not guarantee that the
142      * user will be able to save a newly created document, as this could depend
143      * on the values of document fields or the collections to which the document belongs.
144      *
145      * <p>The collectionId parameter is optional (specify -1 to ignore) and allows
146      * to specify the collection to which the document will be added, which allows
147      * for a better filtered result.
148      *
149      */
150     public long[] filterDocumentTypes(long[] documentTypeIds, long collectionId) throws RepositoryException;
151
152     /**
153      * Filters the given list of document variants so that only document variants to which the
154      * current user has the given ACL permission remains.
155      * Non-existing documents/variants will also be excluded.
156      *
157      * <p>Especially in the remote API implementation, this is more efficient then
158      * retrieving this information for individual documents, since it only requires
159      * one backend HTTP call.
160      */
161     public VariantKey[] filterDocuments(VariantKey[] variantKeys, AclPermission permission) throws RepositoryException;
162
163     /**
164      * Filters documents based on 'read live' permission.
165      * See also {@link #filterDocuments(org.outerj.daisy.repository.VariantKey[], AclPermission)}.
166      */
167     public VariantKey[] filterDocuments(VariantKey[] variantKeys) throws RepositoryException;
168 }
169
Popular Tags