001    /*
002     * file CqAttachment.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.cq.CqAttachment
008     *
009     * (C) Copyright IBM Corporation 2004, 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.Resource;
022    import javax.wvcm.WvcmException;
023    import javax.wvcm.PropertyNameList.PropertyName;
024    
025    import com.ibm.rational.wvcm.stp.StpProperty;
026    import com.ibm.rational.wvcm.stp.StpResource;
027    
028    
029    /**
030     * A proxy for an attachment resource.
031     * 
032     * <p>
033     * Attachments are CqContextResources. Creation and modification of the
034     * attachment takes place in the client's change context for the database. Since
035     * to create, modify, or delete an action the host record must be modified an
036     * action is needed to perform these operations. This action, however, applies
037     * to the record with which the attachment is associated and not to the
038     * attachment itself.
039     * </p>
040     * The user-friendly specification for the location of an attachment has the
041     * form
042     * 
043     * <pre>
044     *  <b>cq.record:</b><i>&lt;record-type&gt;</i>/<i>&lt;record-id&gt;</i>/<i>&lt;field-name&gt;</i>/<i>&lt;attachment-name&gt;</i><b>@</b><i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
045     * </pre>
046     * 
047     * <p>
048     * The parent location of an attachment is an attachment folder whose name is
049     * the same as the name of the field with which the attachment is associated.
050     * The parent location of the attachment folder is the record with which the
051     * attachment is associated. Note that the attachment folder is also the value
052     * of the attachment field.
053     * <p>
054     * The content of the attachment is accessed using the
055     * {@link #doReadContent doReadContent()} method.
056     * </p>
057     */
058    public interface CqAttachment
059        extends CqContextResource
060    {
061        /**
062         * Returns the attachment FILE_SIZE
063         * @see javax.wvcm.Resource#getContentLength()
064         */
065        long getContentLength() throws WvcmException;
066        
067        /**
068         * Returns the attachment DESCRIPTION
069         * @see javax.wvcm.Resource#getComment()
070         */
071        String getComment() throws WvcmException;
072        
073        /** The unique key used to identify the attachment */
074        PropertyName<String> DISPLAY_NAME = StpResource.DISPLAY_NAME;
075    
076        /**
077         * Returns the value of the {@link #DISPLAY_NAME DISPLAY_NAME} property as
078         * defined by this proxy.
079         *
080         * @return  A String containing the unique key used to identify this
081         *          attachment
082         *
083         * @throws  WvcmException  if this proxy does not define a value for the
084         *                         {@link #DISPLAY_NAME DISPLAY_NAME} property.
085         */
086        public String getDisplayName()
087            throws WvcmException;
088    
089        /** The description associated with the attachment */
090        PropertyName<String> DESCRIPTION =
091            new PropertyName<String>(PROPERTY_NAMESPACE, "description");
092    
093        /**
094         * Returns the value of the {@link #DESCRIPTION DESCRIPTION} property as
095         * defined by this proxy.
096         *
097         * @return  A String containing a short description of this attachment.
098         *
099         * @throws  WvcmException  if this proxy does not define a value for the
100         *                         {@link #DESCRIPTION DESCRIPTION} property.
101         */
102        public String getDescription()
103            throws WvcmException;
104    
105        /**
106         * Defines a new value for the DESCRIPTION property. Changes do not take
107         * effect until doWriteProperties() has been successfully executed on this
108         * proxy and the changes are delivered to the database.
109         *
110         * @param  description  The descriptive text to be associated with the
111         *                      attachment.
112         */
113        public void setDescription(String description);
114    
115        /** The file name associated with the attachment */
116        PropertyName<String> FILE_NAME =
117            new PropertyName<String>(PROPERTY_NAMESPACE, "file-name");
118    
119        /**
120         * Returns the value of the {@link #FILE_NAME FILE_NAME} property as defined
121         * by this proxy.
122         *
123         * @return  A String containing the name of the file that originally held
124         *          this attachment data.
125         *
126         * @throws  WvcmException  if this proxy does not define a value for the
127         *                         {@link #FILE_NAME FILE_NAME} property.
128         */
129        public String getFileName()
130            throws WvcmException;
131    
132        /** The size of the attachment in bytes */
133        PropertyName<Long> FILE_SIZE =
134            new PropertyName<Long>(PROPERTY_NAMESPACE, "file-size");
135    
136        /**
137         * Returns the value of the {@link #FILE_SIZE FILE_SIZE} property as defined
138         * by this proxy.
139         *
140         * @return  The number of bytes in this attachment.
141         *
142         * @throws  WvcmException  if this proxy does not define a value for the
143         *                         {@link #FILE_SIZE FILE_SIZE} property.
144         */
145        public long getFileSize()
146            throws WvcmException;
147    
148        /** The field (within a record) that references this attachment */
149        PropertyName<CqFieldValue<?>> FIELD =
150            new PropertyName<CqFieldValue<?>>(PROPERTY_NAMESPACE, "field");
151    
152        /**
153         * Returns the value of the {@link #FIELD FIELD} property as defined by this
154         * proxy.
155         * 
156         * @return A CqFieldValue identifying the field of which this attachment is
157         *         a nested value.
158         * 
159         * @throws WvcmException if this proxy does not define a value for the
160         *             {@link #FIELD FIELD} property.
161         */
162        public CqFieldValue<?> getField()
163            throws WvcmException;
164    
165        /**
166         * The action under which this attachment's record is being modified; null
167         * if the record is not being modified.
168         */
169        PropertyName<CqAction> ACTION = CqRecord.ACTION;
170    
171        /**
172         * Returns the value of the {@link #ACTION ACTION} property as defined by
173         * this proxy.
174         * 
175         * @return Returns an CqAction proxy representing the action under which the
176         *         this attachment's record is being modified.
177         * 
178         * @throws WvcmException if this proxy does not define a value for the
179         *             {@link #ACTION ACTION} property.
180         */
181        CqAction getAction() throws WvcmException;
182    
183        /**
184         * Defines a new value for the {@link #ACTION ACTION} property of this
185         * proxy. Set this value prior to invoking doCreateAttachment,
186         * doWriteProperties or doUnbindAll on this proxy to specify an action other
187         * than the default action specified for those operations.
188         * 
189         * @param action A CqAction proxy identifying the action under which this
190         *            attachment's record is to be modified when creating, updating,
191         *            or deleting this attachment. For the update to succeed, the
192         *            given action must be on the LEGAL_ACTIONs list for the
193         *            attachment's record. If no value is provided, the action used
194         *            to modify the attachment's parent record will be the default
195         *            MODIFY type action if that is uniquely defined by the record
196         *            type.
197         * 
198         * @return this proxy
199         */
200        CqAttachment setAction(CqAction action);
201        
202        /**
203         * Creates a new attachment at the location specified by this proxy(*) and
204         * initializes its content from a named file.
205         * 
206         * <p>
207         * (*) The server is permitted to modify the location. The proxy returned is
208         * a proxy that addresses the location actually chosen by the server. For
209         * attachments, the location must be in the form
210         * </p>
211         * <p>
212         * 
213         * <pre>
214           cq.record:&lt;record-type>/&lt;record-id>/&lt;field-name>/anything&#64;&lt;db-set>/&lt;user-db>
215         * </pre>
216         * 
217         * <p>
218         * where
219         * &lt;record-type>/&lt;record-id>/&lt;field-name>&#64;&lt;db-set>/&lt;user-db>
220         * identifies the field with which this new attachment is to be associated
221         * <p>
222         * To create an attachment, the host record must be modified. If the record
223         * is not already editable, the action under which the record should be
224         * modified can be specified as the value of the ACTION property of this
225         * proxy. If no action is specified and the record is not already being
226         * modified, the default modify action will be used, if unique.
227         * 
228         * @param filename The full file pathname of the file from which the content
229         *            of the attachment is to be read. The file named by this
230         *            parameter must exist until the change context of this proxy is
231         *            delivered to the database.
232         * @param feedback A Feedback instance requesting the properties desired
233         *            from the created attachment and related resources. May be
234         *            <b>null</b> if no properties are desired.
235         * @param deliveryOrder If {@link CqProvider#HOLD} the new attachment and
236         *            its modified record are left in a writable state in the target
237         *            database's change context. The change context must be
238         *            delivered before the changes become visible outside the change
239         *            context. To deliver the entire change context in an arbitrary
240         *            order, use {@link CqProvider#DELIVER_ALL}. To deliver just
241         *            the new attachment and its modified record, use
242         *            {@link CqProvider#DELIVER}. If not one of these values, the
243         *            modified resource named in this argument will be delivered to
244         *            the database in the order specified in this argument.
245         * 
246         * @return An CqAttachment proxy for the created attachment. This proxy will
247         *         define the properties requested by the Feedback argument.
248         * 
249         * @throws WvcmException If the resource cannot be created with the given
250         *             properties. If the resource is successfully created, but
251         *             properties cannot be written to it or the changes cannot be
252         *             delivered to the database (when requested), the resource
253         *             attribute of the thrown exception will be a proxy for the
254         *             newly created resource. If the new resource could not be
255         *             created, the resource attribute of the exception will be this
256         *             proxy.
257         */
258        CqAttachment doCreateAttachment(String filename,
259                                        Feedback feedback,
260                                        List<CqContextResource> deliveryOrder)
261            throws WvcmException;
262        
263        /**
264         * Updating an attachment requires that the parent record be opened for 
265         * update. If an action has not already been started on the parent record,
266         * the action to use may be specified by setting the ACTION property of this
267         * proxy before invoking this method.
268         * 
269         * @see CqContextResource#doWriteProperties(Feedback)
270         */
271        Resource doWriteProperties(Feedback feedback)
272            throws WvcmException;
273    
274        /**
275         * Updating an attachment requires that the parent record be opened for
276         * update. If an action has not already been started on the parent record,
277         * the action to use may be specified by setting the ACTION property of this
278         * proxy before invoking this method.
279         * 
280         * Note that use of the {@link CqProvider#DELIVER} delivery order list
281         * requests delivery of this attachment, its parent record, and any other
282         * attachments currently in the change context.
283         * 
284         * @see CqContextResource#doWriteProperties(Feedback, List)
285         */
286        CqContextResource doWriteProperties(
287            Feedback feedback,
288            List<CqContextResource>  deliveryOrder)
289            throws WvcmException;
290    
291        /**
292         * Deleting an attachment requires that the parent record be opened for
293         * update. If an action has not already been started on the parent record,
294         * the action to use may be specified by setting the ACTION property of this
295         * proxy before invoking this method.
296         * 
297         * @see CqContextResource#doUnbindAll(Feedback)
298         */
299        void doUnbindAll(Feedback feedback)
300            throws WvcmException;
301    
302        /**
303         * Deleting an attachment requires that the parent record be opened for
304         * update. If an action has not already been started on the parent record,
305         * the action to use may be specified by setting the ACTION property of this
306         * proxy before invoking this method.
307         * 
308         * Note that use of the {@link CqProvider#DELIVER} delivery order list
309         * requests deletion of this attachment and delivery of its parent record
310         * and any other attachments currently in the change context.
311         * 
312         * @see CqContextResource#doUnbindAll(Feedback, List)
313         */
314        void 
315        doUnbindAll(Feedback feedback, 
316                 List<CqContextResource> deliveryOrder)
317            throws WvcmException;
318    
319        /**
320         * Gets both the content and selected properties of this attachment.
321         * 
322         * <p>
323         * This version of doReadContent is more efficient than the standard WVCM
324         * doReadContent when interfacing with the ClearQuest desktop application
325         * since the application can write the attachment contents directly to the
326         * named file without the need to create a temporary file.
327         * </p>
328         * 
329         * @param filename the resource content is written to the file named by this
330         *            string.
331         * @param feedback A request for the properties to be returned in the result
332         *            proxy. May be <b>null</b>.
333         * 
334         * @return a CqAttachment proxy containing the requested properties.
335         * 
336         * @throws WvcmException if problems are encountered communicating with
337         *             server
338         */
339        public CqAttachment doReadContent(
340            String   filename,
341            Feedback feedback)
342            throws WvcmException;
343    }