ERDBObjectTable of Contents

Entity-Relationship Database Package Instance Object Introduction Public Methods AddValues Attributes Cross HasField new PrimaryValue SetDB Value Values Utility Methods _new Entity-Relationship Database Package Instance Object IntroductionThis package defines the instance object for the Entity-Relationship Database Package This object can be created directly, returned by the FetchDBQuery object, or returned by the Cross method of this object An object created directly is considered transient. An object created by one of th database methods is considered persistent. A transient object can be made persisten using the Insert method of the ERDB object.

An instance object allows the user to access the fields in the current instance. Th instance consists of zero or more entity and/or relationship objects and a map of fiel names to locations. Some entity fields require additional queries to the database. I the entity object is present, the additional queries are executed automatically. Otherwise the value is treated as missing.

Public Methods newmy $dbObject = ERDBObject::new($name1 => \@list1, $name2 => \@list2, ... $nameN => \@listN);

Create a new transient object. A transient object maps fields to values, but is no associated with a database. The parameter list should be an entity name followed b a set of key-value pairs. Each key should be in the standard objectName(attributeName)peg.1 with two hyperlinks.

my $feature = ERDBObject::new('Feature(id)' => ['peg.1'],'Feature(link)' => ['http://www.undhoople.edu/NC1004.html','http://www.miskatonic.edu/PC1006.html']);SetDBmy = $dbObject->SetDB($db, $target);

Attach a database to this object. This method is useful if you have to create a object manually (using new) but want to be able to use the database method (e.g. Cross) to retrieve additional data.

dbERDB object for the database to use.

targetName of the entity relevant to this object. This parameter is important for cases wher a single ERDBObject actually has data from multiple tables. The parameter indicate the table from which a relationship crossing should occur. So, for example, a ERDBObjec could contain data from the IsLocatedIn and Contig tables; we would specify target of Contig so that the Cross method crosses from there.

Attributesmy @attrNames = $dbObject->Attributes();

This method will return a sorted list of the attributes present in this object The list can be used in the Values method to get all the values stored.

If the ERDBObject was created by a database query, the attributes returned wil only be those which occur on the primary relation. Additional fields may ge loaded into the object if the client has asked for them in a Value o Values command. Initially, however, only the primary fields-- each of whic has one and only one value-- will be found in the attribute list.

HasFieldmy $flag = $dbObject->HasField($fieldSpec);

Return TRUE if this object has the specified field available, else FALSE This method can be used to determine if a value is available withou requiring an additional database query.

fieldSpecA standard field specifier, as is used to specify fields to the GetERDB object.

RETURNReturns TRUE if there's a value for the field in this object, else FALSE.

AddValues$dbObject->AddValues($name, @values);

Add one or more values to a specified field.

nameName of the field to receive the new values. If the field doe not exist, it will be created.

valuesList of values to put in the field.

PrimaryValuemy $value = $dbObject->PrimaryValue($name);

Return the primary value of a field. This will be its first value in a standard value list.

This method is a more convenient version of Value. Basically, the call

my ($value) = $dbObject->Value($name);is equivalent to

my $value = $dbObject->PrimaryValue($name);but the latter is syntactically more convenient.

nameName of the field whose value is desired, in the standard form.

RETURNReturns the value of the specified field, or undef if the field has no value.

Valuemy @values = $dbObject->Value($attributeName);

Return a list of the values for the specified attribute.

attributeNameName of the desired attribute, in the form objectName(fieldName).

RETURNReturns a list of the values for the specified attribute, which may have 0, 1, o multiple values.

Valuesmy @values = $dbObject->Values(\@attributeNames);

This method returns a list of all the values for a list of field specifiers. Essentially, it call the Value method for each element in the parameter list and returns a flattened list of al the results.

For example, let us say that $feature contains a feature with two links and a translation The following call will put the feature links in $link1 and $link2 and the translation i $translation.

my ($link1, $link2, $translation) = $feature->Values(['Feature(link)', 'Feature(translation)']);For convenience, you can also specify the fields as a space-delimited string. The following statemen is equivalent to the one above.

my ($link1, $link2, $translation) = $feature->Values('Feature(link) Feature(translation)');attributeNamesList of attribute names.

RETURNReturns a flattened list of all the results found for each specified field.

Crossmy $query = $dbObject->Cross($relationshipName, $filterClause, $param1, $param2, ... $paramN);

Return a query object for instances related to this one via a specified relationship.

relationshipNameName of the relationship to cross.

filterClauseWHERE clause (without the WHERE) to be used to filter the query. The WHERE clause can b parameterized with parameter markers (?). Each field used in the WHERE clause must b specified in the standard form objectName(fieldName).

param1, param2, ..., paramNParameters for the filter clause.

Utility Methods _newCreate a new instance object.

This is a static method.

dbqueryDBQuery object for the relevant query.

value, value2, ... valueNList of values returned by the query for the current object.