< Anterior | Próximo >

Criando um novo registro

Para criar um novo registro, use o método BuildEntity do objeto Session.

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.

Sintaxe para o BuildEntity:
$session->BuildEntity(entity_def_name); 
  • session - O objeto Session que representa a sessão atual de acesso ao banco de dados.
  • entity_def_name - Uma cadeia que contém o nome do objeto EntityDef para usar como modelo ao criar o registro.
O valor de retorno é um novo objeto Entity que é construído usando o objeto EntityDef nomeado como um modelo.
Exemplo:
# 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:

  1. Determine quais tipos de registro que podem ser criados chamando o método GetSubmitEntityDefNames do objeto Session.
  2. Chame o método BuildEntity do objeto Session.
  3. Use os métodos do objeto Entity para configurar valores para os campos no registro.
  4. Quando tiver terminado a edição do registro, valide e confirme suas alterações no banco de dados chamando os métodos Validate e Commit, do objeto respectivamente.

Exemplo

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.

Exemplo de código:
  1. Usa o método BuildEntity da sessão para criar um Objeto Entity.
  2. Configura os valores em um ou mais campos.
  3. Valida e confirma a entidade.
  4. Recupera e modifica a entidade.
  5. Reverte a entidade.
O código nessas duas sub-rotinas chama duas rotinas externas que não são mostradas aqui - DumpFields, que imprimi os campos de uma entidade para a saída padrão e myValidateCommit, que primeiro valida as alterações e confirma o sucesso da seguinte validação ou reverte a falha da validação. Aqui está o código que pode ser usado para 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";
} 
O exemplo seguinte é um exemplo de teste para entidades stateful:
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";
 }
< Anterior | Próximo >

Feedback