DataSet
Uso da classe DataSet para ler, navegar, alterar, gravar, pesquisar e filtrar registros, com as práticas recomendadas para cada operação.
Uma classe de dados representa um tipo de registro. O conceito é semelhante ao de classe nas linguagens orientadas a objetos: uma classe define a estrutura e o comportamento dos seus registros, e as suas classes filhas herdam essas definições, podendo especializá-las com novos campos e regras ou modificar as definições herdadas.
| Orientação a objetos | Modelo de dados |
|---|---|
| Classe | Classe de dados |
| Subclasse | Classe filha |
| Herança | Herança das definições dos arquivos x-model e x-view |
| Objeto | Registro |
| Tipo do objeto | Classe do registro, gravada no campo iClass ou CLASSE |
As classes de dados formam uma hierarquia e são gravadas na tabela CLASSE, cujo campo MAE
indica a classe superior de cada classe. Cada registro pertence a uma única classe, indicada pelo
seu campo iClass ou CLASSE.
Diferentemente dos objetos, os registros também precisam ser gravados em uma tabela. A tabela é definida por uma classe e herdada pelas suas classes filhas, de modo que os registros de toda a hierarquia abaixo dessa classe são gravados na mesma tabela e diferenciados pelo campo de classe. Por esse motivo, diz-se que os registros do sistema são gravados em classes de dados: logicamente, um registro pertence a uma classe e, fisicamente, é gravado na tabela definida para ela.
Um exemplo é a tabela ENTIDADE, definida pela classe Entidades. As classes filhas de Entidades
especializam o tipo da entidade, cada uma com os campos e as regras próprios desse tipo. De forma
simplificada, a hierarquia poderia ser representada assim:
Os registros de todas essas classes são gravados na tabela ENTIDADE, e o campo de classe indica
o tipo de cada um:
Assim como um objeto de uma subclasse também é uma instância das classes superiores, um registro da classe Funcionários também é uma pessoa física, uma pessoa e uma entidade. Por isso, as definições e as regras da classe Pessoas também se aplicam aos registros das classes Pessoas físicas, Pessoas jurídicas, Funcionários e Fornecedores.
Cada registro do sistema é identificado por uma chave única em todo o banco de dados: não há dois registros com a mesma chave, mesmo em tabelas diferentes. Por isso, a chave é suficiente para identificar um registro, sem a necessidade de informar a tabela em que ele está gravado. Os campos que referenciam outros registros, como o campo de classe, armazenam apenas a chave do registro referenciado.
A chave é gravada no campo iKey ou, nas tabelas que seguem o padrão antigo de nomes, CHAVE.
O sinal da chave indica a origem do registro:
As chaves dos novos registros são geradas pelo sistema quando a opção de
inserção automática de chaves
do DataSet está ativada, ou manual pelo método database.createKey. As chaves e as versões
atualmente são inteiros de 64 bits, no entanto, o sistema ainda mantém compatibilidade com as
chaves de 32 bits. Mais detalhes no manual
Migração chaves de 64 bits
.
Cada registro também possui um número de versão, gravado no campo iVersion ou, no padrão antigo
de nomes, VERSAO. A cada transação de gravação, o banco de dados fornece um novo número de
versão, maior que os anteriores, que é gravado em todos os registros incluídos ou alterados pela
transação. Assim, a versão de um registro identifica a última transação que o alterou, e os
registros gravados na mesma transação compartilham o mesmo número de versão.
A versão é utilizada pelo sistema para:
Por esses motivos, os DataSets cujas alterações são gravadas no banco de dados devem conter os campos de chave e de versão.
O sistema tem por padrão um conjunto de classes de dados mínimas para o seu funcionamento, mas novas podem ser criadas no processo “Administração do sistema > Classes de dados > Explorador de classes”, na extensão do Engine para o VS Code ou IDE embarcada do Engine.
A nova classe herda as definições da classe superior, inclusive a tabela em que os seus
registros são gravados. Por exemplo, ao criar uma classe filha de Funcionários, os registros
serão gravados na mesma tabela ENTIDADE com todo o comportamento herdado das classes
Funcionários, Pessoas físicas, Pessoas e Entidades. Novas regras podem ser definidas por
meio de arquivos x-model e x-view criados na nova classe.
As definições de uma classe são feitas por arquivos JavaScript gravados na própria classe:
Essa divisão mantém as regras de negócio separadas da interface, permitindo que o modelo seja utilizado tanto pelas grades do Web Framework quanto por APIs, processos e rotinas sem interface.
Uma classe pode ter vários arquivos de definição. Eles são avaliados em ordem lexicográfica e, em
cada um deles, uma configuração pode sobrescrever as definidas pelos arquivos anteriores. Por
exemplo, em uma classe com os arquivos abaixo, as configurações de 0200 Engine.model prevalecem
sobre as de 0150 Engine.model, que, por sua vez, prevalecem sobre as de 0100 Engine.model:
0100 Engine.model
0150 Engine.model
0200 Engine.model
As definições também são herdadas na hierarquia de classes: as definições das classes filhas sobrescrevem as das classes superiores.
Os nomes dos arquivos devem ser iniciados pelo número do intervalo correspondente ao seu tipo:
| Intervalo | Tipo de arquivo |
|---|---|
| 0000 a 0099 | x-config |
| 0100 a 4999 | x-model |
| 5000 a 8999 | x-view |
| 9000 a 9099 | Definições de configuração custom |
| 9100 a 9499 | Definições de modelo custom |
| 9500 a 9999 | Definições de visão custom |
São considerados registros custom, os arquivos com chave positiva ou associados ao produto “Custom”.
Os arquivos x-model são do tipo application/x-model e têm a extensão .model. Eles definem o
esquema da tabela que armazena os registros da classe, seguindo o conceito de mapeamento
objeto-relacional (ORM): a tabela, os campos e as regras de negócio que independem da interface.
Tudo o que diz respeito ao esquema das tabelas do banco de dados deve ser definido somente nos
arquivos x-model.
Em um arquivo x-model, this é uma instância de
ModelDef
,
e os campos criados ou obtidos pelo método this.field são instâncias de
Field
.
A documentação dessas classes descreve todas as propriedades, eventos e métodos disponíveis.
As principais propriedades de uma classe que define uma tabela são:
tableName: nome da tabela que armazena os registros da classe e das suas classes filhas.cachedData: indica se a tabela é replicada no
cache local
.lookupDisplayFieldName: campo que identifica o registro quando ele é referenciado por outra
classe. Apesar do nome, essa propriedade não é apenas visual: as consultas que utilizam as
definições de uma classe A que referencia uma classe B retornam o valor desse campo do
registro da classe B.Recomenda-se utilizar resource strings ($R) na propriedade help dos campos, pois o texto
só é carregado quando necessário, reduzindo o consumo de memória do sistema.
Exemplo de um arquivo x-model:
const DBKey = require('@nginstack/engine/lib/dbkey/DBKey.js');
const LookupType = require('@nginstack/engine/lib/classdef/LookupType.js');
const NetworkUtilities = require('@nginstack/engine/lib/net/NetworkUtilities.js');
// Tabela que armazena os registros da classe Engines e das suas classes filhas
this.tableName = 'iHost';
this.upgradeChangesTableStructure = true;
this.cachedData = true;
this.lookupDisplayFieldName = 'iName';
this.on('lookupDisplay', function (evt) {
evt.displayValue = evt.key ? DBKey.str(evt.key, 'iName') : '';
});
let fld = this.field('iKey', 'int64');
fld.label = 'Chave';
fld.required = true;
fld.readOnly = true;
fld.order = -1000;
fld.help = $R(-1898140920);
fld = this.field('iClass', 'int64');
fld.label = 'Classe';
fld.required = true;
fld.order = 20;
fld.classKey = this.key;
fld.lookupType = LookupType.CLASS;
fld.help = $R(-1898140918);
// Os eventos de validação e de tratamento dos dados pertencem ao modelo
fld = this.field('iIPAddresses', 'string', 100);
fld.label = 'Endereços IP';
fld.required = true;
fld.order = 50;
fld.on('beforeChange', function (evt) {
const value = evt.newValue;
if (value) {
// Os arquivos de definição são executados pelo runtime Ije, que não suporta arrow functions
// nem laços for...of
const addresses = value.split(',');
for (let i = 0; i < addresses.length; i++) {
const address = addresses[i].trim();
if (address !== 'dhcp' && !NetworkUtilities.isIPv4Address(address)) {
throw new Error('O valor "' + address + '" não é um endereço IP válido.');
}
addresses[i] = address;
}
evt.newValue = addresses.join(',');
}
});
fld.help = $R(-1898140912);
fld = this.field('iServices', 'masterdetail');
fld.label = 'Serviços';
fld.order = 500;
fld.classKey = -1898146242; /* Services */
fld.masterFieldNames = 'iKey';
fld.detailFieldNames = 'iServer';
fld.help = $R(-1898140898);
Os arquivos x-view são do tipo application/x-view e têm a extensão .view. Eles definem a
apresentação dos dados na interface com o usuário, como a visibilidade, a largura e a ordem dos
campos na grade, e as regras de exibição, como as definidas pelo evento calculate. Os
arquivos x-view não devem conter regras de negócio, que pertencem ao x-model.
Em um arquivo x-view, this é uma instância de
ViewDef
,
que estende ModelDef com propriedades, eventos e métodos voltados para a construção da
interface. Da mesma forma, os campos são instâncias de
ViewDefField
,
que estende Field. Os campos definidos pelo x-model são obtidos pelo método this.field,
informando apenas o nome do campo.
Exemplo de um arquivo x-view para a mesma classe:
this.lookupTableViewWidth = 20;
let fld = this.field('iKey');
fld.visible = false;
fld = this.field('iClass');
fld.tableViewWidth = 10;
fld = this.field('iIPAddresses');
fld.tableViewWidth = 20;
fld = this.field('iServices');
fld.detailIndexFieldNames = 'iName';
fld.on('defineGrid', function (evt) {
const grid = evt.field.grid;
grid.on('defineFields', function (evt) {
evt.grid.field('iServer').visible = false;
});
});
Os arquivos x-class são do tipo application/x-class e têm a extensão .ic. Eles são a forma
original de definição das classes, anterior à divisão entre x-model e x-view, e reúnem no mesmo
arquivo as regras do modelo de dados e as configurações da interface. Por isso, eles são
avaliados tanto na obtenção do modelo da classe, em que this é uma instância de ModelDef,
quanto na obtenção da visão, em que this é uma instância de ViewDef.
Os arquivos x-class ainda são utilizados em muitas classes do sistema e seguem as mesmas regras de ordem de avaliação e de herança. Contudo, eles não devem ser utilizados em novas definições. As classes que ainda os utilizam devem, sempre que possível, ser revistas e migradas para arquivos x-model e x-view, separando as regras de negócio das configurações de interface.
Uso da classe DataSet para ler, navegar, alterar, gravar, pesquisar e filtrar registros, com as práticas recomendadas para cada operação.
Tabelas do cache local, sincronização com o banco de dados e uso do cache como banco de dados local.
Procedimentos para migração de bases de dados para o uso de chaves e versões de 64 bits.
Scripts de pós-atualização para manipulação de dados após uma atualização do sistema.