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 * (C) Copyright IBM Corporation 2004, 2009.  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.cq;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import java.util.EnumSet;
019import java.util.List;
020
021import javax.wvcm.Activity;
022import javax.wvcm.ControllableResource;
023import javax.wvcm.Feedback;
024import javax.wvcm.Folder;
025import javax.wvcm.Resource;
026import javax.wvcm.ResourceList;
027import javax.wvcm.Version;
028import javax.wvcm.Workspace;
029import javax.wvcm.WvcmException;
030import javax.wvcm.Folder.RebindFlag;
031import javax.wvcm.PropertyNameList.PropertyName;
032import javax.wvcm.WvcmException.ReasonCode;
033
034import com.ibm.rational.wvcm.stp.StpAccessControlEntry;
035import com.ibm.rational.wvcm.stp.StpAccessControlledResource;
036import com.ibm.rational.wvcm.stp.StpAccessControlEntry.EntryType;
037import 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 */
050public 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    
251    /**
252     * A special property used to refresh a folder so that children added after
253     * this session started can be found. 
254     */
255    PropertyName<Boolean> NEEDS_REFRESH =
256        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "folder-needs-refresh");
257
258    /**
259     * Sets the NEEDS_REFRESH property. Doing this will cause the folder's 
260     * list of children to be reread. 
261     */
262    void setNeedsRefresh();
263
264}