nginstack

Class: ScriptRunner

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

new ScriptRunner(keyOrURI [, 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.

Parameters:
Name Type Argument Description
keyOrURI 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 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.
Example
// 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' });
 scriptRunner.callFunction('test'); // 'is-v8'

 // test.js source
 /*
 class Test {
   get id() {
     return 'is-v8';
   }
 }
 function test() {
   const t = new Test();
   return t.id;
 }
 *\/

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.

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"