< 前へ | 次へ >

新規レコードの作成

新規レコードを作成するには、Session オブジェクトの BuildEntity メソッドを使用します。

BuildEntity メソッドは、指定されたユーザー データベース用に固有の ID を付けた新規の Entity オブジェクトを作成し、レコードに対して登録アクションを開始します。登録アクション中、レコードは、Entity オブジェクトのデフォルト値の編集が可能です。

BuildEntity を使用して Entity オブジェクトを作成済みで、まだデータベースにコミットしていなかった場合、そのオブジェクトは編集可能になっています。

BuildEntity メソッドは、 指定されたタイプの新規レコードを作成し、登録アクションを開始します。これによって、レコード内容の編集を開始できる ようになります。(レコードを編集可能にするために、EditEntity を呼び出す必要はありません。) 新規レコードのフィールドに値を割り当てるには、戻された Entity オブジェクトの SetFieldValue メソッドを使用します。レコードの更新を行った場合は、レコードに行った変更について、Entity オブジェクトの Validate を使用して検証し、Commit メソッドを使用してコミットします。entitydef_name パラメータに指定する名前が、スキーマ内の該当するレコード タイプに対応している必要もあります。 entitydef_name の正当な名前のリストを取得するには、GetSubmitEntityDefNames メソッドを使用します。

BuildEntity の構文は次のとおりです。
$session->BuildEntity(entity_def_name); 
  • session - 現在のデータベース アクセス セッションを表す Session オブジェクト。
  • entity_def_name - レコードを作成する場合にテンプレートとして使用する EntityDef オブジェクトの名前を含む String。
戻り値は、指定の EntityDef オブジェクトを テンプレートとして使用してビルドされた新規 Entity オブジェクトです。
以下に例を示します。
# Build Session object...

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

BuildEntity メソッドを呼び出した後は、 このチュートリアルの前のレッスンで説明されているように、Entity オブジェクトのメソッドを呼び出して、レコードのフィールド値を設定する ことができます。

新規レコードを作成する手順は、 次のとおりです。

  1. Session オブジェクトの GetSubmitEntityDefNames メソッドを呼び出して、作成可能なレコード タイプ を判別します。
  2. Session オブジェクトの BuildEntity メソッドを呼び出します。
  3. Entity オブジェクトのメソッドを使用して、レコード内のフィールドの値を 設定します。
  4. レコードの編集を完了した場合、データベースへの変更内容を Entity オブジェクトの Validate メソッドを呼び出して検証し、Commit メソッドを呼び出してコミットします。

以下の例は、 状態ありと状態なしの両方のレコード タイプを処理する方法を示しています。

スキーマには、 状態なしレコード (プロジェクトなど) と、ある状態から別の状態に移動する状態ありレコード (障害など) が あります。Rational ClearQuest API を使用すると、両種類のレコードのフィールド値を取得および設定できます。以下の例 には 2 つのサブルーチンが含まれています。状態なしレコード用の No_state と、 状態ありレコード用の Has_state です。

コード例は次のとおりです。
  1. Session の BuildEntity メソッドを使用して、Entity オブジェクトを作成します。
  2. 1 つ以上のフィールドに値を設定します。
  3. エンティティを検証およびコミットします。
  4. エンティティを取得および変更します。
  5. エンティティを元に戻します。
これら 2 つのサブルーチンのコードが、ここには示されていない 2 つの外部ルーチン を呼び出します。1 つは DumpFields で、エンティティのフィールドを標準出力に印刷出力します。 もう 1 つは 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";
 }

フィードバック
< 前へ | 次へ >