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
014package com.ibm.rational.wvcm.stp;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import java.util.List;
019
020import javax.wvcm.WvcmException;
021import javax.wvcm.PropertyNameList.PropertyName;
022
023/**
024 * The interface implemented by resources that support access control lists
025 */
026public 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}