Modelo de dados

Conceitos utilizados na definição e utilização do modelo de dados, incluindo classes de dados, hierarquia de classes e arquivos de definição x-model e x-view.

Classes de dados

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:

Hierarquia de classes da tabela ENTIDADE

Os registros de todas essas classes são gravados na tabela ENTIDADE, e o campo de classe indica o tipo de cada um:

Registros da tabela ENTIDADE e as suas classes

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.

Chaves e versões

Chave

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:

  • Chaves negativas: registros do produto, distribuídos com as atualizações do sistema. As chaves negativas são segmentadas em faixas que identificam os produtos do sistema, permitindo que ele seja dividido em módulos ativados e licenciados de acordo com a necessidade de cada cliente.
  • Chaves positivas: registros pertencentes somente à base de dados em que foram criados, como os cadastros e as customizações do cliente. As chaves positivas são geradas a partir das faixas de chaves habilitadas na base de dados.

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 .

Versão

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:

  • Sincronizar o cache local: cada Engine obtém do banco de dados os registros com versão maior que a última versão sincronizada, aplicando apenas as alterações ainda não recebidas.
  • Detectar alterações concorrentes: ao gravar um registro alterado, o sistema compara a versão lida pelo DataSet com a versão gravada no banco de dados. Se o registro tiver sido alterado por outra transação após a leitura, a gravação é abortada com um erro, evitando que uma alteração sobrescreva outra sem que o usuário perceba.

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.

Criação de uma classe

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.

Arquivos de definição

As definições de uma classe são feitas por arquivos JavaScript gravados na própria classe:

  • x-model: define o modelo de dados da classe, como a tabela, os campos e as regras de negócio, independentemente da interface.
  • x-view: define a apresentação dos dados da classe na interface com o usuário, como a visibilidade e a largura dos campos na grade.

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.

Ordem de avaliação

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”.

x-model

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);

x-view

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;
  });
});

x-class

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.


DataSet

Uso da classe DataSet para ler, navegar, alterar, gravar, pesquisar e filtrar registros, com as práticas recomendadas para cada operação.

Cache local

Tabelas do cache local, sincronização com o banco de dados e uso do cache como banco de dados local.

Migração chaves de 64 bits

Procedimentos para migração de bases de dados para o uso de chaves e versões de 64 bits.

Rotinas automáticas de atualização

Scripts de pós-atualização para manipulação de dados após uma atualização do sistema.