Project: stp

com.ibm.rational.wvcm.stp.cq
Interface CqAttachment

All Superinterfaces:
CqContextResource, CqResource, CqUserDbMember, Resource, StpResource

public interface CqAttachment
extends CqContextResource

A proxy for an attachment resource.

Attachments are CqContextResources. Creation and modification of the attachment takes place in the client's change context for the database. Since to create, modify, or delete an action the host record must be modified an action is needed to perform these operations. This action, however, applies to the record with which the attachment is associated and not to the attachment itself.

The user-friendly specification for the location of an attachment has the form
  cq.record:<record-type>/<record-id>/<field-name>/<attachment-name>@<db-set>/<user-db>
 

The parent location of an attachment is an attachment folder whose name is the same as the name of the field with which the attachment is associated. The parent location of the attachment folder is the record with which the attachment is associated. Note that the attachment folder is also the value of the attachment field.

The content of the attachment is accessed using the doReadContent() method.


Nested Class Summary
 
Nested classes/interfaces inherited from interface com.ibm.rational.wvcm.stp.StpResource
StpResource.UnsupportedProperty
 
Nested classes/interfaces inherited from interface javax.wvcm.Resource
Resource.CopyFlag
 
Field Summary
static PropertyNameList.PropertyName<CqAction> ACTION
          The action under which this attachment's record is being modified; null if the record is not being modified.
static PropertyNameList.PropertyName<String> DESCRIPTION
          The description associated with the attachment
static PropertyNameList.PropertyName<String> DISPLAY_NAME
          The unique key used to identify the attachment
static PropertyNameList.PropertyName<CqFieldValue<?>> FIELD
          The field (within a record) that references this attachment
static PropertyNameList.PropertyName<String> FILE_NAME
          The file name associated with the attachment
static PropertyNameList.PropertyName<Long> FILE_SIZE
          The size of the attachment in bytes
 
Fields inherited from interface CqContextResource
IS_MODIFIED
 
Fields inherited from interface CqUserDbMember
DB_SET, USER_DB
 
Fields inherited from interface com.ibm.rational.wvcm.stp.StpResource
ALL_PROPERTIES, AUTHENTICATION_REALM, CREATOR_GROUP_NAME, CREATOR_LOGIN_NAME, EFFICIENT_LOCATION, INVALID_PROPERTIES, REPOSITORY, STABLE_LOCATION, USER_FRIENDLY_LOCATION
 
Fields inherited from interface javax.wvcm.Resource
ALL_CUSTOM_PROPERTIES, COMMENT, CONTENT_CHARACTER_SET, CONTENT_IDENTIFIER, CONTENT_LANGUAGE, CONTENT_LENGTH, CONTENT_TYPE, CREATION_DATE, CREATOR_DISPLAY_NAME, IS_EXECUTABLE, LAST_MODIFIED, PARENT_LIST, PATHNAME_LOCATION, PROVIDER_LIST, RESOURCE_IDENTIFIER, WORKSPACE_FOLDER_LIST
 
Method Summary
 CqAttachment doCreateAttachment(String filename, Feedback feedback, List<CqContextResource> deliveryOrder)
          Creates a new attachment at the location specified by this proxy(*) and initializes its content from a named file.
 CqAttachment doReadContent(String filename, Feedback feedback)
          Gets both the content and selected properties of this attachment.
 void doUnbindAll(Feedback feedback)
          Deleting an attachment requires that the parent record be opened for update.
 void doUnbindAll(Feedback feedback, List<CqContextResource> deliveryOrder)
          Deleting an attachment requires that the parent record be opened for update.
 Resource doWriteProperties(Feedback feedback)
          Updating an attachment requires that the parent record be opened for update.
 CqContextResource doWriteProperties(Feedback feedback, List<CqContextResource> deliveryOrder)
          Updating an attachment requires that the parent record be opened for update.
 CqAction getAction()
          Returns the value of the ACTION property as defined by this proxy.
 String getComment()
          Returns the attachment DESCRIPTION
 long getContentLength()
          Returns the attachment FILE_SIZE
 String getDescription()
          Returns the value of the DESCRIPTION property as defined by this proxy.
 String getDisplayName()
          Returns the value of the DISPLAY_NAME property as defined by this proxy.
 CqFieldValue<?> getField()
          Returns the value of the FIELD property as defined by this proxy.
 String getFileName()
          Returns the value of the FILE_NAME property as defined by this proxy.
 long getFileSize()
          Returns the value of the FILE_SIZE property as defined by this proxy.
 CqAttachment setAction(CqAction action)
          Defines a new value for the ACTION property of this proxy.
 void setDescription(String description)
          Defines a new value for the DESCRIPTION property.
 
