Class: Controller

@nginstack/engine/lib/router/Controller~ Controller


new Controller()

Classe base para todos os controladores que utilizem a API de roteamento do Engine.

Extends

Members


duplicationHandling :module:@nginstack/engine/lib/event/DuplicationHandling

Indica como deve ser tratada a tentativa de registrar uma função de listener duplicada neste Emitter. Valores possíveis: DuplicationHandling.IGNORE (padrão), DuplicationHandling.ACCEPT e DuplicationHandling.REMOVE.

Type:
Inherited From:

listenerCompareFunction :function

Indica como devem ser comparados dois listeners para determinar se eles são iguais. Valores possíveis: ListenerCompareFunctions.STRICT e ListenerCompareFunctions.SOURCE. O tratamento do registro de um listener duplicado é determinada pela propriedade #duplicationHandling.

Type:
  • function
Inherited From:
See:

moduleFileName :string

Nome do módulo onde o controlador foi declarado. Utilizado apenas nas mensagens de erro para auxiliar o desenvolvedor a localizar o controlador responsável por uma falha em uma rota.

Type:
  • string

Methods


addListenersFromEmitter(emitter [, opt_type])

Adiciona neste emitter os listeners do emitter informado.

Parameters:
Name Type Argument Description
emitter module:@nginstack/engine/lib/event/Emitter~Emitter

Emitter que terá os eventos copiados.

opt_type string <optional>

Tipo do evento a ser copiado. Caso não seja informado, serão copiados os listeners de todos os tipos de evento.

Inherited From:

assignListeners(emitter [, opt_type])

Torna este emitter uma cópia do emitter informado. Os tipos de eventos registrados nesta instância serão preservados e complementados com os existentes em emitter.

Parameters:
Name Type Argument Description
emitter module:@nginstack/engine/lib/event/Emitter~Emitter

Emitter que terá os eventos copiados.

opt_type string| Array.<string> <optional>

Tipo do evento a ser copiado. Caso não seja informado, serão copiados os listeners de todos os tipos de evento. Também pode ser informado um array de tipo de eventos a sere copiados.

Inherited From:

badRequest( [content])

Cria uma resposta com erro BAD_REQUEST. Opcionalmente, pode ser informado o conteúdo da resposta.

Parameters:
Name Type Argument Description
content Object <optional>

Conteúdo da resposta.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

created( [content])

Cria uma resposta com estado CREATED. Opcionalmente, pode ser informado o conteúdo da resposta.

Parameters:
Name Type Argument Description
content Object <optional>

Conteúdo da resposta.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

emit(event)

Emite o evento informado, executando todas as funções de listeners previamente registradas para o tipo do evento emitido.

Parameters:
Name Type Description
event module:@nginstack/engine/lib/event/Event~Event

Evento a ser emitido.

Inherited From:
Throws:

Erro que dispara caso não exista um tipo registrado para manipulação do evento. Eventos aptos a serem manipulados devem ser registrados com o método #registerEventType.

Type
EventTypeException
Returns:

Retorna a indicação que o evento foi emitido para todos os listeners e não foi solicitado o cancelamento da ação padrão associada ao evento, por meio da execução do método Event#preventDefault. Caso o evento não possa ser cancelado (@link Event#cancelable}), será retornado sempre true.

Type
boolean

filterListeners(filterFn [, opt_type])

Elimina os listeners que não satisfaçam a função de filtro.

Parameters:
Name Type Argument Description
filterFn function

Função que indicará quais filtros devem ser mantidos neste emitter. Deverá ser retornado true para indicar que o filtro deve ser preservado.

opt_type string <optional>

Tipo de evento que terá os listeners filtrados. Caso não seja informado, os listeners de todos os tipos de eventos serão filtrados.

Inherited From:

forbidden( [content])

Cria uma resposta com erro FORBIDDEN. Opcionalmente, pode ser informado o conteúdo da resposta.

Parameters:
Name Type Argument Description
content Object <optional>

Conteúdo da resposta.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

hasAction(name)

