Writing properties

You can use the Rational® ClearQuest® CM API to set a new value for a property in the proxy object by using the property-specific set method, if it exists. Properties that do not have a set method cannot be set by using the Rational ClearQuest CM API.

When specifying new values in a set method, the values are stored in the proxy. The values are not written to the actual resource in its repository until the client application calls a do method such as the doWriteProperties method on the proxy object.

You must call a do method such as doWriteProperties method to update the underlying resource in the product repository. The method writes the updated properties in the proxy to the product resource all as one transaction. Failures do not occur when property values are set in the proxy, but can occur when the do method is called. At that time, an exception might be thrown.

The following example appends some text to the Comment property of a resource:

PropertyRequest requestComment = 
   new PropertyRequest (Resource.COMMENT );
Location location = myProvider.location(...);
Resource myResource = myProvider.resource(location);
myResource = myResource.doReadProperties(requestComment);
String comment = myResource.getComment();
myResource.setComment(comment + "addition to comment");
myResource.doWriteProperties(null);

The doWriteProperties() method takes a PropertyRequest parameter.

It is not necessary to call doReadProperties() before calling doWriteProperties() if you know what property value to write without first reading the current value. In the following example, the Owner field of Defect SAMPL00000005 in the sample database is set to user = admin.

Here is the location string syntax for a record location:

cq.record:<record-type>/<record-id>@<db-set-name>/<database-name>

In this example, the record location string is:

"cq.record:Defect/SAMPL00000005@7.0.0/SAMPL"

where:

<record-type> is Defect
<record-id> is SAMPL00000005
<db-set-name> is 7.0.0
<database-name> is SAMPL

The Resource.setProperty method is used an alternative to the interface-specific set methods.

CqRecord myRecord = myCqProvider.cqRecord(myProvider.stpLocation("cq.record:Defect/SAMPL00000005@7.0.0/SAMPL"));
PropertyName<CqRecord> OWNER = new FieldName<CqRecord>("Owner");

myRecord.setProperty(OWNER, myProvider.buildProxy(CqRecord.class, "cq.record:users/admin@7.0.0/SAMPL"));
myRecord.doWriteProperties(null);

See Location syntax for more information.