La méthode BuildEntity crée un objet Entity avec un ID unique pour la base de données utilisateur indiquée et déclenche une action submit pour l'enregistrement. Pendant l'action submit, l'enregistrement est disponible pour l'édition des valeurs par défaut, dans l'objet Entity.
Si vous avez créé un objet Entity à l'aide de BuildEntity mais que vous ne l'avez pas encore validé dans la base de données, l'objet est disponible pour l'édition.
La méthode BuildEntity crée un enregistrement du type spécifié et déclenche une action submit, qui vous permet de commencer l'édition du contenu de l'enregistrement. (Vous n'avez pas besoin d'appeler EditEntity pour rendre l'enregistrement éditable.) Vous pouvez affecter des valeurs aux zones du nouvel enregistrement à l'aide de la méthode SetFieldValue de l'objet Entity renvoyé. Lorsque vous avez terminé la mise à jour de l'enregistrement, utilisez les méthodes Validate et Commit de l'objet Entity pour valider les modifications apportées à l'enregistrement. Le nom que vous avez spécifié dans le paramètre nom_entitydef doit également correspondre à un type d'enregistrement du schéma. Pour obtenir la liste des noms admis pour nom_entitydef, utilisez la méthode GetSubmitEntityDefNames.
$session->BuildEntity(nom_déf_entité);
# Build Session object... # Create a new "defect" record $entityobj = $sessionobj->BuildEntity("defect");
Après avoir appelé la méthode BuildEntity, vous pouvez appeler les méthodes de l'objet Entity pour définir les valeurs des zones dans l'enregistrement, comme décrit dans la leçon précédente de ce tutoriel.
Pour créer un enregistrement :
L'exemple suivant vous montre comment utiliser les types d'enregistrement avec ou sans état.
Votre schéma contient des enregistrements sans état, tels que Project, et des enregistrements avec état, qui passent d'un état à l'autre, tels que Defect. L'API Rational ClearQuest vous permet d'obtenir et de définir des valeurs pour les zones de n'importe quel type d'enregistrement. L'exemple suivant contient deux sous-routines : No_state pour les enregistrements sans état, et Has_state pour les enregistrements avec état.
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"; }