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