O método BuildEntity cria um novo objeto Entity com um ID exclusivo para o banco de dados do usuário determinado e inicia uma ação de submissão para o registro. Durante a ação de submissão, o registro está disponível para edição dos valores padrão no objeto Entity.
Se você criou um objeto Entity usando o BuildEntity e ainda não confirmou o objeto para o banco de dados, ele está disponível para edição.
O método BuildEntity cria um novo registro do tipo especificado e inicia uma ação de submissão, o que permite que você inicie a edição do conteúdo do registro. (Não é necessário chamar o EditEntity para tornar o registro editável.) Você pode designar valores aos campos do novo registro usando o método SetFieldValue do objeto Entity retornado. Quanto tiver terminado a atualização do registro, use os métodos Validate e Commit do objeto Entity para validar e confirmar quaisquer alterações feitas no registro, respectivamente. O nome especificado por você no parâmetro entitydef_name deve corresponder também a um tipo de registro adequado no esquema. Para obter uma lista de nomes permitidos para o entitydef_name, use o método GetSubmitEntityDefNames.
$session->BuildEntity(entity_def_name);
# Build Session object... # Create a new "defect" record $entityobj = $sessionobj->BuildEntity("defect");
Depois de chamar o método BuildEntity, você pode chamar os métodos do objeto Entity para configurar valores de campo no registro como descrito nas lições prévias deste tutorial.
Para criar um novo registro:
O exemplo a seguir ilustra como trabalhar com tipos de registro stateful e stateless.
Seu esquema tem registros stateless, como o Project e registros stateful, que podem ser movidos de estado para estado, como o Defect. A API do Rational ClearQuest permite que você obtenha e defina os valores dos campos para ambos os tipos de registros. O seguinte exemplo contém duas sub-rotinas: No_state para registros stateless, e Has_state para registros com estados.
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"; }