001 /*
002 * file StpAccessControlledResource.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.StpAccessControlledResource
008 *
009 * (C) Copyright IBM Corporation 2007, 2008. All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights: Use, duplication or
011 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
012 */
013
014 package com.ibm.rational.wvcm.stp;
015
016 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018 import java.util.List;
019
020 import javax.wvcm.WvcmException;
021 import javax.wvcm.PropertyNameList.PropertyName;
022
023 /**
024 * The interface implemented by resources that support access control lists
025 */
026 public interface StpAccessControlledResource extends StpResource
027 {
028 /**
029 * A Boolean indicating whether or not the session user is allowed to change
030 * the access rights on this resource.
031 */
032 PropertyName<Boolean> CAN_CHANGE_ACCESS_RIGHTS =
033 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "can-change-access-rights");
034
035 /**
036 * Returns the value of the
037 * {@link #CAN_CHANGE_ACCESS_RIGHTS CAN_CHANGE_ACCESS_RIGHTS} property as
038 * defined by this proxy.
039 *
040 * @return <b>true</b> if the user has CHANGE_PERMISSION access rights on
041 * this resource; <b>false</b> otherwise.
042 *
043 * @throws WvcmException if this proxy does not define a value for the
044 * {@link #CAN_CHANGE_ACCESS_RIGHTS CAN_CHANGE_ACCESS_RIGHTS}
045 * property.
046 */
047 boolean getCanChangeAccessRights() throws WvcmException;
048
049 /**
050 * A list of the access control entries applied directly to this resource.
051 */
052 PropertyName<List<StpAccessControlEntry>> APPLIED_ACCESS_CONTROL_ENTRIES =
053 new PropertyName<List<StpAccessControlEntry>>(PROPERTY_NAMESPACE,
054 "applied-access-control-entries");
055
056 /**
057 * Returns the value of the
058 * {@link #APPLIED_ACCESS_CONTROL_ENTRIES APPLIED_ACCESS_CONTROL_ENTRIES}
059 * property as defined by this proxy.
060 *
061 * @return A collection of StpAccessControlEntry instances. Will never be
062 * <b>null</b>. The controlled resource of each instance will refer
063 * to this resource, the type of each will be APPLIED, and the
064 * principal and access rights fields will vary based on the access
065 * rights applied to this resource.
066 *
067 * @throws WvcmException if this proxy does not define a value for the
068 * {@link #APPLIED_ACCESS_CONTROL_ENTRIES APPLIED_ACCESS_CONTROL_ENTRIES}
069 * property.
070 */
071 List<StpAccessControlEntry> getAppliedAccessControlEntries()
072 throws WvcmException;
073
074 /**
075 * A list of the access control entries in effect on this resource for all
076 * principals known to the user.
077 */
078 PropertyName<List<StpAccessControlEntry>> EFFECTIVE_ACCESS_CONTROL_ENTRIES =
079 new PropertyName<List<StpAccessControlEntry>>(PROPERTY_NAMESPACE,
080 "effective-access-control-entries");
081
082 /**
083 * Returns the value of the
084 * {@link #EFFECTIVE_ACCESS_CONTROL_ENTRIES EFFECTIVE_ACCESS_CONTROL_ENTRIES}
085 * property as defined by this proxy.
086 *
087 * @return A collection of StpAccessControlEntry instances. Will never be
088 * <b>null</b>. The controlled resource of each instance will refer
089 * to this resource, the type of each will be EFFECTIVE, and the
090 * principal and access rights fields will vary based on the
091 * relevant access control entries applied to this and related
092 * resources.
093 *
094 * @throws WvcmException if this proxy does not define a value for the
095 * {@link #EFFECTIVE_ACCESS_CONTROL_ENTRIES EFFECTIVE_ACCESS_CONTROL_ENTRIES}
096 * property.
097 */
098 List<StpAccessControlEntry> getEffectiveAccessControlEntries()
099 throws WvcmException;
100
101 /**
102 * The effective access rights granted the current user to this resource
103 */
104 PropertyName<StpAccessControlEntry> ACCESS_RIGHTS =
105 new PropertyName<StpAccessControlEntry>(PROPERTY_NAMESPACE,
106 "access-rights");
107
108 /**
109 * Returns the value of the {@link #ACCESS_RIGHTS ACCESS_RIGHTS} property as
110 * defined by this proxy.
111 *
112 * @return An StpAccessControlEntry instance representing the effective
113 * access rights granted the current user to this resource. Will
114 * never be <b>null</b>. The controlled resource will refer to this
115 * folder, the type will be EFFECTIVE, and the access rights field
116 * will specify the rights granted.
117 *
118 * @throws WvcmException if this proxy does not define a value for the
119 * {@link #ACCESS_RIGHTS ACCESS_RIGHTS} property.
120 */
121 StpAccessControlEntry getAccessRights() throws WvcmException;
122
123 /**
124 * A list of access control entries each representing an access right that
125 * could be applied to this resource. The principal and controlled resource
126 * fields of the returned objects are set nominally to the everyone group
127 * and this resource respectively.
128 */
129 PropertyName<List<StpAccessControlEntry>> POSSIBLE_ACCESS_RIGHTS =
130 new PropertyName<List<StpAccessControlEntry>>(PROPERTY_NAMESPACE,
131 "possible-access-rights");
132
133 /**
134 * Returns the value of the
135 * {@link #POSSIBLE_ACCESS_RIGHTS POSSIBLE_ACCESS_RIGHTS} property as
136 * defined by this proxy.
137 *
138 * @return A collection of StpAccessControlEntry instances. Will never be
139 * <b>null</b>. The controlled resource of each instance will refer
140 * to this resource, the type of each will be APPLIED, the principal
141 * of each will be a group including everyone, and the kind will
142 * vary to enumerate the possible access rights that may be applied
143 * to this folder. Any of these instances may be modified to form an
144 * instance for defining new applied access rights.
145 *
146 * @throws WvcmException if this proxy does not define a value for the
147 * {@link #POSSIBLE_ACCESS_RIGHTS POSSIBLE_ACCESS_RIGHTS}
148 * property.
149 */
150 List<StpAccessControlEntry> getPossibleAccessRights() throws WvcmException;
151
152 /**
153 * Defines a new value for the
154 * {@link #APPLIED_ACCESS_CONTROL_ENTRIES APPLIED_ACCESS_CONTROL_ENTRIES}
155 * property of this proxy.
156 * <p>
157 * Set new access control entries for the resource. The specified access
158 * control entries replace all existing entries for "visible" principals
159 * already set on the folder. This operation affects only the principals the
160 * user can see, so it may only affect a subset of the full set of access
161 * control entries on the resource.
162 *
163 * @param value A List of StpAccessControlEntry instances specifying the new
164 * value of the access control list. Only the principal and
165 * access rights of each access control entry are significant.
166 * The type, controlled resource and applied resource fields of
167 * these access control entries are ignored (the effective values
168 * being APPLIED and this resource, respectively).
169 */
170 void setAppliedAccessControlEntries(List<StpAccessControlEntry> value);
171
172 /**
173 * Defines modifications to be made to the
174 * {@link #APPLIED_ACCESS_CONTROL_ENTRIES APPLIED_ACCESS_CONTROL_ENTRIES}
175 * property of the resource referenced by this proxy.
176 *
177 * @param additions Access control entries to be added to those already set
178 * on the resource; does not add duplicates, and does not produce
179 * an error if there are duplicates. An entry on this list
180 * replaces any existing entry for the same principal. Does not
181 * add an access control entry for a principal the user is not a
182 * member of, unless the user also has the Security Administrator
183 * privilege.
184 * @param deletions All access control entries in this list that match any
185 * visible entries on the resource are removed from the respource;
186 * matching does not consider the access rights or controlled
187 * resource fields.
188 */
189 void setAppliedAccessControlEntries(List<StpAccessControlEntry> additions,
190 List<StpAccessControlEntry> deletions);
191 }