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
014package com.ibm.rational.wvcm.stp.cq;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import java.util.List;
019
020import javax.wvcm.Feedback;
021import javax.wvcm.ResourceList;
022import javax.wvcm.WvcmException;
023import javax.wvcm.PropertyNameList.PropertyName;
024import javax.wvcm.PropertyRequestItem.PropertyRequest;
025
026import com.ibm.rational.wvcm.stp.StpLocation;
027import 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>&lt;parent-folder-path&gt;</i>/<i>&lt;item-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
038 * </pre>
039 * 
040 */
041public 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}