001    /*
002     * file CqQueryFolder.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.cq.CqQueryFolder
008     *
009     * © Copyright IBM Corporation 2004, 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.cq;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import java.util.EnumSet;
019    import java.util.List;
020    
021    import javax.wvcm.Activity;
022    import javax.wvcm.ControllableResource;
023    import javax.wvcm.Feedback;
024    import javax.wvcm.Folder;
025    import javax.wvcm.Resource;
026    import javax.wvcm.ResourceList;
027    import javax.wvcm.Version;
028    import javax.wvcm.Workspace;
029    import javax.wvcm.WvcmException;
030    import javax.wvcm.Folder.RebindFlag;
031    import javax.wvcm.PropertyNameList.PropertyName;
032    import javax.wvcm.WvcmException.ReasonCode;
033    
034    import com.ibm.rational.wvcm.stp.StpAccessControlEntry;
035    import com.ibm.rational.wvcm.stp.StpAccessControlledResource;
036    import com.ibm.rational.wvcm.stp.StpAccessControlEntry.EntryType;
037    import com.ibm.rational.wvcm.stpex.StpExBase;
038    
039    
040    /**
041     * A proxy for a query folder.
042     * <p>
043     * The user-friendly specification for the location of a query folder has the
044     * form
045     * 
046     * <pre>
047     *  <b>cq.query:</b><i>&lt;parent-folder-path&gt;</i>/<i>&lt;folder-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
048     * </pre>
049     */
050    public interface CqQueryFolder extends Folder, CqQueryFolderItem,
051                    StpAccessControlledResource
052    {
053        /**
054         * Creates a new folder at the location specified in this proxy.
055         * 
056         * @param feedback A Feedback object specifying the information desired from
057         *            the new folder after it has been created.
058         * @return A proxy for the newly-created folder populated with the requested
059         *         properties. The creation of the new folder will have been
060         *         delivered to the database before the method returns.
061         * @throws WvcmException If the folder cannot be created at the specified
062         *             location.
063         */
064        CqQueryFolder doCreateFolder(Feedback feedback) throws WvcmException;
065    
066        /**
067         * Creates a new folder at the location specified in this proxy.
068         * 
069         * @param feedback A Feedback object specifying the information desired from
070         *            the new folder after it has been created.
071         * @param deliveryOrder A specification of what resources are to be
072         *            delivered to the database after the folder has been created.
073         * @return A proxy for the newly-created folder populated with the requested
074         *         properties.
075         * @throws WvcmException If the folder cannot be created at the specified
076         *             location or if any of the resources to be delivered to the
077         *             database cannot be delivered.
078         */
079        CqQueryFolder doCreateFolder(Feedback feedback,
080                                     List<CqContextResource> deliveryOrder)
081            throws WvcmException;
082    
083        /**
084         * The queries, query folders and other items that are immediately contained
085         * within this folder.
086         */
087        PropertyName<ResourceList<CqQueryFolderItem>> QUERY_FOLDER_ITEMS =
088            new PropertyName<ResourceList<CqQueryFolderItem>>(PROPERTY_NAMESPACE,
089                                                              "query-folder-items");
090    
091        /**
092         * Returns the value of the {@link #QUERY_FOLDER_ITEMS QUERY_FOLDER_ITEMS}
093         * property as defined by this proxy.
094         * 
095         * @return A ResourceList containing a proxy for each immediate member of
096         *         this query folder.
097         * 
098         * @throws WvcmException if this proxy does not define a value for the
099         *             {@link #QUERY_FOLDER_ITEMS QUERY_FOLDER_ITEMS} property.
100         */
101        ResourceList<CqQueryFolderItem> getQueryFolderItems() throws WvcmException;
102    
103        /**
104         * A boolean indicating whether or not the effective access rights on this
105         * folder allow it to be read by the current user.
106         */
107        PropertyName<Boolean> IS_READABLE =
108            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-readable");
109    
110        /**
111         * Returns the value of the {@link #IS_READABLE IS_READABLE} property as
112         * defined by this proxy.
113         * 
114         * @return A boolean indicating whether or not the effective access rights
115         *         on this folder allow it to be read by the current user
116         * 
117         * @throws WvcmException if this proxy does not define a value for the
118         *             {@link #IS_READABLE IS_READABLE} property.
119         */
120        boolean getIsReadable() throws WvcmException;
121    
122        /**
123         * A boolean indicating whether or not the effective access rights on this
124         * folder allow it to be written by the current user
125         */
126        PropertyName<Boolean> IS_WRITABLE =
127            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-writable");
128    
129        /**
130         * Returns the value of the {@link #IS_WRITABLE IS_WRITABLE} property as
131         * defined by this proxy.
132         * 
133         * @return A boolean indicating whether or not the effective access rights
134         *         on this folder allow it to be read by the current user.
135         * 
136         * @throws WvcmException if this proxy does not define a value for the
137         *             {@link #IS_WRITABLE IS_WRITABLE} property.
138         */
139        boolean getIsWritable() throws WvcmException;
140    
141        /**
142         * A PropertyName class for requesting the applied or effective access
143         * rights for a specific group on this folder and, optionally, its nested
144         * folders
145         */
146        public class GroupAccessRightsName extends
147                        PropertyName<List<StpAccessControlEntry>>
148        {
149            /**
150             * Constructs a PropertyName for requesting the applied or effective
151             * access rights for a specific group on this folder and, optionally,
152             * its nested folders. The value of this property is a List of
153             * StpAccessControlEntry objects.
154             * 
155             * @param groupName The name of the group for which access rights are to
156             *            be returned.
157             * @param type The EntryType (APPLIED or EFFECTIVE) of the access rights
158             *            to be returned.
159             * @param nested <b>true</b> if the access rights of the specified type
160             *            and group are also to be returned for the folders nested
161             *            within this folder; <b>false</b> if just the access
162             *            rights on this folder are to be included.
163             */
164            public GroupAccessRightsName(String groupName,
165                                         EntryType type,
166                                         boolean nested)
167            {
168                super(StpExBase.GROUP_ACCESS_RIGHTS_NAMESPACE, (nested? "nested-"
169                                                                      : "")
170                    + type + "-" + groupName + "-access-rights");
171            }
172        }
173    
174        /**
175         * Retrieves from this proxy, the StpAccessControlEntry list returned as the
176         * value of a requested property named by a GroupAccessRightsName having the
177         * same parameters as this method.
178         * 
179         * @param groupName The name of the group for which access rights were
180         *            requested.
181         * @param type The EntryType of the access rights requested.
182         * @param nested <b>true</b> if the access rights of the specified type and
183         *            group were also to be returned for the folders nested within
184         *            this folder; <b>false</b> if just the access rights on this
185         *            folder were to be included.
186         * @return A list of StpAccessControlEntry objects, each representing an
187         *         AccessRight of the group as requested.
188         * @throws WvcmException If the implied GroupAccessRights property was not
189         *             requested or not otherwise available.
190         */
191        List<StpAccessControlEntry> getGroupAccessRights(String groupName,
192                                                         EntryType type,
193                                                         boolean nested)
194            throws WvcmException;
195    
196        /**
197         * A PropertyName class for requesting the applied or effective access
198         * rights for a specific user on this folder and, optionally, its nested
199         * folders
200         */
201        public class UserAccessRightsName extends
202                        PropertyName<List<StpAccessControlEntry>>
203        {
204            /**
205             * Constructs a PropertyName for requesting the applied or effective
206             * access rights for a specific user on this folder and, optionally, its
207             * nested folders. The value of this property is a List of
208             * StpAccessControlEntry objects.
209             * 
210             * @param userName The login_name of the user for which access rights
211             *            are to be returned.
212             * @param type The EntryType (APPLIED or EFFECTIVE) of the access rights
213             *            to be returned.
214             * @param nested <b>true</b> if the access rights of the specified type
215             *            and user are also to be returned for the folders nested
216             *            within this folder; <b>false</b> if just the access
217             *            rights on this folder are to be included.
218             */
219            public UserAccessRightsName(String userName,
220                                        EntryType type,
221                                        boolean nested)
222            {
223                super(StpExBase.USER_ACCESS_RIGHTS_NAMESPACE, (nested? "nested-"
224                                                                     : "")
225                    + type + "-" + userName + "-access-rights");
226            }
227        }
228    
229        /**
230         * Retrieves from this proxy, the StpAccessControlEntry list returned as the
231         * value of a requested property named by a UserAccessRightsName having the
232         * same parameters as this method.
233         * 
234         * @param userName The name of the user for which access rights were
235         *            requested.
236         * @param type The EntryType of the access rights requested.
237         * @param nested <b>true</b> if the access rights of the specified type and
238         *            user were also to be returned for the folders nested within
239         *            this folder; <b>false</b> if just the access rights on this
240         *            folder were to be included.
241         * @return A list of StpAccessControlEntry objects, each representing an
242         *         AccessRight of the type and user as requested.
243         * @throws WvcmException If the implied GroupAccessRights property was not
244         *             requested or not otherwise available.
245         */
246        List<StpAccessControlEntry> getUserAccessRights(String userName,
247                                                        EntryType type,
248                                                        boolean nested)
249            throws WvcmException;
250    }