Verifica se há uma ação com o nome informado.

Parameters:
Name Type Description
name string

Nome do método a ser validado sua presença.

Returns:

Retorna true caso haja uma ação com o nome informado.

Type
boolean

hasListeners(type)

Verifica se há listeners registrados para o tipo de evento informado.

Parameters:
Name Type Description
type string| Array.<string>

Tipo do evento a ser verificado. Também pode ser informado um array de tipos. Neste caso, será retornado true se houver ao menos um listener registrado para um dos tipos informados.

Inherited From:
Returns:

True se houver listeners registrados para o tipo de evento informado.

Type
boolean

internalServerError( [content])

Cria uma resposta com status de erro INTERNAL_SERVER_ERROR. Opcionalmente, pode ser informado o conteúdo da resposta.

Parameters:
Name Type Argument Description
content Object <optional>

Conteúdo da resposta.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

listenerHandlers(type)

Obtém todas as funções de listeners registradas para o tipo de evento informado. O array retornado é uma cópia dos listeners registrados e sua manipulação não alterará a instância desta classe. Para adicionar ou remover uma nova função de listener, utilize os métodos #on ou #off.

Parameters:
Name Type Description
type string

Tipo de evento ao qual serão obtidos os EventListeners registrados.

Inherited From:
See:
Throws:

Será disparado um erro caso o tipo informado não tenha sido registrado previamente pelo método #registerEventType.

Type
EventTypeException
Returns:

Todas as funções de listeners registradas neste emitter para o tipo informado.

Type
Array.<function(module:@nginstack/engine/lib/event/Event~Event)>

listeners( [opt_type])

Obtém todos os listeners registrados para o tipo de evento informado. O array retornado é uma cópia dos listeners registrados e sua manipulação não alterará a instância desta classe. Para adicionar ou remover uma nova função de listener, utilize os métodos #on ou #off.

Parameters:
Name Type Argument Description
opt_type string <optional>

Tipo de evento ao qual serão obtidos os EventListeners registrados.

Inherited From:
See:
Throws:

Será disparado um erro caso o tipo informado não tenha sido registrado previamente pelo método #registerEventType.

Type
EventTypeException
Returns:

Todos os listeners registrados neste emitter para o tipo informado. Sempre serão retornadas instâncias de Listener, por mais que tenham sido registradas funções de listeners nos métodos #on ou #replaceListeners. Para obter as funções, acesse a propriedade Listener#handler dos elementos retornados ou utilize o método #listenerHandlers para obter a relação de funções. Caso não seja informado, serão retornados todos os listeners.

Type
Array.<module:@nginstack/engine/lib/event/Listener~Listener>

noContent()

Cria uma resposta com estado NO_CONTENT.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

notFound( [content])

Cria uma resposta com erro NOT_FOUND. Opcionalmente, pode ser informado o conteúdo da resposta.

Parameters:
Name Type Argument Description
content Object <optional>

Conteúdo da resposta.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

notModified()

Cria uma resposta com status NOT_MODIFIED (304), indicando que o cache do cliente continua válido em uma requisição com cabeçalhos de verificação de cache.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

off(type, listener)

Remove uma função de listener previamente adicionada por meio do método #on.

Se uma função de listener for removida durante a emissão de um evento, ela será executada por mais que tenha sido removida. Ou seja, a remoção valerá para as emissões seguintes.

Parameters:
Name Type Description
type string

Tipo do evento que será removido.

listener module:@nginstack/engine/lib/event/Listener~Listener| function

Indica a função de listener a ser removida.

Inherited From:
See:
Returns:

Esta instância de Emitter, permitindo encadeamento de chamadas.

Type
module:@nginstack/engine/lib/event/Emitter~Emitter

offAll( [opt_type])

Remove todas as funções de listener associadas ao tipo informado. Caso o tipo não seja informado, serão removidas todas as funções de listeners de todos os tipos de eventos.

Parameters:
Name Type Argument Description
opt_type string <optional>

Tipo de evento que deverá ter os listeners removidos.