Methods inherited from interface CqContextResource
doDeliver, doRevert, getIsModified
 
Methods inherited from interface CqUserDbMember
getDbSet, getUserDb
 
Methods inherited from interface CqResource
cqProvider, getContentCharacterSet, getContentIdentifier, getContentLanguage, getContentType, getCreationDate, getCreatorDisplayName, getCreatorGroupName, getCreatorLoginName, getIsExecutable, getLastModified, getProviderList, getWorkspaceFolderList, setComment, setContentCharacterSet, setContentLanguage, setContentType, setCreatorDisplayName, setIsExecutable
 
Methods inherited from interface com.ibm.rational.wvcm.stp.StpResource
doReadProperties, equals, getAllProperties, getAuthenticationRealm, getCustomProperties, getEfficientLocation, getInvalidProperties, getMetaProperties, getPropertyException, getRepository, getResourceError, getResourceIdentifier, getStableLocation, getUserFriendlyLocation, hashCode, hasProperties, initMetaProperty, proxyType, setPropertyClean, stpLocation, stpProvider
 
Methods inherited from interface javax.wvcm.Resource
doCopy, doFind, doFindAll, doGetPropertyNameList, doGetPropertyNameList, doReadContent, doReadProperties, doWriteContent, forgetProperty, getParentList, getPathnameLocation, getProperty, initProperty, location, lookupProperty, modifyLocation, propertyNameList, provider, removeProperty, setDisplayName, setProperty, setProperty, updatedPropertyNameList
 

Field Detail

ACTION

static final PropertyNameList.PropertyName<CqAction> ACTION
The action under which this attachment's record is being modified; null if the record is not being modified.


DESCRIPTION

static final PropertyNameList.PropertyName<String> DESCRIPTION
The description associated with the attachment


DISPLAY_NAME

static final PropertyNameList.PropertyName<String> DISPLAY_NAME
The unique key used to identify the attachment


FIELD

static final PropertyNameList.PropertyName<CqFieldValue<?>> FIELD
The field (within a record) that references this attachment


FILE_NAME

static final PropertyNameList.PropertyName<String> FILE_NAME
The file name associated with the attachment


FILE_SIZE

static final PropertyNameList.PropertyName<Long> FILE_SIZE
The size of the attachment in bytes

Method Detail

doCreateAttachment

CqAttachment doCreateAttachment(String filename,
                                Feedback feedback,
                                List<CqContextResource> deliveryOrder)
                                throws WvcmException
Creates a new attachment at the location specified by this proxy(*) and initializes its content from a named file.

(*) The server is permitted to modify the location. The proxy returned is a proxy that addresses the location actually chosen by the server. For attachments, the location must be in the form

       cq.record:<record-type>/<record-id>/<field-name>/<file-name>@<db-set>/<user-db>
 

where <record-type>/<record-id>/<field-name>/<file-name>@<db-set>/<user-db> identifies the field with which this new attachment is to be associated

To create an attachment, the host record must be modified. If the record is not already editable, the action under which the record should be modified can be specified as the value of the ACTION property of this proxy. If no action is specified and the record is not already being modified, the default modify action will be used, if unique.

Parameters:
filename - The full file pathname of the file from which the content of the attachment is to be read. The file named by this parameter must exist until the change context of this proxy is delivered to the database.
feedback - A Feedback instance requesting the properties desired from the created attachment and related resources. May be null if no properties are desired.
deliveryOrder - If CqProvider.HOLD the new attachment and its modified record are left in a writable state in the target database's change context. The change context must be delivered before the changes become visible outside the change context. To deliver the entire change context in an arbitrary order, use CqProvider.DELIVER_ALL. To deliver just the new attachment and its modified record, use CqProvider.DELIVER. If not one of these values, the modified resource named in this argument will be delivered to the database in the order specified in this argument.
Returns:
An CqAttachment proxy for the created attachment. This proxy will define the properties requested by the Feedback argument.
Throws:
WvcmException - If the resource cannot be created with the given properties. If the resource is successfully created, but properties cannot be written to it or the changes cannot be delivered to the database (when requested), the resource attribute of the thrown exception will be a proxy for the newly created resource. If the new resource could not be created, the resource attribute of the exception will be this proxy.

