new Entity(classKey, dataSet [, opt_options])
Classe utilizada para manipular registros das classes de dados do sistema, declaradas por meio de arquivos x-model. O seu uso é recomendado em vez da manipulação direta via dataSets, pois as regras de negócio declaradas no x-model, por meio de eventos e definições de campos, são respeitadas com base nas permissões do usuário corrente da sessão ou do usuário indicado nas opções do construtor.
Não é recomendado utilizar diretamente o construtor Entity, prefira:
- Entity.fromKey: para consultar ou alterar registros que façam parte do cache local;
- Entity.fromDataSet: para consultar ou alterar registros de APIs existentes que hoje expõem DataSets como interface de dados, como os objetos de gestão;
- EntitySet.newEntity: para construir uma nova entidade de uma determinada classe de dados;
- EntitySet.findByKey: para consultar ou alterar entidades de uma determinada coleção previamente criada.
Parameters:
Name | Type | Argument | Description |
---|---|---|---|
classKey |
number | Classe de dados da entidade. |
|
dataSet |
DataSet | DataSet que contém os dados da entidade. Enquanto a entidade criada existir, o DataSet informado não poderá ter a sua posição alterada. A mudança da posição do DataSet impedirá o uso da entidade criada. A entidade criada terá a propriedade Entity#autoPersist com o mesmo valor da propriedade DataSet#automaticApplyUpdates do DataSet informado. |
|
opt_options |
EntityOptions | Record.<*, *> |
<optional> |
Opções da entidade a ser criada. |
- See:
-
- EntitySet
- Key
- KeySet
Throws:
-
Será gerado um erro caso a chave informada em opt_options.keynão exista ou se o usuário não tiver permissão de visão para a classe desta entidade.
- Type
- EntityError
Members
-
<static> requiresStrictMode :boolean
-
Indica que a classe module:@nginstack/orm/lib/Entity somente modificará registros nas classes de dados que estiverem como o modo estrito habilitado.
Type:
- boolean
-
autoPersist :boolean
-
Indica se os dados serão persistidos automaticamente no banco de dados quando for executado o método #post.
Type:
- boolean
- See:
-
classKey :number
-
Chave da classe de dados desta entidade.
Type:
- number
Example
const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); currentUser.classKey.nome // => Usuários
-
key :number
-
Chave que identifica unicamente esta entidade no banco de dados.
Type:
- number
Example
const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); currentUser.key === session.userKey // => true
-
postPending :boolean
-
Indica que uma entidade recém criada ou alterações realizadas em uma entidade existente não foram efetivadas pelo método #post.
Type:
- boolean
- See:
-
state :EntityState
-
Indica qual é o estado de modificação desta entidade. Valores possíveis:
- EntityState.UNCHANGED: A entidade não foi modificada desde a sua criação ou da última execução do método Entity#persist.
- EntityState.ADDED: uma nova entidade foi criada, mas as alterações ainda não foram persistidas no banco de dados.
- EntityState.MODIFIED: a entidade foi modificada, mas as alterações ainda não foram persistidas no banco de dados.
- EntityState.DELETED: a entidade foi excluída, mas as alterações ainda não foram persistidas no banco de dados.
- EntityState.DETACHED: indica que uma instância de Entity não faz mais parte de um EntitySet, nem representa uma entidade do banco de dados. Normalmente, uma entidade fica nesse estado após a exclusão de uma entidade ter sido persistida no banco de dados ou quando o dataSet informado para a Entidade teve a sua posição modificada.
Type:
- EntityState
Example
const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); assert.equal(currentUser.state, EntityState.UNCHANGED); currentUser.set('ismtpusername', 'user@server.com'); assert.equal(currentUser.state, EntityState.MODIFIED); currentUser.post(); assert.equal(currentUser.state, EntityState.UNCHANGED);
Methods
-
<static> fromDataSet(classKey, dataSet [, opt_options])
-
Cria uma entidade para manipular o registro corrente do dataSet.
A entidade criada terá a propriedade Entity#autoPersist com o mesmo valor da propriedade DataSet#automaticApplyUpdates do DataSet informado.
Parameters:
Name Type Argument Description classKey
number Classe de dados da entidade que será manipulada.
dataSet
DataSet DataSet que contém a entidade que deverá ser manipulada pela Entidade a ser criada.
opt_options
Object | Record.<*, *> <optional>
Opções disponíveis:
- userKey: usuário que será utilizado para validar as permissões. Mais detalhes em EntityOptions#userKey;
- fields: campos da definição da classe que devem ser manipulados por essa entidade. Mais detalhes em EntityOptions#fields;
- modelDef: definição do modelo de dados que deve ser utilizada. Por padrão, a definição do modelo de dados utilizada é a da informada. No entanto, em alguns cenários de uso é necessário retirar ou complementar comportamentos do modelo. O uso desta opção não é recomendada, pois ela desabilita a capacidade da entidade ajustar dinamicamente as regras de modelo quando a classe é alterada. Mais detalhes em EntityOptions#modelDef.
Returns:
Entidade contida na posição corrente do DataSet.
- Type
- Entity
Example
const users = Entity.fromDataSet(ClassKeys.USERS, ds); users.toJSONString();
-
<static> fromKey(key [, opt_options])
-
Cria uma entidade para manipular o registro indicado pela chave key. Esta função somente poder ser utilizada com registros que façam parte do cache local do Engine, como os cadastros do sistema.
Por padrão, a entidade criada terá a propriedade Entity#autoPersist ativa.
Parameters:
Name Type Argument Description key
number Chave da entidade a ser criada.
opt_options
Object | Record.<*, *> <optional>
Opções disponíveis:
- userKey: usuário que será utilizado para validar as permissões. Mais detalhes em EntityOptions#userKey;
- fields: campos da definição da classe que devem ser manipulados por essa entidade. Mais detalhes em EntityOptions#fields;
- modelDef: definição do modelo de dados que deve ser utilizada. Por padrão, a definição do modelo de dados utilizada é a da classe da chave informada. No entanto, em alguns cenários de uso é necessário retirar ou complementar comportamentos do modelo. O uso desta opção não é recomendada, pois ela desabilita a capacidade da entidade ajustar dinamicamente as regras de modelo quando a classe é alterada. Mais detalhes em EntityOptions#modelDef.
Throws:
-
Será gerado um erro caso a chave informada não exista ou se o usuário corrente não tiver permissão de visão para a classe desta entidade.
- Type
- EntityError
Returns:
Entidade associada à chave informada.
- Type
- Entity
Example
var entity = Entity.fromKey(ngin.keys.Users.ANONYMOUS); entity.toJSONString();
-
assign(values)
-
Serão atribuídas as propriedades do objeto informado. As propriedades existentes no objeto informado que não existem neste serão ignoradas. Propriedades existentes em obj que o usuário não tem poder de edição irá produzir um erro apenas se o valor existente em obj for diferente do existente na entidade.
Parameters:
Name Type Description values
Object.<string, *> Mapa de propriedades a serem atribuídas à entidade.
-
bindDataSet(dataSet)
-
Informa um novo DataSet onde os dados da entidade serão persistidos. O DataSet informado deve ter a mesma estrutura do dataSet informado no construtor, ou seja, deve ter os mesmos campos, com os mesmos tipos, na mesma ordem.
Parameters:
Name Type Description dataSet
DataSet DataSet que será utilizado para gravar os dados da entidade.
Example
var entity = Entity.fromKey(ngin.keys.Classes.GROUPS); var ds = classes.getCachedDataSet(ngin.keys.Classes.GROUPS); entitySet.bindDataSet(ds);
-
cancel()
-
Cancela a edição corrente ou criação da entidade. Após a execução dos métodos #post e #persist não será possível cancelar a edição corrente.
Example
const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); currentUser.edit(); try { doStrangeThingsWith(currentUser); } catch (e) { currentUser.cancel(); throw e; }
-
clone()
-
Obtém entidade clone a partir da entidade original.
Returns:
Entidade clone.
- Type
- Entity
Example
var clone = new Entity(chaveDaClasse, {key: chaveDoRegistro}).clone();
-
delete()
-
Exclui esta entidade. Após a execução deste método, a entidade estará com estado DELETED ou DETACHED (caso autoPersist esteja ativo) e não poderá ser mais modificada.
Example
const Entity = require('@nginstack/orm/lib/Entity'); const user = Entity.fromKey(userToRemove); currentUser.delete();
-
edit()
-
Inicia a edição da entidade. Esse método é executado automaticamente ao tentar alterar o valor da entidade por meio do método #set. Ele deve ser utilizado apenas quando deseja-se rodar os eventos de edição programaticamente.
Example
const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); assert.equal(currentUser.state, EntityState.UNCHANGED); currentUser.edit(); assert.equal(currentUser.state, EntityState.MODIFIED);
-
get()
-
Obtém o valor de uma propriedade da entidade. Tentar acessar uma propriedade que não existe ou que o usuário não tenha visão produzirá um erro.
Returns:
Valor da propriedade.
- Type
- *
Example
const Groups = require('@nginstack/engine/keys/Groups'); const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); // Retorna true, se o usuário estiver associado diretamente o grupo Administrators currentUser.get('igroups').includes(Groups.ADMINISTRATORS);
-
persist()
-
Persiste as modificações realizadas neste entidade no banco de dados. Caso a entidade esteja em edição ou inserção, será executado o método #post antes da persistência dos dados.
- See:
Returns:
Versão das alterações no banco de dados.
- Type
- number
Example
const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); try { doGoodThingsWith(currentUser); } finally { currentUser.persist(); }
-
post()
-
Efetiva a edição ou criação da entidade localmente no dataSet. Caso #autoPersist esteja habilitado, as alterações serão persistidas pelo método #persist automaticamente, em conjunto com o post. Caso não esteja, as alterações serão efetivadas no DataSet informado ao construtor, mas não serão persistidas no banco de dados. Neste caso, o método #persist deve ser executado posteriormente para que as alterações sejam gravadas no banco de dados.
Caso as alterações devam ser gravadas no banco de dados, prefira utilizar diretamente o método #persist. O método persist efetiva as alterações pendentes via post, antes de gravar as alterações no banco de dados.
- See:
Example
const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); try { doGoodThingsWith(currentUser); } finally { currentUser.post(); }
-
set(name, value)
-
Atualiza uma propriedade desta entidade. Tentar alterar uma propriedade que não existe ou que o usuário não tenha poder de alterar produzirá um erro.
Parameters:
Name Type Description name
string Nome da propriedade.
value
* Valor da propriedade.
Example
const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); currentUser.set('ismtpusername', 'user@server.com'); currentUser.post();
-
toJSONSchema()
-
Exporta a definição desta classe no formato JSON Schema.
Returns:
- Type
- Object
-
toJSONString()
-
Cria uma representação JSON desta entidade. Serão exportadas apenas as propriedades visíveis pelo usuário.
Returns:
JSON com os campos visíveis para o usuário.
- Type
- string
Example
const Entity = require('@nginstack/orm/lib/Entity'); const currentUser = Entity.fromKey(session.userKey); currentUser.toJSONString()