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, 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.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>&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     */
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         * Makes an editable copy of the query folder item named by this proxy in
312         * the query folder specified in the argument list and deletes the query
313         * folder item at the current proxy location. Any dirty properties are
314         * written to the new copy after it is created.
315         * <p>
316         * This variant of doMove is provided because in the presence of stable or
317         * fast location formats the client cannot always guarantee that
318         * <code>parentFolder.child(childName)</code> is a valid location
319         * specification.
320         * 
321         * @param parentFolder The folder to which this query folder item is to be
322         *            moved. The location must name an existing query folder of this
323         *            user database.
324         * @param childName The name this resource is to have in the destination
325         *            folder.
326         * @param overwrite Specifies how a query folder item already at the target
327         *            location is to be handled.
328         * @param feedback The properties to be defined by the proxy that is
329         *            returned by this method.
330         * @param deliveryOrder Same as the deliveryOrder parameter of
331         *            {@link #doCopy(StpLocation, com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem.OverwriteMode, Feedback, List) doCopy}.
332         *            But note that use of {@link CqProvider#DELIVER} both
333         *            delivers the copy and deletes the original query folder item.
334         * 
335         * @return A proxy for the new copy of this resource. Unless the deliver
336         *         option was specified, this resource will be editable.
337         * 
338         * @throws WvcmException if the server is unable to create the copy at the
339         *             specified location.
340         */
341        CqQueryFolderItem doMove(CqQueryFolder parentFolder,
342                                 String childName,
343                                 OverwriteMode overwrite,
344                                 Feedback feedback,
345                                 List<CqContextResource> deliveryOrder)
346            throws WvcmException;
347    }