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    }