Package com.chilkatsoft.chilkat2

Class Js

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Js
All Implemented Interfaces:
AutoCloseable
public class Js extends ChilkatObject
<section class="js-summary">

Execute sandboxed JavaScript inside an application with controlled access to Chilkat features.

Use Chilkat.Js when an application needs to execute JavaScript internally while retaining control over what the script is allowed to access. By default, scripts run in a closed sandbox with the JavaScript language and standard library available, but without filesystem, network, or Chilkat class access unless the host application explicitly enables those capabilities.

Embedded JavaScript engine

Run JavaScript code from inside the host application without launching an external scripting process.

Sandboxed by default

Start from a restricted execution environment and selectively expose only the capabilities the script should use.

Enable Chilkat classes

Allow scripts to use selected Chilkat classes when the host application wants JavaScript to perform controlled Chilkat operations.

Filesystem restrictions

Optionally restrict filesystem access so scripts can read or write only within approved locations.

Script input and output

Execute JavaScript, pass data through the host-controlled environment, and retrieve results or diagnostics from the script run.

Controlled automation

Use JavaScript as an embedded extension language for application-defined workflows while keeping host resources protected.

Common pattern: Create a Js object, load or provide the JavaScript code, enable only the Chilkat classes and filesystem locations the script is permitted to use, run the script, and inspect the result or diagnostic output. Use Chilkat.Js when the application needs scriptability with a security boundary controlled by the host.

For an extended overview, see Js Class Overview. Also see About the Chilkat.Js JavaScript Engine.

Third-Party Notice This software includes portions of the QuickJS JavaScript engine. Copyright © 2017–2024 Fabrice Bellard. Licensed under the MIT License. The Chilkat Js engine was originally derived from QuickJS, but has been extensively modified.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Js

      public Js()
      Creates a new Js object.

  • Method Details

    • getTimeoutSeconds

      public int getTimeoutSeconds()
      Specify a timeout in seconds to prevent JavaScript from running indefinitely, such as in an infinite loop. By default, the value is 0, meaning no timeout is set and infinite loops will continue forever.
      Returns:
      the value of the TimeoutSeconds property

    • setTimeoutSeconds

      public void setTimeoutSeconds​(int value)
      Sets the TimeoutSeconds property; see getTimeoutSeconds().
      Parameters:
      value - the new value

    • callFunction

      public void callFunction​(JsonObject funcJson, JsonObject resultJson)
      Calls a JavaScript function. The function name and arguments are passed in funcJson. The result is returned in resultJson.
      Parameters:
      funcJson - the funcJson argument (not null)
      resultJson - the resultJson argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • consoleOutputSb

      public void consoleOutputSb​(StringBuilder sb)
      Returns the console output in sb from the last call to eval(StringBuilder, JsonObject) .
      Parameters:
      sb - the sb argument (not null)

    • eval

      public void eval​(StringBuilder jscript, JsonObject resultJson)
      Run jscript as a script. Return output and errors in resultJson.
      Parameters:
      jscript - the jscript argument (not null)
      resultJson - the resultJson argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setCkPermission

      public void setCkPermission​(String chilkatClassName, String permission)
      Sets sandbox related permissions for Chilkat objects. The chilkatClassName is the name of the Chilkat class (case-insensitive), such as Http, Rest, "MailMan", "Ftp2", "Ssh", etc. The chilkatClassName can also be set to "all" to apply the permission to all Chilkat classes.

      Possible values for permission are:

      • disable - Your JavaScript code is not allowed to create an instance of the Chilkat class. A JavaScript exception is thrown when trying to create a Chilkat object of a class that is disabled.
      • sandbox - Objects for the Chilkat class can be instantiated in JavaScript, but they have no read or write access to the local filesystem.
      • readOnly - Objects for the Chilkat class can be instantiated in JavaScript and have read-only access to the local filesystem.
      • writeOnly - Objects for the Chilkat class can be instantiated in JavaScript and have write-only access to the local filesystem.
      • readWrite - Objects for the Chilkat class can be instantiated in JavaScript and have read/write access to the local filesystem.

      By default, all Chilkat classes are disabled. Your application must enable "all" or specific Chilkat classes before calling eval(StringBuilder, JsonObject) or callFunction(JsonObject, JsonObject) .

      Parameters:
      chilkatClassName - the chilkatClassName argument (not null)
      permission - the permission argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener