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:
-
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:
-
- ListenerCompareFunctions
- #duplicationHandling
-
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 emittermodule:@nginstack/engine/lib/event/Emitter~Emitter Emitter que terá os eventos copiados.
opt_typestring <optional>
Tipo do evento a ser copiado. Caso não seja informado, serão copiados os listeners de todos os tipos de evento.
-
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 emittermodule:@nginstack/engine/lib/event/Emitter~Emitter Emitter que terá os eventos copiados.
opt_typestring| 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.
-
badRequest( [content])
-
Cria uma resposta com erro BAD_REQUEST. Opcionalmente, pode ser informado o conteúdo da resposta.
Parameters:
Name Type Argument Description contentObject <optional>
Conteúdo da resposta.
Returns:
-
created( [content])
-
Cria uma resposta com estado CREATED. Opcionalmente, pode ser informado o conteúdo da resposta.
Parameters:
Name Type Argument Description contentObject <optional>
Conteúdo da resposta.
Returns:
-
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 eventmodule:@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 filterFnfunction Função que indicará quais filtros devem ser mantidos neste emitter. Deverá ser retornado true para indicar que o filtro deve ser preservado.
opt_typestring <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.
-
forbidden( [content])
-
Cria uma resposta com erro FORBIDDEN. Opcionalmente, pode ser informado o conteúdo da resposta.
Parameters:
Name Type Argument Description contentObject <optional>
Conteúdo da resposta.
Returns:
-
hasAction(name)
-
Verifica se há uma ação com o nome informado.
Parameters:
Name Type Description namestring 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 typestring| 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 contentObject <optional>
Conteúdo da resposta.
Returns:
-
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 typestring 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_typestring <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:
-
notFound( [content])
-
Cria uma resposta com erro NOT_FOUND. Opcionalmente, pode ser informado o conteúdo da resposta.
Parameters:
Name Type Argument Description contentObject <optional>
Conteúdo da resposta.
Returns:
-
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:
-
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 typestring Tipo do evento que será removido.
listenermodule:@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.
-
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_typestring <optional>
Tipo de evento que deverá ter os listeners removidos.
- Inherited From:
Returns:
Esta instância de Emitter, permitindo encadeamento de chamadas.
-
ok( [content])
-
Cria uma resposta com estado OK. Opcionalmente, pode ser informado o conteúdo da resposta.
Parameters:
Name Type Argument Description contentObject <optional>
Conteúdo da resposta.
Returns:
-
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 typestring Tipo de evento que será registrado.
listenerfunction 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.
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 urlstring Nova URL definitiva do recurso da requisição.
Returns:
-
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 typestring| Array.<string> Tipo do evento a ser registrado. Também pode ser informado um array de tipos.
-
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 typestring Tipo de evento que será registrado.
listenermodule:@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 actionstring Nome da ação a ser executada. Uma ação deverá ser implementada como método do controlador.
parametersArray.<*> Parâmetros que devem ser passados para o método do controlador responsável pela ação.
requestmodule:@nginstack/engine/lib/http/Request~Request Requisição HTTP que está sendo atendida.
responsemodule:@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.
-
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 urlstring Nova URL temporária do recurso da requisição.
Returns:
-
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 urlstring Nova URL temporária do recurso da requisição.
Returns:
-
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
retryAfterdo 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 emthis.badRequest(e).Parameters:
Name Type Argument Description retryAfternumber Segundos que o cliente deve aguardar.
contentObject <optional>
Conteúdo da resposta.
Returns:
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 typestring| Array.<string> Tipo do evento a ser bloqueado. Também pode ser informado um array de tipos.
-
<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 objectObject 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
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
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
beforeActioneafterAction, portanto ele será executado após esses eventos.Type: module:@nginstack/engine/lib/router/ControllerEvent~ControllerEvent
Example
this.on('error', function (evt) { evt.result = RouteResult() .withStatus(Status.OK) .withContent({ error: evt.error.message }); });