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
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><parent-folder-path></i>/<i><folder-name></i>@<i><db-set></i>/<i><user-db></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
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 }