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 * © 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><record-type></i>/<i><record-id></i>/<i><field-name></i>/<i><attachment-name></i><b>@</b><i><db-set></i>/<i><user-db></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:<record-type>/<record-id>/<field-name>/anything@<db-set>/<user-db>
215 * </pre>
216 *
217 * <p>
218 * where
219 * <record-type>/<record-id>/<field-name>@<db-set>/<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 }