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, 2011.  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.Resource;
022import javax.wvcm.WvcmException;
023import javax.wvcm.PropertyNameList.PropertyName;
024
025import com.ibm.rational.wvcm.stp.StpProperty;
026import 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 */
058public 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>/&lt;file-name>&#64;&lt;db-set>/&lt;user-db>
215     * </pre>
216     * 
217     * <p>
218     * where
219     * &lt;record-type>/&lt;record-id>/&lt;field-name>/&lt;file-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}