dataClass.fromCollection( )

4D v19.8


dataClass.fromCollection ( colObj {; settings} ) -> Resultado

Parâmetro	Tipo	Descrição
colObj	Collection	Coleção de objetos a ser mapeado com entidades
settings	Objeto	Opção de construção: contexto
Resultado	EntitySelection	Seleção de entidades preenchida a partir da coleção

Descrição

O método dataClass.fromCollection( ) atualiza ou cria entidades na classe de dados de acordo com a coleção de objetos colObj, e retorna a seleção de entidades correspondente.

No parâmetro colObj, passe uma coleção de objetos para criar novas entidades ou atualizar entidades existentes na classe de dados. Os nomes das propriedades devem ser os mesmos que os nomes de atributos na classe de dados. Se um nome de propriedade não existir na classe de dados, é ignorado. Se um valor de atributo não for definido na coleção, seu valor será null.

O mapeamento entre os objetos da coleção e as entidades é feito nos nomes de atributo e correspondência de tipos (matching types). Se uma propriedade de objeto tiver o mesmo nome que um atributo de entidade, mas seus tipos não forem correspondentes, o atributo de entidade não é preenchido.

Modo Criar ou atualizar
Para cada objeto de colObj:

Se o objeto contiver uma propriedade booleana, "__NEW" é estabelecido para false (ou não contém uma propriedade "__NEW"), então a entidade será atualizada ou criada com os valores correspondentes das propriedades do objeto. Não é feito uma verificação quanto à chave primária:
- Se a chave primária é dada no objeto e existir, a entidade é atualizada
- Se a chave primária for dada no objeto (no estado em que se encontra - "as is") e não existir, a entidade é criada
- Se a chave primária não for dada no objeto, a entidade é criada
  A chave primária pode ser dada tal qual ou com a propriedade __KEY. Se a chave primária não for dada, a entidade é criada e o valor da chave priimária é atribuido com respeito às regras padrão de banco de dados.
Se o objeto contiver uma propriedade booleana "__NEW" estabelecida como true, a entidade será criada com os valores correspondentes dos atributos do objeto. Uma verificação é feita para a chave primaária:
- Se a chave primária for dada no objeto (as is) e existir, um erro é enviado
- Se a chave primária for dada no objeto (as is) e não existir, a entidade é criada
- Se a chave primária não for dada no objeto, a entidade é criada
  
  Nota: A propriedade "__KEY" que contém um valor é levada em consideração apenas quando a propriedade "__NEW" for estabelecida para falso (ou omitida) e uma entidade correspondente existir. Em todos os outros casos, a propriedade "__KEY" é ignorada, e o valor da chave primária deve ser passado "as is".

Entidades Relacionadas
Os objetos de colObj podem conter um ou mais objetos aninhados descrevendo uma ou mais entidades relacionadas, que podem ser úteis para criar ou atualizar links entre entidades
Os objetos aninhados descrevendo entidades relacionadas contém o atributo ___KEY (preenchidos com a chave primária da entidade relacionada) ou a chave primária da entidade relacionadaem si mesma. O uso do atributo __KEY permite independência do nome da chave primária.

Nota: o conteúdo das entidades relacionadas não podem ser criadas/atualizadas através do mecanismo.

Stamp (carimbo)
Se um atributo __STAMP for dado, uma verificação é realizada com a stamp na datastore e um erro pode ser retornado ("Dado que a stamp não corresponda à stamp atual para o record# XX da tabela XXXX").

settings

No parâmetro opcional settings, você pode passar um objeto contendo opções adicionais. A seguinte propriedade é suportada:

Propriedade	Tipo	Descrição
context	Texto	Rótulo para o contexto de otimização aplicado à seleção de entidade. Esse contexto será usado pelo código que manipula a seleção de entidade para que possa se beneficiar da otimização. Esse recurso é projetado para processamento de cliente / servidor ORDA; Para mais informações, consulte a seção Client/server optimization.

Exemplo 1

Para atualizar uma entidade existente, a propriedade __NEW não é dada, e a chave primária de funcionário é dada e existe:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.ID:=668 // Chave primária existente em tabela Employee

 $emp.firstName:="Arthur"

 $emp.lastName:="Martin"

 $emp.employer:=New object("ID";121) //Chave primária existe na classe de dados relacionada  Company

  // Para este empregado, podemos mudar a  Company usando outra Chave primária existente  na classe de dados relacionada Company

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Exemplo 2

Se quisermos atualizar uma entidade existente, a propriedade __NEW não dada, a chave primária de funcionários está com o atributo __KEY e existe:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.__KEY:=1720 //Chave Primária existente em tabela Funcionários - Employees

 $emp.firstName:="John"

 $emp.lastName:="Boorman"

 $emp.employer:=New object("ID";121) //Existing PK in the related dataClass Company

  // Para este funcionário, podemos mudar a Empresa - Company usando outra chave primária existente na classe de dados relacionada Company

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Exemplo 3

Criação simples de uma nova entidade da coleção:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.firstName:="Victor"

 $emp.lastName:="Hugo"

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Exemplo 4

Se quisermos criar uma entidade, a propriedade __NEW é True, e a chave primária de funcionários não é dada:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.firstName:="Mary"

 $emp.lastName:="Smith"

 $emp.employer:=New object("__KEY";121) // Chave primária  existente na classe de dados relacionada Company

 $emp.__NEW:=True

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Exemplo 5

Se quisermos criar uma entidade, a propriedade __NEW é omitida, a chave primária do funcionário é dada e não existe:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.ID:=10000 //Chave primária não existe

 $emp.firstName:="Françoise"

 $emp.lastName:="Sagan"

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Exemplo 6

Neste exemplo, a primeira entidade será criada e salva mas a segunda vai falhar já que ambas usam a mesma chave primária:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$emp2;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.ID:=10001 // Chave primária não existe

 $emp.firstName:="Simone"

 $emp.lastName:="Martin"

 $emp.__NEW:=True

 $empsCollection.push($emp)

 

 $emp2:=New object

 $emp2.ID:=10001 // Mesma chave primária, já existente

 $emp2.firstName:="Marc"

 $emp2.lastName:="Smith"

 $emp2.__NEW:=True

 $empsCollection.push($emp2)

 $employees:=ds.Employee.fromCollection($empsCollection)

  //first entity is created

  //erro de duplicação de chave para a segunda entidade

Ver também

entitySelection.toCollection( )