Package com.valhalla.sdk

Interface ScriptContext

public interface ScriptContext
Runtime context supplied to each script lifecycle callback.

The context exposes launch settings, permission checks, and script-scoped logging. A permission in the package manifest authorizes an operation; it does not guarantee that the active client adapter advertises the corresponding capability. Use Client.supports(...) before optional native features.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    debug(String message)
    Logs a debug message.
    default void
    error(String message)
    Logs an error message.
    default boolean
    getBooleanSetting(String name, boolean fallback)
    Reads common boolean spellings such as true, yes, and 1.
    default double
    getDoubleSetting(String name, double fallback)
    Reads a finite floating-point setting.
    default <E extends Enum<E>>
    E
    getEnumSetting(String name, Class<E> type, E fallback)
    Reads an enum constant case-insensitively, treating spaces and hyphens as underscores.
    default List<Integer>
    getIntListSetting(String name)
    Reads a comma-separated list while silently omitting malformed integers.
    default int
    getIntSetting(String name, int fallback)
    Reads a base-10 integer setting without propagating parse errors.
    default int
    getIntSetting(String name, int fallback, int minimum, int maximum)
    Reads and clamps an integer setting to an inclusive range.
    default List<String>
    getListSetting(String name)
    Reads a comma-separated setting as trimmed, non-empty strings.
    default long
    getLongSetting(String name, long fallback)
    Reads a base-10 long setting without propagating parse errors.
    String
    getScriptId()
    Returns the stable package identifier from manifest.json.
    default String
    getSetting(String name, String fallback)
    Returns a launch-time script setting supplied by the Command Center.
    boolean
    hasPermission(String permission)
    Tests whether the installed package was granted a manifest permission.
    default void
    info(String message)
    Logs an informational message.
    void
    log(String level, String message)
    Publishes a script-scoped log entry.
    default void
    requirePermission(String permission)
    Requires a package permission before continuing.
    default void
    warn(String message)
    Logs a warning message.

  • Method Details

    • getScriptId

      String getScriptId()
      Returns the stable package identifier from manifest.json.
      Returns:
      script identifier used to prefix logs and runtime state

    • log

      void log(String level, String message)
      Publishes a script-scoped log entry.
      Parameters:
      level - severity label such as DEBUG, INFO, or ERROR
      message - human-readable message; avoid credentials and other secrets

    • hasPermission

      boolean hasPermission(String permission)
      Tests whether the installed package was granted a manifest permission.
      Parameters:
      permission - permission string, preferably from Permissions
      Returns:
      true when the package grants the permission

    • getSetting

      default String getSetting(String name, String fallback)
      Returns a launch-time script setting supplied by the Command Center.
      Parameters:
      name - setting key declared in the package manifest
      fallback - value returned when the key is absent
      Returns:
      configured string value, or fallback when absent

    • getIntSetting

      default int getIntSetting(String name, int fallback)
      Reads a base-10 integer setting without propagating parse errors.
      Parameters:
      name - setting key
      fallback - value used for missing or malformed input
      Returns:
      parsed value or fallback

    • getIntSetting

      default int getIntSetting(String name, int fallback, int minimum, int maximum)
      Reads and clamps an integer setting to an inclusive range.
      Parameters:
      name - setting key
      fallback - value used for missing or malformed input before clamping
      minimum - inclusive lower bound
      maximum - inclusive upper bound
      Returns:
      parsed value constrained to [minimum, maximum]
      Throws:
      IllegalArgumentException - when maximum < minimum

    • getLongSetting

      default long getLongSetting(String name, long fallback)
      Reads a base-10 long setting without propagating parse errors.
      Parameters:
      name - setting key
      fallback - value used for missing or malformed input
      Returns:
      parsed value or fallback

    • getDoubleSetting

      default double getDoubleSetting(String name, double fallback)
      Reads a finite floating-point setting.
      Parameters:
      name - setting key
      fallback - value used for missing, malformed, infinite, or NaN input
      Returns:
      finite parsed value or fallback

    • getBooleanSetting

      default boolean getBooleanSetting(String name, boolean fallback)
      Reads common boolean spellings such as true, yes, and 1.
      Parameters:
      name - setting key
      fallback - value used for missing or unrecognized input
      Returns:
      parsed boolean or fallback

    • getEnumSetting

      default <E extends Enum<E>> E getEnumSetting(String name, Class<E> type, E fallback)
      Reads an enum constant case-insensitively, treating spaces and hyphens as underscores.
      Type Parameters:
      E - enum type
      Parameters:
      name - setting key
      type - enum class used for parsing
      fallback - value used for missing or unrecognized input
      Returns:
      parsed enum constant or fallback
      Throws:
      NullPointerException - when type is null

    • getListSetting

      default List<String> getListSetting(String name)
      Reads a comma-separated setting as trimmed, non-empty strings.
      Parameters:
      name - setting key
      Returns:
      immutable list, empty when the setting is absent or blank

    • getIntListSetting

      default List<Integer> getIntListSetting(String name)
      Reads a comma-separated list while silently omitting malformed integers.
      Parameters:
      name - setting key
      Returns:
      immutable list of successfully parsed integers

    • debug

      default void debug(String message)
      Logs a debug message.
      Parameters:
      message - message logged at DEBUG severity

    • info

      default void info(String message)
      Logs an informational message.
      Parameters:
      message - message logged at INFO severity

    • warn

      default void warn(String message)
      Logs a warning message.
      Parameters:
      message - message logged at WARN severity

    • error

      default void error(String message)
      Logs an error message.
      Parameters:
      message - message logged at ERROR severity

    • requirePermission

      default void requirePermission(String permission)
      Requires a package permission before continuing.
      Parameters:
      permission - permission string, preferably from Permissions
      Throws:
      SecurityException - when the permission is not granted