< 上一课 | 下一课 >

创建新记录

要创建新记录,请使用 Session 对象的 BuildEntity 方法。

BuildEntity 方法利用针对指定用户数据库的唯一标识创建新的 Entity 对象,并启动针对该记录的提交操作。在提交操作期间,该记录可用于编辑 Entity 对象中的缺省值。

如果您使用 BuildEntity 创建了 Entity 对象,但尚未将其落实到数据库,那么该对象是可编辑的。

BuildEntity 方法会创建指定类型的新记录然后开始提交操作,这使您可以开始编辑记录的内容。(您不需要调用 EditEntity 以使记录为可编辑)。您可以使用所返回 Entity 对象的 SetFieldValue 方法为新记录的字段赋值。完成更新记录后,请分别使用 Entity 对象的 ValidateCommit 方法来验证和落实对记录所做的任何更改。 在 entitydef_name 参数中指定的名称还必须对应于模式中适当的记录类型。要获取 entitydef_name 的合法名称的列表,请使用 GetSubmitEntityDefNames 方法。

BuildEntity 的语法如下:
$session->BuildEntity(entity_def_name); 
  • session - 一个 Session 对象,表示当前的数据库访问会话。
  • entity_def_name - 一个字符串,用于在创建记录时包含用作模板的 EntityDef 对象的名称。
返回值是一个新的 Entity 对象,该对象是由用作模板的指定 EntityDef 对象创建的。
例如:
# Build Session object...

# Create a new "defect" record 
$entityobj = $sessionobj->BuildEntity("defect"); 

调用 BuildEntity 方法后,您可以调用 Entity 对象的方法来设置本教程上一课中所描述记录中的字段值。

要创建新记录:

  1. 通过调用 Session 对象的 GetSubmitEntityDefNames 方法确定您可以创建的记录类型。
  2. 调用 Session 对象的 BuildEntity 方法。
  3. 使用 Entity 对象的方法,为记录中的字段设置值。
  4. 完成编辑记录后,分别调用 Entity 对象的 ValidateCommit 方法来验证该记录,并将您的更改落实到数据库中。

示例

以下示例演示如何处理有状态和无状态记录类型。

您的模式具有无状态记录,如“项目”,以及有状态记录(可从一种状态转变为另一种),如“缺陷”。Rational ClearQuest API 使您能够获取和设置这两种类型记录的字段值。 以下示例包括两个子例程:针对无状态记录的 No_state 和针对有状态记录的 Has_state。

代码示例如下:
  1. 使用 Session 的 BuildEntity 方法来创建 Entity 对象。
  2. 在一个或多个字段中设置值。
  3. 验证和落实实体。
  4. 检索和修改实体。
  5. 还原实体。
这两个子例程中的代码调用未在此处显示的两个外部例程 - DumpFields(将实体字段打印到标准输出)和 myValidateCommit(首先验证更改,验证成功后落实更改,或验证失败后进行还原)。以下是可用于 myValidateCommit 的代码:
 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";
 }
< 上一课 | 下一课 >

反馈