001 /*
002 * file CqQueryFolderItem.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem
008 *
009 * (C) Copyright IBM Corporation 2006, 2012. 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.List;
019
020 import javax.wvcm.Feedback;
021 import javax.wvcm.ResourceList;
022 import javax.wvcm.WvcmException;
023 import javax.wvcm.PropertyNameList.PropertyName;
024 import javax.wvcm.PropertyRequestItem.PropertyRequest;
025
026 import com.ibm.rational.wvcm.stp.StpLocation;
027 import com.ibm.rational.wvcm.stp.StpResource;
028
029 /**
030 * A specification for an item in a query folder, which may be a query, chart,
031 * report, report format, or a nested query folder.
032 * <p>
033 * The user-friendly specification for the location of a query folder item has
034 * the form
035 *
036 * <pre>
037 * <b>cq.query:</b><i><parent-folder-path></i>/<i><item-name></i>@<i><db-set></i>/<i><user-db></i>
038 * </pre>
039 *
040 */
041 public interface CqQueryFolderItem extends CqContextResource
042 {
043 /** The query folder that contains this folder */
044 PropertyName<CqQueryFolder> QUERY_FOLDER =
045 new PropertyName<CqQueryFolder>(PROPERTY_NAMESPACE, "query-folder");
046
047 /**
048 * Returns the value of the {@link #QUERY_FOLDER QUERY_FOLDER} property as
049 * defined by this proxy.
050 *
051 * @return A CqQueryFolder proxy for the query folder that contains this
052 * folder. Will be <b>null</b> if there is no containing query
053 * folder.
054 *
055 * @throws WvcmException if this proxy does not define a value for the
056 * {@link #QUERY_FOLDER QUERY_FOLDER} property.
057 */
058 public CqQueryFolder getQueryFolder() throws WvcmException;
059
060 /**
061 * The site-extended name for this folder item.
062 */
063 PropertyName<StpLocation> SITE_EXTENDED_NAME =
064 new PropertyName<StpLocation>(PROPERTY_NAMESPACE, "site-extended-name");
065
066 /**
067 * Returns the value of the {@link #SITE_EXTENDED_NAME SITE_EXTENDED_NAME}
068 * property as defined by this proxy.
069 *
070 * @return An StpLocation containing the site-extended name for this
071 * resource.
072 *
073 * @throws WvcmException if this proxy does not define a value for the
074 * {@link #SITE_EXTENDED_NAME SITE_EXTENDED_NAME} property.
075 */
076 public StpLocation getSiteExtendedName() throws WvcmException;
077
078 /**
079 * An indication whether or not a site extended name is required to access
080 * this resource unambiguously.
081 */
082 PropertyName<Boolean> IS_SITE_EXTENDED_NAME_REQUIRED =
083 new PropertyName<Boolean>(PROPERTY_NAMESPACE,
084 "is-site-extended-name-required");
085
086 /**
087 * Returns the value of the
088 * {@link #IS_SITE_EXTENDED_NAME_REQUIRED IS_SITE_EXTENDED_NAME_REQUIRED}
089 * property as defined by this proxy.
090 *
091 * @return <b>true</b> if the name of this resource requires a site
092 * extension field to be unambiguous; <b>false</b> if no site
093 * extension field is needed
094 *
095 * @throws WvcmException if this proxy does not define a value for the
096 * {@link #IS_SITE_EXTENDED_NAME_REQUIRED IS_SITE_EXTENDED_NAME_REQUIRED}
097 * property.
098 */
099 public boolean getIsSiteExtendedNameRequired() throws WvcmException;
100
101 /**
102 * A list of all the items in the query folder hierarchy whose name differs
103 * from the name of this resource only in its site extensions.
104 */
105 PropertyName<ResourceList<CqQueryFolderItem>> SITE_EXTENDED_NAMES =
106 new PropertyName<ResourceList<CqQueryFolderItem>>(PROPERTY_NAMESPACE,
107 "site-extended-names");
108
109 /**
110 * Returns the value of the {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES}
111 * property as defined by this proxy.
112 *
113 * @return A ResourceList containing a proxy for each CqQueryFolderItem
114 * resource whose name differs from the name of this resource only in the
115 * site extensions used.
116 *
117 * @throws WvcmException if this proxy does not define a value for the
118 * {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES} property.
119 */
120 public ResourceList<CqQueryFolderItem> getSiteExtendedNames()
121 throws WvcmException;
122
123 /**
124 * The replica that masters this resource. A resource can be modified only
125 * in the replica that masters (has mastership of) it.
126 */
127 PropertyName<CqReplica> CQ_MASTER_REPLICA =
128 new PropertyName<CqReplica>(PROPERTY_NAMESPACE, "cq-master-replica");
129
130 /**
131 * Returns the value of the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA}
132 * property as defined by this proxy.
133 *
134 * @return A CqReplica proxy for the replica that has mastership of this
135 * resource.
136 *
137 * @throws WvcmException if this proxy does not define a value for the
138 * {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} property.
139 */
140 CqReplica getCqMasterReplica() throws WvcmException;
141
142 /**
143 * Defines a new value for the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA}
144 * property of this proxy.
145 *
146 * @param newMasterReplica A CqReplica proxy identifying the replica that
147 * should assume mastership of this resource.
148 */
149 void setCqMasterReplica(CqReplica newMasterReplica);
150
151 /**
152 * Indicates whether or not this query folder item can be updated and/or
153 * deleted by the user.
154 */
155 PropertyName<Boolean> CAN_UPDATE_OR_DELETE =
156 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "can-update-or-delete");
157
158 /**
159 * Returns the value of the
160 * {@link #CAN_UPDATE_OR_DELETE CAN_UPDATE_OR_DELETE} property as defined by
161 * this proxy.
162 *
163 * @return <b>true</b> if this query folder item can be updated or deleted
164 * by the current user.
165 *
166 * @throws WvcmException if this proxy does not define a value for the
167 * {@link #CAN_UPDATE_OR_DELETE CAN_UPDATE_OF_DELETE} property.
168 */
169 boolean getCanUpdateOrDelete() throws WvcmException;
170
171 /**
172 * Makes an editable copy of the query folder item named by this proxy at
173 * the location specified in the argument list. Any dirty properties in this
174 * proxy are written to the new copy after it is created, <i>not</i> to the
175 * resource referenced by this proxy. This item is not modified by this
176 * operation.
177 *
178 * @param destination The location where a new copy of this query folder
179 * item is to be created. The parent folder of this location must
180 * already exist in the query folder hierarchy of the database.
181 * @param overwrite Specifies how a query folder item already at the target
182 * location is to be handled.
183 * @param feedback A request for the properties to be defined by the proxy
184 * that is returned by this method.
185 * @param deliveryOrder If {@link CqProvider#HOLD}, the copied resource is
186 * left in a writable state in the change context--the copied
187 * resource in the change context must be delivered before it
188 * becomes visible to other providers. If not
189 * {@link CqProvider#HOLD}, the modified and moribund resources
190 * specified by this parameter will be delivered to or deleted
191 * from the database in the order indicated. To deliver all
192 * modified and moribund resources in an arbitrary order, use
193 * {@link CqProvider#DELIVER_ALL}. To deliver just this copied
194 * resource, use {@link CqProvider#DELIVER}. Must not be <b>null</b>.
195 *
196 * @return A CqQueryFolderItem proxy for the new copy of this item. Unless
197 * the deliver option was specified, the copied query item will be
198 * editable.
199 *
200 * @throws WvcmException if the server is unable to create the copy at the
201 * specified location.
202 */
203 CqQueryFolderItem doCopy(StpLocation destination,
204 OverwriteMode overwrite,
205 Feedback feedback,
206 List<CqContextResource> deliveryOrder)
207 throws WvcmException;
208
209 /**
210 * Makes an editable copy of the query folder item named by this proxy at
211 * the location specified in the argument list. Any dirty properties are
212 * written to the new copy after it is created, <i>not</i> to the resource
213 * addressed by this proxy.
214 * <p>
215 * This variant of doCopy is provided because in the presence of stable or
216 * fast location formats the client cannot always guarantee that
217 * <code>parentFolder.child(childName)</code> will be a valid location
218 * specification.
219 *
220 * @param parentFolder The folder to which this query folder item is to be
221 * copied. The proxy must name an existing query folder of this
222 * user database.
223 * @param childName The name the copy of this resource is to have in the
224 * destination folder.
225 * @param overwrite Specifies how a query folder item already at the target
226 * location is to be handled.
227 * @param feedback The query properties to be defined by the proxy that is
228 * returned by this method.
229 * @param deliveryOrder Same as the version of
230 * {@link #doCopy(StpLocation, com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem.OverwriteMode, Feedback, List) doCopy taking an StpLocation}.
231 *
232 * @return A CqQueryFolderItem proxy for the new copy of this query folder
233 * item. Unless the deliver option was specified, this query
234 * definition will be editable.
235 *
236 * @throws WvcmException if the server is unable to create the copy at the
237 * specified location.
238 */
239 CqQueryFolderItem doCopy(CqQueryFolder parentFolder,
240 String childName,
241 OverwriteMode overwrite,
242 Feedback feedback,
243 List<CqContextResource> deliveryOrder)
244 throws WvcmException;
245
246 /**
247 * An enumeration of the values for specifying what doCopy and/or doMove
248 * should do when a resource already exists at the targeted destination.
249 */
250 public enum OverwriteMode
251 {
252 /**
253 * If a resource exists at the target location, the operation will
254 * fail; the resource at the target location will not be overwritten.
255 */
256 FORBID,
257
258 /**
259 * If a resource exists at the target location, that resource is to be
260 * deleted and replaced by the source resource. Specifically, if the
261 * target is a folder, that folder and all of its members are deleted
262 * and replaced by the source.
263 */
264 REPLACE,
265
266 /**
267 * If the source resource is a folder and a folder exists at the target
268 * location, that folder is not deleted, but the contents of the source
269 * folder are merged with the contents of the target folder and this
270 * rule is applied recursively for each member of the source folder. If
271 * either the source resource or the target resource is not a folder,
272 * the target resource is deleted and replaced by the source--i.e., in
273 * this case, the operation behaves the same as in the REPLACE
274 * OverwriteMode.
275 */
276 MERGE
277 }
278
279 /**
280 * Makes an editable copy of the query folder item named by this proxy at
281 * the location specified in the argument list and deletes the query folder
282 * item at the current proxy location. Any dirty properties are written to
283 * the new copy after it is created.
284 *
285 * @param destination The location to which this query folder item is to be
286 * moved. The location must be in the QUERY namespace of this
287 * user database.
288 * @param overwrite Specifies how a query folder item already at the target
289 * location is to be handled.
290 * @param feedback The properties to be defined by the proxy that is
291 * returned by this method.
292 * @param deliveryOrder Same as the deliveryOrder parameter of
293 * {@link #doCopy(StpLocation, com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem.OverwriteMode, Feedback, List) doCopy}.
294 * But note that use of {@link CqProvider#DELIVER} both delivers
295 * the copy and deletes the original query folder item.
296 *
297 * @return A proxy for the new copy of this resource. Unless the deliver
298 * option was specified, the resource at the proxy location will be
299 * editable.
300 *
301 * @throws WvcmException if the server is unable to create the copy at the
302 * specified location.
303 */
304 CqQueryFolderItem doMove(StpLocation destination,
305 OverwriteMode overwrite,
306 Feedback feedback,
307 List<CqContextResource> deliveryOrder)
308 throws WvcmException;
309
310 /**
311 * Directly rename the query item without change any other property of it.
312 * <p>
313 *
314 * @param parentFolder The folder to which this query folder item is belonged
315 *
316 * @param newName The name this resource will be renamed to
317 *
318 * @param feedback The properties to be defined by the proxy that is
319 * returned by this method.
320 * @param deliveryOrder Same as the deliveryOrder parameter of
321 * {@link #doCopy(StpLocation, com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem.OverwriteMode, Feedback, List) doCopy}.
322 *
323 * @return A proxy for the newly renamed resource. Unless the deliver
324 * option was specified, this resource will be editable.
325 *
326 * @throws WvcmException if the server is unable to rename the resource with the
327 * new name.
328 */
329 CqQueryFolderItem doRename(CqQueryFolder parentFolder,
330 String newName,
331 Feedback feedback,
332 List<CqContextResource> deliveryOrder)
333 throws WvcmException;
334
335
336 /**
337 * Makes an editable copy of the query folder item named by this proxy in
338 * the query folder specified in the argument list and deletes the query
339 * folder item at the current proxy location. Any dirty properties are
340 * written to the new copy after it is created.
341 * <p>
342 * This variant of doMove is provided because in the presence of stable or
343 * fast location formats the client cannot always guarantee that
344 * <code>parentFolder.child(childName)</code> is a valid location
345 * specification.
346 *
347 * @param parentFolder The folder to which this query folder item is to be
348 * moved. The location must name an existing query folder of this
349 * user database.
350 * @param childName The name this resource is to have in the destination
351 * folder.
352 * @param overwrite Specifies how a query folder item already at the target
353 * location is to be handled.
354 * @param feedback The properties to be defined by the proxy that is
355 * returned by this method.
356 * @param deliveryOrder Same as the deliveryOrder parameter of
357 * {@link #doCopy(StpLocation, com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem.OverwriteMode, Feedback, List) doCopy}.
358 * But note that use of {@link CqProvider#DELIVER} both
359 * delivers the copy and deletes the original query folder item.
360 *
361 * @return A proxy for the new copy of this resource. Unless the deliver
362 * option was specified, this resource will be editable.
363 *
364 * @throws WvcmException if the server is unable to create the copy at the
365 * specified location.
366 */
367 CqQueryFolderItem doMove(CqQueryFolder parentFolder,
368 String childName,
369 OverwriteMode overwrite,
370 Feedback feedback,
371 List<CqContextResource> deliveryOrder)
372 throws WvcmException;
373 }