doReadContent

CqAttachment doReadContent(String filename,
                           Feedback feedback)
                           throws WvcmException
Gets both the content and selected properties of this attachment.

This version of doReadContent is more efficient than the standard WVCM doReadContent when interfacing with the ClearQuest desktop application since the application can write the attachment contents directly to the named file without the need to create a temporary file.

Parameters:
filename - the resource content is written to the file named by this string.
feedback - A request for the properties to be returned in the result proxy. May be null.
Returns:
a CqAttachment proxy containing the requested properties.
Throws:
WvcmException - if problems are encountered communicating with server

doUnbindAll

void doUnbindAll(Feedback feedback)
                 throws WvcmException
Deleting an attachment requires that the parent record be opened for update. If an action has not already been started on the parent record, the action to use may be specified by setting the ACTION property of this proxy before invoking this method.

Specified by:
doUnbindAll in interface CqContextResource
Specified by:
doUnbindAll in interface Resource
Throws:
WvcmException - If the resource does not exist or cannot be deleted using the default DELETE action.
See Also:
CqContextResource.doUnbindAll(Feedback)

doUnbindAll

void doUnbindAll(Feedback feedback,
                 List<CqContextResource> deliveryOrder)
                 throws WvcmException
Deleting an attachment requires that the parent record be opened for update. If an action has not already been started on the parent record, the action to use may be specified by setting the ACTION property of this proxy before invoking this method. Note that use of the CqProvider.DELIVER delivery order list requests deletion of this attachment and delivery of its parent record and any other attachments currently in the change context.

Specified by:
doUnbindAll in interface CqContextResource
Parameters:
feedback - A Feedback object requesting the properties desired from resources modified during this operation. May be null if no properties are desired.
deliveryOrder - If CqProvider.HOLD the moribund resource is left in the change context and not actually deleted--it must be delivered before the deletion becomes visible to other providers. If not CqProvider.HOLD, the modified and moribund resources specified by this parameter will be delivered to or deleted from the database in the order indicated. To deliver all modified and moribund resources in an arbitrary order, use CqProvider.DELIVER_ALL. To deliver just this moribund resource, use CqProvider.DELIVER. Must not be null.
Throws:
WvcmException - If the resource does not exist or cannot be deleted using the default DELETE action.
See Also:
CqContextResource.doUnbindAll(Feedback, List)

doWriteProperties

Resource doWriteProperties(Feedback feedback)
                           throws WvcmException
Updating an attachment requires that the parent record be opened for update. If an action has not already been started on the parent record, the action to use may be specified by setting the ACTION property of this proxy before invoking this method.

Specified by:
doWriteProperties in interface CqContextResource
Specified by:
doWriteProperties in interface Resource
Parameters:
feedback - Specifies optional feedback to the caller.
Returns:
A proxy for this resource (after delivery if a delivery happens) populated with the properties requested by the Feedback object for the result.
Throws:
WvcmException - If there are errors when attempting update properties or deliver the resource back to the database.
See Also:
CqContextResource.doWriteProperties(Feedback)

doWriteProperties

CqContextResource doWriteProperties(Feedback feedback,
                                    List<CqContextResource> deliveryOrder)
                                    throws WvcmException
Updating an attachment requires that the parent record be opened for update. If an action has not already been started on the parent record, the action to use may be specified by setting the ACTION property of this proxy before invoking this method. Note that use of the CqProvider.DELIVER delivery order list requests delivery of this attachment, its parent record, and any other attachments currently in the change context.