Inherited From:
Returns:

Esta instância de Emitter, permitindo encadeamento de chamadas.

Type
module:@nginstack/engine/lib/event/Emitter~Emitter

ok( [content])

Cria uma resposta com estado OK. Opcionalmente, pode ser informado o conteúdo da resposta.

Parameters:
Name Type Argument Description
content Object <optional>

Conteúdo da resposta.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

on(type, listener)

Registra uma função que deverá ser executada quando o evento indicado por type for emitido. Por padrão, a função será adicionada no final da fila de listeners, sendo executada após a execução dessas funções previamente registradas.

Se o listener for adicionado durante a emissão de um evento, ele será desconsiderado nesta emissão e será executado apenas nas emissões seguintes.

O comportamento deste emitter ao tentar registrar uma função de listener mais de uma vez é determinado pela propriedade #duplicationHandling.

Parameters:
Name Type Description
type string

Tipo de evento que será registrado.

listener function

Função que será executada quando ocorrer a emissão do evento.

Inherited From:
See:
Returns:

Esta instância de Emitter, permitindo encadeamento de chamadas.

Type
module:@nginstack/engine/lib/event/Emitter~Emitter
Example
modelDef.on('afterInsert', function (event) {
  event.data.setField('codigo', 'Novo cliente');
}).on('beforePost', function (event) {
  if (event.data.str('codigo').trim() == '') {
    throw new Error('O campo código é obrigatório.');
  }
});

permanentRedirect(url)

Cria uma resposta com status PERMANENT_REDIRECT (308), indicando que o recurso requisitado foi movido definitivamente para a URL informada.

Parameters:
Name Type Description
url string

Nova URL definitiva do recurso da requisição.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

registerEventType(type)

Registra um novo tipo de evento, permitindo que ele possa ser utilizado por esta instância de Emitter. A tentativa de emitir um evento ou listener de um tipo não registrado provocará um erro.

Parameters:
Name Type Description
type string| Array.<string>

Tipo do evento a ser registrado. Também pode ser informado um array de tipos.

Inherited From:

replaceListeners(type, listener)

Registra uma função de listener que irá substituir todos os listeners registrados para o tipo de evento indicado por type. A função informada receberá, além do parâmetro event, um segundo parâmetro que será uma função, que ao ser invocada, emitirá o o evento informado para os listeners que foram substituídos.

O comportamento deste emitter ao tentar registrar uma função de listener mais de uma vez é determinado pela propriedade #duplicationHandling.

Importante: o uso deste método não é recomendado. Ignorar os listeners registrados previamente por outros desenvolvedores é uma má prática de desenvolvimento e pode gerar inconsistências de dados. Seu uso deve ser restrito à compatibilização de eventos antigos que dependem deste comportamento, que antes eram declarados pelo método "set" da antiga API de Eventos do Engine (classe global Event).

Parameters:
Name Type Description
type string

Tipo de evento que será registrado.

listener module:@nginstack/engine/lib/event/Listener~Listener| function

Função que será executada quando ocorrer a emissão do evento.

Inherited From:
See:
Example
this.replaceListeners('beforePost', function (event, emit) {
   event.data.codigo = 'Novo cliente';
   emit(event);
 });

runAction(action, parameters, request, response)

Executa uma ação do controlador com os parâmetros informados. Uma ação da controladora é um método da classe. A diferença entre executar este método e executar diretamente o método do controlador é que os eventos beforeAction e afterAction são emitidos.

Parameters:
Name Type Description
action string

Nome da ação a ser executada. Uma ação deverá ser implementada como método do controlador.

parameters Array.<*>

Parâmetros que devem ser passados para o método do controlador responsável pela ação.

request module:@nginstack/engine/lib/http/Request~Request

Requisição HTTP que está sendo atendida.

response module:@nginstack/engine/lib/http/Response~Response

Resposta da requisição HTTP que está sendo gerada.

Returns:

Resultado da ação ou o erro que ocorreu durante a sua execução.

Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

