/ 
VCS-CMSynergy-1.14
River stage zero No dependents
/ VCS::CMSynergy::Object

NAME

VCS::CMSynergy::Object - Convenience wrapper to treat objectnames as an object

SYNOPSIS

use VCS::CMSynergy;

$ccm = VCS::CMSynergy->new(%attr);

$obj1 = $ccm->object($name, $version, $cvtype, $instance);
$obj2 = $ccm->object($objectname);

print "...and the object is $obj";
print "name     =", $obj->name;
print "version  =", $obj->version;
print "cvtype   =", $obj->cvtype;
print "instance =", $obj->instance;
print $obj1->objectname;

## tiehash interface

print $obj->{comment};	
# same as print $ccm->get_attribute(comment => $obj)

$obj->{comment} = "blurfl";	
# same as $ccm->set_attribute(comment => $obj, "blurfl")

$obj->create_attribute("foo", "text");
$obj->delete_attribute("foo");
$hashref = $obj->list_attributes;
print $obj->displayname;

This synopsis only lists the major methods.

DESCRIPTION

A VCS::CMSynergy::Object is mostly a glorified wrapper for a CM Synergy's objectname (sometimes called object reference form in CM Synergy documentation). Because of its overloaded string conversion method (see below), it can be used with VCS::CMSynergy methods wherever an objectname would be appropriate, esp. where the documentation specifies a file_spec.

There is also a "TIEHASH INTERFACE" for manipulating an object's attributes using the hash notation.

METHODS

new

Create a VCS::CMSynergy::Object from a CM Synergy session and either an objectname (sometimes called object reference form in CM Synergy documentation) in "name-version:cvtype:instance" format or the four parts specified separately.

Usually you would not call this method directly, but rather via the wrapper "object" in VCS::CMSynergy.

Note that no check is made whether the specified object really exists in the database.

objectname

Returns the object's complete name in object reference form.

name

Returns the object's name.

version

Returns the object's version.

cvtype

Returns the object's type.

instance

Returns the object's instance (also called subsystem in older documentation).

string conversion

VCS::CMSynergy::Object overloads string conversion with "objectname", i.e. the following expressions evaluate to the same string:

"$obj"  
$obj->objectname

This makes it possible to use a VCS::CMSynergy::Object throughout VCS::CMSynergy wherever an objectname would have been appropriate.

proj_vers

Returns

$obj->name . "_" . $obj->version

(i.e. the displayname for a project object), but also checks that $obj->cvtype actually is "project".

TIEHASH INTERFACE

print $obj->{comment};	
$obj->{comment} = "blurfl";

NOTE: The tiehash interface and all other methods described below are only available when you have Scalar::Util installed. See "Why is Scalar::Util needed?" for an explanation.

You can use a VCS::CMSynergy::Object reference in the same way you would use a hash reference. The available keys are the underlying CM Synergy object's attributes.

Note that contrary to the behaviour of real hashes, keys don't spring into existence "on demand". Getting or setting the value of an attribute that does not exist for the underlying CM Synergy object will return undef or throw an excpetion (depending on your sessions's "RaiseError" in VCS::CMSynergy option). However, exists works as expected.

FETCH

$value = $obj->{attribute_name};

A wrapper for "get_attribute" in VCS::CMSynergy.

STORE

$obj->{attribute_name} = $value;

A wrapper for "set_attribute" in VCS::CMSynergy.

EXISTS

Checks the return value from "list_attributes" for the existence of the key (attribute) given.

FIRSTKEY, NEXTKEY

foreach (@{ $obj->keys })  { ... }
foreach (@{ $obj->values })  { ... }
while (my ($attr, $val) = each %$obj)  { ... }

These use "list_attributes" to obtain a list of attributes and then iterate over this list. Hence keys, values, and each all work as expected.

create_attribute

$obj->create_attribute($attribute_name, $attribute_type);

A wrapper for "create_attribute" in VCS::CMSynergy.

delete_attribute

$obj->delete_attribute($attribute_name");

A wrapper for "delete_attribute" in VCS::CMSynergy.

copy_attribute

$obj->copy_attribute($attribute_name, $flags, @to_file_specs);

A wrapper for "copy_attribute" in VCS::CMSynergy.

list_attributes

$hashref = $obj->list_attributes;

A wrapper for "list_attributes" in VCS::CMSynergy.

Note that returned hash is cached in the VCS::CMSynergy::Object (and updated for successfull "create_attribute" and "delete_attribute").

property

$value = $obj->property($keyword);

A wrapper for "property" in VCS::CMSynergy.

displayname

print $obj->displayname;

Short hand for $obj->property("displayname"), except that the return value is cached in the VCS::CMSynergy::Object.

Why is Scalar::Util needed?

In order to implement methods that actually invoke CM Synergy operations, every VCS::CMSynergy::Object has to keep a reference to the session (a VCS::CMSynergy) wherein it was created. These references can stall the timely garbage collection of a session (including the ccm stop called from "DESTROY" in VCS::CMSynergy) if a VCS::CMSynergy::Object has a longer lifetime than its session. To prevent this we need to make the reference to the session not count w.r.t. to garbage collection. We use "weaken" in Scalar::Util for that. If the session goes away before the VCS::CMSynergy::Object gets destroyed, its session reference will become undef. Hence any method called on the VCS::CMSynergy::Object which involves a CM Synergy operation will result in an error Can't call method "..." on an undefined value.

SEE ALSO

VCS::CMSynergy