BuildEntity 方法利用针对指定用户数据库的唯一标识创建新的 Entity 对象,并启动针对该记录的提交操作。在提交操作期间,该记录可用于编辑 Entity 对象中的缺省值。
如果您使用 BuildEntity 创建了 Entity 对象,但尚未将其落实到数据库,那么该对象是可编辑的。
BuildEntity 方法会创建指定类型的新记录然后开始提交操作,这使您可以开始编辑记录的内容。(您不需要调用 EditEntity 以使记录为可编辑)。您可以使用所返回 Entity 对象的 SetFieldValue 方法为新记录的字段赋值。完成更新记录后,请分别使用 Entity 对象的 Validate 和 Commit 方法来验证和落实对记录所做的任何更改。 在 entitydef_name 参数中指定的名称还必须对应于模式中适当的记录类型。要获取 entitydef_name 的合法名称的列表,请使用 GetSubmitEntityDefNames 方法。
$session->BuildEntity(entity_def_name);
# Build Session object...
# Create a new "defect" record
$entityobj = $sessionobj->BuildEntity("defect");
调用 BuildEntity 方法后,您可以调用 Entity 对象的方法来设置本教程上一课中所描述记录中的字段值。
要创建新记录:
以下示例演示如何处理有状态和无状态记录类型。
您的模式具有无状态记录,如“项目”,以及有状态记录(可从一种状态转变为另一种),如“缺陷”。Rational ClearQuest API 使您能够获取和设置这两种类型记录的字段值。 以下示例包括两个子例程:针对无状态记录的 No_state 和针对有状态记录的 Has_state。
sub myValidateCommit( $entity ){
$status = $entity->Validate;
if ( $status ) {
$entity->Revert;
# for simplicity, we die on any error, you should do what makes sense in your
# application if recovery is possible.
die "Error validating: $status \n";
}
else {
$entity->Commit;
}
}
sub No_state {
my($session) = @_;
my($entity);
my($failure);
print "Test for stateless entities is starting";
print "submit a stateless entity";
$entity = $session->BuildEntity("project");
# ignore failure $failure = $entity->SetFieldValue("name", "initial project name");
DumpFields($entity);
myValidateCommit( $entity );
$entity = "";
print "Reload, show values before modification";
# Note that the Entity->Reload method can be used to force a refresh of the entity from the database.
$entity = $session->GetEntity("project", "initial project name");
DumpFields($entity);
print "Modify, then show new values";
$session->EditEntity($entity, "modify");
# ignore the failure
$failure = $entity->SetFieldValue("name", "modified project name");
DumpFields($entity);
print "revert, then show restored values";
$entity->Revert();
DumpFields($entity);
print "Modify again, and commit";
$session->EditEntity($entity, "modify");
# ignore failure
$failure = $entity->SetFieldValue("name", "final project name");
myValidateCommit( $entity );
$entity = "";
print "Reload, and show final result";
$entity = $session->GetEntity("project", "final project name");
DumpFields($entity);
$entity = "";
print "Test for stateless entities is done";
}
sub Has_states {
my($session) = @_;
my($entity);
# the entity that is stateful
# failure message from functions that return strings
my($failure);
my($id);
# Rational ClearQuest defect database ID
print "Test for stateful entities is starting";
print "submit a stateful entity";
$entity = $session->BuildEntity("defect");
# ignore failures
$failure = $entity->SetFieldValue("headline", "man bites dog!");
$failure = $entity->SetFieldValue("project", "final project name");
$failure = $entity->SetFieldValue("submit_date", "03/18/2000 10:09:08");
$id = $entity->GetDbId();
open(FILE, ">>XXStdout");
print FILE, "Entity id is", $id, "\n";
close FILE;
DumpFields($entity);
myValidateCommit( $entity );
$entity = "";
print "Reload, show values before modification";
# Note that the Entity->Reload method can be used to force a refresh of the entity from the database.
$entity = $session->GetEntityByDbId("defect", $id);
DumpFields($entity);
print "Modify then show new values";
$session->EditEntity($entity, "modify");
# ignore failure
$failure = $entity->SetFieldValue("headline", "man bites tree!");
DumpFields($entity);
print "revert, then show restored values";
$entity->Revert();
DumpFields($entity);
print "Modify again and commit";
$session->EditEntity($entity, "modify");
# ignore failure
$failure = $entity->SetFieldValue("headline", "tree bites man!");
myValidateCommit( $entity );
$entity = "";
print "Reload and show before changing state";
$entity = $session->GetEntityByDbId("defect", $id);
DumpFields($entity);
print "Change to new state, then show new values";
$session->EditEntity($entity, "close");
$failure = $entity->SetFieldValue("description", "looked like an oak tree");
# ignore failure
DumpFields($entity);
print "revert then show restored values";
$entity->Revert();
DumpFields($entity);
print "Change to new state again then commit";
$session->EditEntity($entity, "close");
$failure = $entity->SetFieldValue("description", "man of steel, tree of maple");
# ignore failure
myValidateCommit( $entity );
$entity = "";
print "Reload, show final values";
$entity = $session->GetEntityByDbId("defect", $id);
DumpFields($entity);
$entity = "";
print "Test of stateful entities is done";
}