< Vorherige Lektion | Nächste Lektion >

Neuen Datensatz erstellen

Verwenden Sie zum Erstellen eines neuen Datensatzes die Methode BuildEntity des Sitzungsobjekts.

Die Methode BuildEntity erstellt ein neues Entitätsobjekt mit einer eindeutigen ID für die angegebene Benutzerdatenbank und leitet eine Aktion "Submit" (Übergeben) für den Datensatz ein. Während der Aktion "Submit" steht der Datensatz zur Bearbeitung der Standardwerte im Entitätsobjekt zur Verfügung.

Wenn Sie mit der Methode BuildEntity ein Entitätsobjekt erstellen und es noch nicht in der Datenbank festgeschrieben haben, ist das Objekt editierbar.

Die Methode BuildEntity erstellt einen neuen Datensatz des angegebenen Typs und startet eine Aktion "Submit", die Ihnen ermöglicht, mit dem Bearbeiten des Inhalts des Datensatzes zu beginnen. (Es ist nicht erforderlich, EditEntity aufzurufen, um den Datensatz editierbar zu machen.) Sie können den Feldern des neuen Datensatzes Werte zuordnen, indem Sie die Methode SetFieldValue des zurückgegebenen Entitätsobjekts verwenden. Wenn Sie die Aktualisierung des Datensatzes abgeschlossen haben, verwenden Sie die Methoden Validate bzw. Commit des Entitätsobjekts, um alle Änderungen, die Sie am Datensatz vorgenommen haben, zu validieren bzw. festzuschreiben. Der Name, den Sie im Parameter Name_der_Entitätsdefinition angeben, muss auch einem Satztyp im Schema entsprechen. Rufen Sie mit der Methode GetSubmitEntityDefNames eine Liste gültiger Namen für Name_der_Entitätsdefinition ab.

Die Syntax für BuildEntity lautet wie folgt:
$session->BuildEntity(Name_der_Entitätsdefinition); 
  • session - Das Sitzungsobjekt, das die aktuelle Sitzung für den Datenbankzugriff repräsentiert.
  • Name_der_Entitätsdefinition - Eine Zeichenfolge, die den Namen des EntityDef-Objekts enthält, das beim Erstellen des Datensatzes zu verwenden ist.
Der Rückgabewert ist ein neues Entitätsobjekt, das erstellt wird, indem das benannte EntityDef-Objekt als Schablone verwendet wird.
Beispiel:
# Sitzungsobjekt erstellen...

# Einen neuen Fehlerdatensatz (defect) erstellen
$entityobj = $sessionobj->BuildEntity("defect"); 

Nach dem Aufrufen der Methode BuildEntity können Sie die Methoden des Entitätsobjekts aufrufen, um die Feldwerte im Datensatz wie in der vorherigen Lektion dieses Lernprogramms beschrieben zu definieren.

Gehen Sie wie folgt vor, um einen neuen Datensatz zu erstellen:

  1. Bestimmen Sie, welche Satztypen Sie erstellen können, indem Sie die Methode GetSubmitEntityDefNames des Sitzungsobjekts aufrufen.
  2. Rufen Sie die Methode BuildEntity des Sitzungsobjekts auf.
  3. Verwenden Sie die Methoden des Entitätsobjekts, um Werte für Felder im Datensatz zu definieren.
  4. Wenn Sie mit dem Bearbeiten des Datensatzes fertig sind, validieren Sie ihn, und schreiben Sie Ihre Änderungen in der Datenbank fest. Verwenden Sie dazu die Methode Validate bzw. Commit des Entitätsobjekts.

Beispiel

Das folgende Beispiel veranschaulicht, wie Sie mit statusabhängigen und statusunabhängigen Satztypen arbeiten.

Ihr Schema hat statusunabhängige Datensätze, wie z. B. Project, und statusabhängige Datensätze, z. B. Defect, die von einem Status in den anderen wechseln. Die Rational-ClearQuest-API bietet Ihnen die Möglichkeit, Feldwerte für beide Arten von Datensätzen abzurufen und zu definieren. Das folgende Beispiel enthält zwei Subroutinen: "No_state" für statusunabhängige Datensätze und "Has_state" für statusabhängige Datensätze.

Das Codebeispiel führt folgende Aktionen aus:
  1. Es verwendet die Methode BuildEntity der Sitzung, um ein Entitätsobjekt zu erstellen.
  2. Es definiert die Werte in einem oder mehreren Feldern.
  3. Es validiert die Entität und schreibt sie fest.
  4. Es ruft die Entität ab und modifiziert sie.
  5. Es setzt die Entität zurück.
Der Code in diesen zwei Subroutinen ruft zwei externe Routinen auf, die hier nicht behandelt werden: "DumpFields" gibt die Felder einer Entität in die Standardausgabe aus, "myValidateCommit" validiert zuerst die Änderungen und schreibt die Änderung nach erfolgreicher Validierung fest bzw. setzt sie nach fehlerhafter Validierung zurück. Folgender Code kann für "myValidateCommit" verwendet werden:
 sub myValidateCommit( $entity ){
  $status = $entity->Validate;
  if ( $status ) {
    $entity->Revert;
    # Zur Vereinfachung wird der hier dargestellte Vorgang bei Auftreten eines Fehlers abgebrochen,
    # Sie können in Ihrer Anwendung nach Bedarfslage vorgehen, wenn eine Wiederherstellung möglich ist.
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"); 
   # Folgenden Fehler ignorieren: $failure = $entity->SetFieldValue("name", "initial project name");
   DumpFields($entity); 
   myValidateCommit( $entity ); 
   $entity = ""; 
   print "Reload, show values before modification"; 
   # Beachten Sie, dass die Methode "Entity->Reload" verwendet werden kann, um eine Aktualisierung der Entität in der Datenbank zu erzwingen.
   $entity = $session->GetEntity("project", "initial project name"); 
   DumpFields($entity); 
   print "Modify, then show new values"; 
   $session->EditEntity($entity, "modify"); 

   # Fehler ignorieren
   $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"); 

   # Fehler ignorieren
   $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"; 
} 
Das folgende Beispiel veranschaulicht einen Test für statusabhängige Entitäten:
sub Has_states {
 my($session) = @_;
 my($entity);
 # die statusabhängige Entität
 # Fehlernachricht von Funktionen, die Zeichenfolgen zurückgeben
 my($failure);
 my($id);
 # Kennung der Rational-ClearQuest-Fehlerdatenbank
 print "Test for stateful entities is starting";
 print "submit a stateful entity";
 $entity = $session->BuildEntity("defect");
 # Fehler ignorieren
 $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";
 # Beachten Sie, dass die Methode "Entity->Reload" verwendet werden kann, um eine Aktualisierung der Entität in der Datenbank zu erzwingen.
 $entity = $session->GetEntityByDbId("defect", $id);
 DumpFields($entity);
 print "Modify then show new values";
 $session->EditEntity($entity, "modify"); 

 # Fehler ignorieren
$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");
 # Fehler ignorieren
 $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");
 # Fehler ignorieren
 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");
 # Fehler ignorieren
 myValidateCommit( $entity ); 

 $entity = "";
 print "Reload, show final values";
 $entity = $session->GetEntityByDbId("defect", $id);
 DumpFields($entity);
 $entity = "";
 print "Test of stateful entities is done";
 }
< Vorherige Lektion | Nächste Lektion >

Feedback