seeOther(url)

Cria uma resposta com status SEE OTHER (303), indicando que o recurso da requisição foi temporariamente alterado para a URL informada e ela deve ser acessada com o método GET.

Parameters:
Name Type Description
url string

Nova URL temporária do recurso da requisição.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

temporaryRedirect(url)

Cria uma resposta com status TEMPORARY_REDIRECT (307), indicando que o recurso da requisição foi temporariamente alterado para a URL informada.

Parameters:
Name Type Description
url string

Nova URL temporária do recurso da requisição.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult

tooManyRequests(retryAfter [, content])

Cria uma resposta com erro TOO_MANY_REQUESTS (429), indicando que o cliente deve aguardar antes de realizar uma nova requisição. O tempo de espera é informado pelo cabeçalho "Retry-After".

Os erros com nome "TooManyRequestsError" lançados pelas rotas e não tratados geram essa mesma resposta, com o tempo de espera informado pela propriedade retryAfter do erro. Os erros com nome "ThrottledError", gerados pela limitação das tentativas de acesso, sempre geram essa resposta, mesmo quando a rota os devolve com outro status, como em this.badRequest(e).

Parameters:
Name Type Argument Description
retryAfter number

Segundos que o cliente deve aguardar.

content Object <optional>

Conteúdo da resposta.

Returns:
Type
module:@nginstack/engine/lib/router/RouteResult~RouteResult
Example
if (requestsInLastMinute > 100) {
  return this.tooManyRequests(60, new Error('Limite de requisições por minuto excedido.'));
}

unregisterEventType(type)

Remove o registro de um tipo de evento, bloqueando a utilização nesta instância de Emitter. A tentativa de emitir um evento ou listener de um tipo não registrado provocará um erro.

Parameters:
Name Type Description
type string| Array.<string>

Tipo do evento a ser bloqueado. Também pode ser informado um array de tipos.

Inherited From:

<static> wrap(object)

Cria um controlador que encapsula o objeto informado. Todas as ações do controlador serão delegadas para o objeto informado e deverão ser criadas como métodos dele.

Parameters:
Name Type Description
object Object

Objeto que será encapsulado pelo controlador.

Events


afterEvent

Evento emitido após a execução do método associado à ação de uma rota HTTP, mesmo que tenha ocorrido um erro durante a sua execução.

O seu uso é recomendado para fins de geração de logs ou para padronizar os resultados em um formato específico esperado pelo cliente da API HTTP.

Type: module:@nginstack/engine/lib/router/ControllerEvent~ControllerEvent
See:
Example
this.on('afterAction', function (evt) {
   const original = evt.result;
   evt.result = RouteResult()
     .withStatus(Status.OK)
     .withContent({
       success: !evt.error
       data: JSON.stringify(original.content)
     });
 });

beforeAction

Evento emitido antes da execução do método associado à ação de uma rota HTTP.

O seu uso é recomendado para tratamentos ou validações que devem ocorrer para todas as rotas de uma API, ou para implementar um mecanismo de autorização customizado alternativo ao modelo de autorização padrão do sistema.

Type: module:@nginstack/engine/lib/router/ControllerEvent~ControllerEvent
See:
Example
this.on('beforeAction', function (evt) {
   if (session.userKey == -1) {
     customAuthorization(evt.request.headers['x-user-token']);
   }
 });

error

Evento emitido se ocorrer um erro durante a execução do método associado à ação de uma rota HTTP.

O seu uso é recomendado para geração de logs ou para a geração de erros em um formato diferente do padrão do roteador HTTP, o qual expõe as propriedades do erro como propriedades de um objeto literal.

Observação: este evento irá capturar erros gerados nos eventos beforeAction e afterAction, portanto ele será executado após esses eventos.

Type: module:@nginstack/engine/lib/router/ControllerEvent~ControllerEvent
See:
Example
this.on('error', function (evt) {
   evt.result = RouteResult()
     .withStatus(Status.OK)
     .withContent({
       error: evt.error.message
     });
 });