nginstack

Class: ScriptRunner

@nginstack/engine/lib/runner/ScriptRunner~ ScriptRunner

new ScriptRunner(fileId [, options])

Esta classe é responsável por criar um ambiente JavaScript isolado do atual, possibilitando a execução de scripts e sua manipulação.

Deve-se observar que os recursos alocados pelo ambiente JavaScript utilizado internamente pelo ScriptRunner podem ser altos e a liberação desses recursos ocorrerá apenas quando esta instância deixar de ser referenciada por outros objetos, momento em que o garbage collector do JavaScript irá destruir o objeto e liberar os recursos associados a ele. Por esse motivo, devem ser evitadas referências às instâncias desta classe quando elas não estiverem mais em uso. A liberação imediata dos recursos também pode ser solicitada por meio do método #dispose, sendo recomendado o seu uso em um bloco try..finally.

Parameters:
Name Type Argument Description
fileId string | number

URI ou chave do script que se será executado.
options Object <optional>

Opções do ambiente a ser criado.

Properties
Name Type Argument Description
runtime string <optional>

Indica o runtime JavaScript que deve ser utilizado para executar o script informado, podendo ser informado 'ije' ou 'v8'. Caso não seja informado, será utilizado o runtime padrão do sistema, atualmente o 'ije'. Quando for informado um realm, o tipo do ambiente será obtido a partir da configuração do realm, não podendo ser modificado por este parâmetro.
realm string <optional>

Indica que a sessão JavaScript que será utilizada para executar o script deve ser obtida do pool de sessões stateless ou stateful indicado pelo realm. Deve-se observar que quando um pool é utilizado, o ambiente JavaScript manterá o estado das execuções anteriores. Também é importante que o método #dispose seja utilizado tão logo o uso da instância seja concluído para que o ambiente JavaScript seja devolvido ao pool, permitindo o seu reuso por outras instâncias.
sessionId string <optional>

Identificador único da sessão JavaScript que será utilizada para executar o script. Esta propriedade somente deve ser utilizada para recuperar sessões criadas previamente em um realm do tipo 'stateful'. Caso ela não seja informada, será criada uma nova sessão cujo identificador pode ser obtido pela propriedade #sessionId. Será gerado um erro caso não exista mais uma sessão com o identificador informado. A opção realm passa a ser opcional quando sessionId é informado, pois o realm informado na construção da sessão é preservado. Caso o realm também seja informado, ele deverá ter o mesmo valor informado na construção do ScriptRunner que criou esta sessão.
waitTimeout number <optional>

