001: /*
002: * Copyright 2004 Outerthought bvba and Schaubroeck nv
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.outerj.daisy.repository.acl;
017:
018: import org.outerj.daisy.repository.Document;
019: import org.outerj.daisy.repository.RepositoryException;
020: import org.outerj.daisy.repository.VariantKey;
021:
022: /**
023: * Provides functionality for maintaining the ACL (Access Control List) and
024: * checking permissions.
025: *
026: * <p>The AccessManager can be retrieved via {@link org.outerj.daisy.repository.Repository#getAccessManager()}.
027: *
028: * <p>See Daisy's documentation for background information on the ACL system.
029: *
030: * <p>Basically, instead of associating an ACL with each document in the
031: * repository, there is one global ACL. Which ACL entries applies to which
032: * documents is based on conditions selecting documents based on eg
033: * their document type or collection membership. The structure of the
034: * ACL is thus as follows:
035: *
036: * <pre>
037: * object expression
038: * acl entry
039: * acl entry
040: * ...
041: * object expression
042: * acl entry
043: * acl entry
044: * ...
045: * ...
046: * </pre>
047: *
048: * <p>wherin the "object expression" is the expression selecting a set
049: * of documents. Each "acl entry" specifies for a certain subject
050: * (user, role or everyone) the allowed action (deny/grant) for a
051: * certain operation (read/write).
052: *
053: * <p>Two ACL's are managed: a staging ACL and a live ACL. Only
054: * the staging ACL can be directly modified, the live ACL can
055: * be updated by replacing it with the staging ACL.
056: *
057: * <p>About access to these functions: all users can read the ACL,
058: * only the Administrator can save (modify) it. All users can retrieve
059: * access information (ie using the getAclInfo* methods) for themselves,
060: * the Administrator can retrieve this information for whatever user.
061: */
062: public interface AccessManager {
063: /**
064: * Gets the currently active, live ACL. This ACL is not modifiable.
065: * To make modifications to the ACL, first modify the staging ACL, and then
066: * put the staging version live by callling {@link #copyLiveToStaging()}.
067: */
068: Acl getLiveAcl() throws RepositoryException;
069:
070: /**
071: * Gets the staging ACL.
072: */
073: Acl getStagingAcl() throws RepositoryException;
074:
075: /**
076: * Puts the staging ACL live.
077: */
078: void copyStagingToLive() throws RepositoryException;
079:
080: /**
081: * Reverts changes to the staging ACL.
082: */
083: void copyLiveToStaging() throws RepositoryException;
084:
085: /**
086: * Gets ACL info for the current user, by evaluating the (live) ACL rules
087: * on the given document object.
088: */
089: AclResultInfo getAclInfo(Document document)
090: throws RepositoryException;
091:
092: /**
093: * Gets ACL info for the specified user acting in the specified role, for the specified
094: * document variant, by evaluating the live ACL.
095: */
096: AclResultInfo getAclInfoOnLive(long userId, long[] roleIds,
097: String documentId, long branchId, long languageId)
098: throws RepositoryException;
099:
100: /**
101: * Gets ACL info for the specified user acting in the specified role, for the specified
102: * document variant, by evaluating the live ACL.
103: */
104: AclResultInfo getAclInfoOnLive(long userId, long[] roleIds,
105: VariantKey key) throws RepositoryException;
106:
107: /**
108: * Gets the ACL info for the branch "main" and language "default" of the document. This method
109: * is mainly provided for backwards compatibility.
110: */
111: AclResultInfo getAclInfoOnLive(long userId, long[] roleIds,
112: String documentId) throws RepositoryException;
113:
114: /**
115: * Gets ACL info for the specified user acting in the specified role, for the specified
116: * document variant, by evaluating the staging ACL.
117: */
118: AclResultInfo getAclInfoOnStaging(long userId, long[] roleIds,
119: String documentId, long branchId, long languageId)
120: throws RepositoryException;
121:
122: /**
123: * Gets ACL info for the specified user acting in the specified role, for the specified
124: * document variant, by evaluating the staging ACL.
125: */
126: AclResultInfo getAclInfoOnStaging(long userId, long[] roleIds,
127: VariantKey key) throws RepositoryException;
128:
129: /**
130: * Gets the ACL info for the branch "main" and language "default" of the document. This method
131: * is mainly provided for backwards compatibility.
132: */
133: AclResultInfo getAclInfoOnStaging(long userId, long[] roleIds,
134: String documentId) throws RepositoryException;
135:
136: /**
137: * Checks the ACL using the supplied document object. The current content of the
138: * document is used during ACL evaluation, even if it includes unsaved changes.
139: * This allows to check the ACL result before saving the document.
140: *
141: * <p>This method does not work in the remote API implementation.
142: */
143: AclResultInfo getAclInfoOnLive(long userId, long[] roleIds,
144: Document document) throws RepositoryException;
145:
146: /**
147: * Equivalent of {@link #getAclInfoOnLive(long, long[], org.outerj.daisy.repository.Document)}.
148: */
149: AclResultInfo getAclInfoOnStaging(long userId, long[] roleIds,
150: Document document) throws RepositoryException;
151:
152: /**
153: * Filters the given list of document type ids to the ones for which the user
154: * is potentially able to create new documents. This does not guarantee that the
155: * user will be able to save a newly created document, as this could depend
156: * on the values of document fields or the collections to which the document belongs.
157: *
158: * <p>The collectionId parameter is optional (specify -1 to ignore) and allows
159: * to specify the collection to which the document will be added, which allows
160: * for a better filtered result.
161: *
162: */
163: long[] filterDocumentTypes(long[] documentTypeIds, long collectionId)
164: throws RepositoryException;
165:
166: /**
167: * Filters the given list of document variants so that only document variants to which the
168: * current user has the given ACL permission remains.
169: * Non-existing documents/variants will also be excluded.
170: *
171: * <p>Especially in the remote API implementation, this is more efficient then
172: * retrieving this information for individual documents, since it only requires
173: * one backend HTTP call.
174: *
175: * @param nonLive set to true when read access to all versions of the document is required
176: * (rather than just the live version).
177: */
178: VariantKey[] filterDocuments(VariantKey[] variantKeys,
179: AclPermission permission, boolean nonLive)
180: throws RepositoryException;
181:
182: /**
183: * Filter documents assuming access to non-live versions is not required.
184: */
185: VariantKey[] filterDocuments(VariantKey[] variantKeys,
186: AclPermission permission) throws RepositoryException;
187:
188: /**
189: * Filters documents based on 'read' permission and without requiring access to all versions.
190: * See also {@link #filterDocuments(org.outerj.daisy.repository.VariantKey[], AclPermission)}.
191: */
192: VariantKey[] filterDocuments(VariantKey[] variantKeys)
193: throws RepositoryException;
194: }
|