Specified by:
doWriteProperties in interface CqContextResource
Parameters:
feedback - An instance of Feedback requesting properties for this resource and for the resources delivered by this operation. May be null if no feedback is desired.
deliveryOrder - If CqProvider.HOLD the modified resource is left in a writable state in the change context--the modified resource in the change context must be delivered before the modifications become visible to other providers. If not CqProvider.HOLD, the modified and moribund resources specified by this parameter will be delivered to or deleted from the database in the order indicated. To deliver all modified and moribund resources in an arbitrary order, use CqProvider.DELIVER_ALL. To deliver just this modified resource, use CqProvider.DELIVER. Must not be null.
Returns:
A proxy for this resource populated with the properties requested by the Feedback object for the result. The properties reflect the state of the resource after delivery if delivery has been requested.
Throws:
WvcmException - If there are errors when attempting to write properties or deliver the resource.
See Also:
CqContextResource.doWriteProperties(Feedback, List)

getAction

CqAction getAction()
                   throws WvcmException
Returns the value of the ACTION property as defined by this proxy.

Returns:
Returns an CqAction proxy representing the action under which the this attachment's record is being modified.
Throws:
WvcmException - if this proxy does not define a value for the ACTION property.

getComment

String getComment()
                  throws WvcmException
Returns the attachment DESCRIPTION

Specified by:
getComment in interface CqResource
Specified by:
getComment in interface Resource
Returns:
the Resource.COMMENT property.
Throws:
WvcmException - if this property was not set and this Resource was not created with Resource.COMMENT as a wanted property.
See Also:
Resource.getComment()

getContentLength

long getContentLength()
                      throws WvcmException
Returns the attachment FILE_SIZE

Specified by:
getContentLength in interface CqResource
Specified by:
getContentLength in interface Resource
Returns:
the Resource.CONTENT_LENGTH property.
Throws:
WvcmException - if this Resource was not created with Resource.CONTENT_LENGTH as a wanted property.
See Also:
Resource.getContentLength()

getDescription

String getDescription()
                      throws WvcmException
Returns the value of the DESCRIPTION property as defined by this proxy.

Returns:
A String containing a short description of this attachment.
Throws:
WvcmException - if this proxy does not define a value for the DESCRIPTION property.

getDisplayName

String getDisplayName()
                      throws WvcmException
Returns the value of the DISPLAY_NAME property as defined by this proxy.

Specified by:
getDisplayName in interface Resource
Returns:
A String containing the unique key used to identify this attachment
Throws:
WvcmException - if this proxy does not define a value for the DISPLAY_NAME property.
See Also:
Resource.setDisplayName(java.lang.String)

getField

CqFieldValue<?> getField()
                         throws WvcmException
Returns the value of the FIELD property as defined by this proxy.

Returns:
A CqFieldValue identifying the field of which this attachment is a nested value.
Throws:
WvcmException - if this proxy does not define a value for the FIELD property.

getFileName

String getFileName()
                   throws WvcmException
Returns the value of the FILE_NAME property as defined by this proxy.

Returns:
A String containing the name of the file that originally held this attachment data.
Throws:
WvcmException - if this proxy does not define a value for the FILE_NAME property.

getFileSize

long getFileSize()
                 throws WvcmException
Returns the value of the FILE_SIZE property as defined by this proxy.

Returns:
The number of bytes in this attachment.
Throws:
WvcmException - if this proxy does not define a value for the FILE_SIZE property.

setAction

CqAttachment setAction(CqAction action)
Defines a new value for the ACTION property of this proxy. Set this value prior to invoking doCreateAttachment, doWriteProperties or doUnbindAll on this proxy to specify an action other than the default action specified for those operations.

Parameters:
action - A CqAction proxy identifying the action under which this attachment's record is to be modified when creating, updating, or deleting this attachment. For the update to succeed, the given action must be on the LEGAL_ACTIONs list for the attachment's record. If no value is provided, the action used to modify the attachment's parent record will be the default MODIFY type action if that is uniquely defined by the record type.
Returns:
this proxy

setDescription

void setDescription(String description)
Defines a new value for the DESCRIPTION property. Changes do not take effect until doWriteProperties() has been successfully executed on this proxy and the changes are delivered to the database.

Parameters:
description - The descriptive text to be associated with the attachment.

Generated Fri 24-May-2013 12:47 AM

Copyright © IBM 2013. All rights reserved.