Tempo máximo de espera em milissegundos para que uma sessão stateful em uso conclua a sua execução e possa ser utilizada para executar o script informado. Caso não seja informado, será gerado um erro imediatamente no caso da sessão informada estar em uso. Esta opção é utilizada apenas quando o sessionId é informado.
Examples
// Executa um código JavaScript compatível apenas com o runtime V8
 const ScriptRunner = require('@nginstack/engine/lib/runner/ScriptRunner');

 const scriptRunner = new ScriptRunner('test.js', { runtime: 'v8' });
 try {
   scriptRunner.callFunction('test'); // 'is-v8'
 } finally {
   scriptRunner.dispose();
 }

 // test.js source
 /*
 class Test {
   get id() {
     return 'is-v8';
   }
 }
 function test() {
   const t = new Test();
   return t.id;
 }
 *\/
// Executa um código JavaScript compatível apenas com o runtime V8
 const ScriptRunner = require('@nginstack/engine/lib/runner/ScriptRunner');

 const scriptRunner = new ScriptRunner('test.js');
 try {
   scriptRunner.callFunction('test'); // 'is-v8'
 } finally {
   scriptRunner.dispose();
 }

 // test.js source
 /*
 class Test {
   get id() {
     return 'is-v8';
   }
 }
 function test() {
   const t = new Test();
   return t.id;
 }
 *\/
// Restaura uma sessão stateful a partir do seu id
 const ScriptRunner = require('@nginstack/engine/lib/runner/ScriptRunner');
 const sid = request.sid;
 const scriptRunner = new ScriptRunner('test.js', {
   sessionId: sid,
   waitTimeout: 60000
 });
 try {
   const data = scriptRunner.callFunction('test');
   response.contentType = 'application/json';
   response.write(JSON.stringify({
      success: true,
      data: data,
      sid: scriptRunner.sessionId
   }));
 } finally {
   scriptRunner.dispose();
 }

Members

sessionId :string

Identificador único da sessão JavaScript criada ou adquirida pelo ScriptRunner para executar o script informado.

Type:
  • string

trackingId :string

Identificador de rastreio da sessão JavaScript criada ou adquirida pelo ScriptRunner para executar o script informado.

Mais detalhes em Session.trackingId.

Type:
  • string
See:

Methods

applyFunction(functionName [, args])

Executa uma função global declarada pelo script. O script será completamente executado ao menos uma vez para a identificação das funções globais definidas.

Parameters:
Name Type Argument Description
functionName string

Nome da função que será executada.
args Array <optional>

Parâmetros para a função que será invocada.
See:
Returns:

O valor retornado pela função.
Importante: apenas valores primitivos e DataSets podem ser retornados.

Type
DataSet | number | Date | string | boolean
Example
// Considerando que o script "echo" tenha esse código
  function doEcho(value) {
    const result = value ? value : "none";
    return result;
  }

  // Temos que:
  const ScriptRunner = require('@nginstack/engine/lib/runner/ScriptRunner');
  const scriptRunner = new ScriptRunner(-1898145715); // echo
  scriptRunner.loginBySession(session);
  scriptRunner.applyFunction('doEcho', []); // retorna "none"
  scriptRunner.publishGlobalProperty('value', 'opa');
  scriptRunner.applyFunction('doEcho', []); // retorna "none"
  scriptRunner.applyFunction('doEcho', ['opa']); // retorna "opa"

callFunction(functionName [, params])

Executa uma função global declarada pelo script. O script será completamente executado ao menos uma vez para a identificação das funções globais definidas. A diferença para o applyFunction é que neste método é com uma lista aberta de argumentos, semelhante a diferença entre Function.apply e o Function.call.

Parameters:
Name Type Argument Description
functionName string

Nome da função que deve ser executada.
params Object <optional>
<repeatable>

Objetos passados como parâmetro para a função. Todos os valores passados devem ser capazes de serialização.
Returns:

O valor retornado pela função.
Importante: apenas valores primitivos e DataSets podem ser retornados.

Type
DataSet | number | Date | string | boolean
Example
// Considerando que o script "echo" tenha esse código
  function doEcho(value) {
    const result = value ? value : "none";
    return result;
  }

  // Temos que:
  const ScriptRunner = require('@nginstack/engine/lib/runner/ScriptRunner');
  const scriptRunner = new ScriptRunner(-1898145715); // echo
  scriptRunner.loginBySession(session);
  scriptRunner.callFunction('doEcho'); // retorna "none"
  scriptRunner.publishGlobalProperty('value', 'opa');
  scriptRunner.callFunction('doEcho'); // retorna "none"
  scriptRunner.callFunction('doEcho', 'opa'); // retorna "opa"

clear()

Limpa todas as propriedades do ambiente JavaScript incluindo as propriedades publicadas via publishGlobalProperty.

dispose()

Libera imediatamente os recursos associados a este objeto.

evaluate(expression)

Executa uma expressão JavaScript no contexto global da sessão, permitindo a manipulação ou inspeção do ambiente. Será retornado o resultado da expressão informada.

Parameters:
Name Type Description
expression string

Expressão que serpa executada.
Returns:

O valor retornado pela expressão.

Type
DataSet | number | Date | string | boolean
Example
// Considerando que o script "echo" tenha esse código
  function doEcho(value) {
    const result = value ? value : "none";
    return result;
  }

  // Temos que:
  const ScriptRunner = require('@nginstack/engine/lib/runner/ScriptRunner');
  const scriptRunner = new ScriptRunner(-1898145715); // echo
  scriptRunner.loginBySession(session);
  scriptRunner.callFunction('doEcho', 'ops'); // retorna "ops"
  scriptRunner.evaluate('function doEcho() { return 'ok'; }');
  scriptRunner.callFunction('doEcho', 'ops'); // retorna "ok"

login(userName, password)

Efetua login na sessão utilizando um nome de usuário e senha. Por padrão, o ambiente recém criado será executado em nome do usuário Anonymous.

Parameters:
Name Type Description
userName string

Nome do usuário que será logado.
password string

Senha do usuário que será logado.
See:
Returns:

Indica se o login foi executado com sucesso.

Type
boolean

loginByAuthToken(id)

Efetua login no ambiente gerado por este ScriptRunner utilizando um "ID" obtido através de um objeto ngin.security.AuthToken criado anteriormente. Este token precisa ser autorizado utilizando o método Session#authorizeToken ou Security#authorizeToken para que seja válido e também para que se obtenha o "ID".

Parameters:
Name Type Description
id string

"ID" do token gerado através do método Session#authorizeToken ou Security#authorizeToken.
See:

loginBySession(session)

Efetua login utilizando o usuário da sessão informada. Este método é útil para executar o novo ambiente com o mesmo usuário da sessão corrente.

Parameters:
Name Type Description
session Session

Sessão cujo usuário corrente será utilizado para realizar o login neste ambiente.
See:
Example
// O código abaixo é equivalente à um executeScript(key)
  var scriptRunner = new ScriptRunner(key);
  scriptRunner.loginBySession(session);
  scriptRunner.run();

publishGlobalProperty(name, value)

Cria no ambiente de execução do script a variável global passada.
Importante: apenas valores primitivos e DataSets podem ser usados.

Parameters:
Name Type Description
name string

Nome da variável.
value DataSet | Number | Date | String | Boolean

Valor da variável.
See:

readGlobalProperty(name)

Retorna do ambiente de execução do script o valor de uma variável global anteriormente publicada ou definida pelo script.
Importante: apenas valores primitivos e DataSets podem ser usados.

Parameters:
Name Type Description
name string

Nome da variável.
See:
Returns:

Valor da variável.

Type
DataSet | Number | Date | String | Boolean

run()

Roda o script utilizando o login previamente realizado, ou anonimamente caso nenhum método de login tenha sido executado. Essa função roda o script informado no construtor e retorna o último valor deixado na pilha do script.

Importante: apenas valores primitivos e DataSets podem ser retornados.

Returns:

Último valor deixado na pilha do script.

Type
Object
Example
// Considerando que o script "echo" tenha esse código
  const value;
  const result = value ? value : "none";
  result;

  // Temos que:
  const ScriptRunner = require('@nginstack/engine/lib/runner/ScriptRunner');
  const scriptRunner = new ScriptRunner(-1898145715); // echo
  scriptRunner.loginBySession(session);
  scriptRunner.run(); // retorna "none"
  scriptRunner.publishGlobalProperty('value', 'opa');
  scriptRunner.run(); // retorna "opa"