Interface ScriptEngine


  • public interface ScriptEngine
    Interface for managing script engine variables, statements, and script execution.

    The ScriptEngine interface provides methods for interacting with a script engine, such as executing scripts and statements, managing variables, and serializing/deserializing objects. It serves as a bridge between JLine and various scripting languages like JavaScript, Groovy, etc.

    The ScriptEngine is responsible for:

    • Executing scripts and statements in the underlying script engine
    • Managing variables in the script engine's context
    • Converting objects between Java and the script engine's native format
    • Serializing and deserializing objects to/from various formats
    • Providing completers for script-specific syntax
    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      void del​(java.lang.String... vars)
      Deletes variables from the script engine's context.
      default java.lang.Object deserialize​(java.lang.String value)
      Deserializes a value from its string representation.
      java.lang.Object deserialize​(java.lang.String value, java.lang.String format)
      Deserializes a value from its string representation using the specified format.
      default java.lang.Object execute​(java.io.File script)
      Executes a script from a file.
      java.lang.Object execute​(java.io.File script, java.lang.Object[] args)
      Executes a script from a file with the specified arguments.
      java.lang.Object execute​(java.lang.Object closure, java.lang.Object... args)
      Executes a script engine closure with the specified arguments.
      java.lang.Object execute​(java.lang.String statement)
      Executes a script engine statement.
      default java.lang.Object execute​(java.nio.file.Path script)
      Executes a script from a file.
      default java.lang.Object execute​(java.nio.file.Path script, java.lang.Object[] args)
      Executes a script from a file with the specified arguments.
      default java.util.Map<java.lang.String,​java.lang.Object> find()
      Gets all variables with their values from the script engine's context.
      java.util.Map<java.lang.String,​java.lang.Object> find​(java.lang.String name)
      Gets all variables that match the specified pattern.
      java.lang.Object get​(java.lang.String name)
      Gets the value of a variable from the script engine's context.
      java.util.List<java.lang.String> getDeserializationFormats()
      Returns the deserialization formats supported by this script engine.
      java.lang.String getEngineName()
      Returns the name of the underlying script engine.
      java.util.Collection<java.lang.String> getExtensions()
      Returns the file name extensions associated with this script engine.
      Completer getScriptCompleter()
      Returns a completer for script-specific syntax.
      java.util.List<java.lang.String> getSerializationFormats()
      Returns the serialization formats supported by this script engine.
      boolean hasVariable​(java.lang.String name)
      Tests if a variable exists in the script engine's context.
      void persist​(java.nio.file.Path file, java.lang.Object object)
      Persists an object to a file.
      void persist​(java.nio.file.Path file, java.lang.Object object, java.lang.String format)
      Persists an object to a file using the specified serialization format.
      void put​(java.lang.String name, java.lang.Object value)
      Creates or updates a variable in the script engine's context.
      java.lang.String toJson​(java.lang.Object object)
      Serializes an object to a JSON string.
      java.util.Map<java.lang.String,​java.lang.Object> toMap​(java.lang.Object object)
      Converts an object's fields to a map.
      java.lang.String toString​(java.lang.Object object)
      Converts an object to its string representation.
    • Method Detail

      • getEngineName

        java.lang.String getEngineName()
        Returns the name of the underlying script engine.

        This method retrieves the name of the script engine implementation being used, such as "JavaScript", "Groovy", etc.

        Returns:
        the name of the script engine
      • getExtensions

        java.util.Collection<java.lang.String> getExtensions()
        Returns the file name extensions associated with this script engine.

        This method retrieves the file extensions that are recognized by this script engine, such as ".js" for JavaScript, ".groovy" for Groovy, etc.

        Returns:
        a collection of file name extensions associated with this script engine
      • getScriptCompleter

        Completer getScriptCompleter()
        Returns a completer for script-specific syntax.

        This method retrieves a completer that can provide completion for script-specific syntax, such as keywords, built-in functions, etc. The completer can be used for tab completion in the console.

        Returns:
        a completer for script-specific syntax
      • hasVariable

        boolean hasVariable​(java.lang.String name)
        Tests if a variable exists in the script engine's context.

        This method determines whether a variable with the specified name exists in the script engine's context.

        Parameters:
        name - the name of the variable to check
        Returns:
        true if a variable with the specified name exists, false otherwise
      • put

        void put​(java.lang.String name,
                 java.lang.Object value)
        Creates or updates a variable in the script engine's context.

        This method creates a new variable with the specified name and value in the script engine's context, or updates an existing variable if one with the specified name already exists.

        Parameters:
        name - the name of the variable to create or update
        value - the value to assign to the variable
      • get

        java.lang.Object get​(java.lang.String name)
        Gets the value of a variable from the script engine's context.

        This method retrieves the value of the variable with the specified name from the script engine's context.

        Parameters:
        name - the name of the variable to get
        Returns:
        the value of the variable, or null if no variable with the specified name exists
      • find

        default java.util.Map<java.lang.String,​java.lang.Object> find()
        Gets all variables with their values from the script engine's context.

        This method retrieves all variables and their values from the script engine's context. This is a convenience method that calls find(String) with a null pattern.

        Returns:
        a map of variable names to their values
      • find

        java.util.Map<java.lang.String,​java.lang.Object> find​(java.lang.String name)
        Gets all variables that match the specified pattern.

        This method retrieves all variables whose names match the specified pattern from the script engine's context. The pattern can contain wildcard characters (*) to match multiple variable names.

        Parameters:
        name - the pattern to match variable names against, or null to match all variables
        Returns:
        a map of matching variable names to their values
      • del

        void del​(java.lang.String... vars)
        Deletes variables from the script engine's context.

        This method removes variables from the script engine's context. The variable names can contain wildcard characters (*) to match multiple variables.

        Parameters:
        vars - the names of the variables to delete, which can contain wildcard characters
      • toJson

        java.lang.String toJson​(java.lang.Object object)
        Serializes an object to a JSON string.

        This method converts the specified object to a formatted JSON string representation. The exact format of the JSON string depends on the script engine implementation.

        Parameters:
        object - the object to serialize to JSON
        Returns:
        a formatted JSON string representation of the object
      • toString

        java.lang.String toString​(java.lang.Object object)
        Converts an object to its string representation.

        This method converts the specified object to a string representation. The exact format of the string depends on the script engine implementation.

        Parameters:
        object - the object to convert to a string
        Returns:
        a string representation of the object
      • toMap

        java.util.Map<java.lang.String,​java.lang.Object> toMap​(java.lang.Object object)
        Converts an object's fields to a map.

        This method extracts the fields of the specified object and returns them as a map of field names to field values. The exact set of fields included in the map depends on the script engine implementation.

        Parameters:
        object - the object whose fields to extract
        Returns:
        a map of field names to field values
      • deserialize

        default java.lang.Object deserialize​(java.lang.String value)
        Deserializes a value from its string representation.

        This method converts the specified string representation back to an object. This is a convenience method that calls deserialize(String, String) with a null format.

        Parameters:
        value - the string representation to deserialize
        Returns:
        the deserialized object
      • deserialize

        java.lang.Object deserialize​(java.lang.String value,
                                     java.lang.String format)
        Deserializes a value from its string representation using the specified format.

        This method converts the specified string representation back to an object using the specified serialization format.

        Parameters:
        value - the string representation to deserialize
        format - the serialization format to use, or null to use the default format
        Returns:
        the deserialized object
      • getSerializationFormats

        java.util.List<java.lang.String> getSerializationFormats()
        Returns the serialization formats supported by this script engine.

        This method retrieves the names of the serialization formats that can be used with the persist(Path, Object, String) method.

        Returns:
        a list of supported serialization format names
      • getDeserializationFormats

        java.util.List<java.lang.String> getDeserializationFormats()
        Returns the deserialization formats supported by this script engine.

        This method retrieves the names of the deserialization formats that can be used with the deserialize(String, String) method.

        Returns:
        a list of supported deserialization format names
      • persist

        void persist​(java.nio.file.Path file,
                     java.lang.Object object)
        Persists an object to a file.

        This method serializes the specified object and writes it to the specified file. This is a convenience method that calls persist(Path, Object, String) with a null format.

        Parameters:
        file - the file to write the serialized object to
        object - the object to serialize and persist
      • persist

        void persist​(java.nio.file.Path file,
                     java.lang.Object object,
                     java.lang.String format)
        Persists an object to a file using the specified serialization format.

        This method serializes the specified object using the specified format and writes it to the specified file.

        Parameters:
        file - the file to write the serialized object to
        object - the object to serialize and persist
        format - the serialization format to use, or null to use the default format
      • execute

        java.lang.Object execute​(java.lang.String statement)
                          throws java.lang.Exception
        Executes a script engine statement.

        This method evaluates the specified statement in the script engine and returns the result of the evaluation.

        Parameters:
        statement - the statement to execute
        Returns:
        the result of executing the statement
        Throws:
        java.lang.Exception - if an error occurs during execution
      • execute

        default java.lang.Object execute​(java.nio.file.Path script)
                                  throws java.lang.Exception
        Executes a script from a file.

        This method executes the script contained in the specified file and returns the result of the execution. This is a convenience method that calls execute(File, Object[]) with null arguments.

        Parameters:
        script - the file containing the script to execute
        Returns:
        the result of executing the script
        Throws:
        java.lang.Exception - if an error occurs during execution
      • execute

        default java.lang.Object execute​(java.io.File script)
                                  throws java.lang.Exception
        Executes a script from a file.

        This method executes the script contained in the specified file and returns the result of the execution. This is a convenience method that calls execute(File, Object[]) with null arguments.

        Parameters:
        script - the file containing the script to execute
        Returns:
        the result of executing the script
        Throws:
        java.lang.Exception - if an error occurs during execution
      • execute

        default java.lang.Object execute​(java.nio.file.Path script,
                                         java.lang.Object[] args)
                                  throws java.lang.Exception
        Executes a script from a file with the specified arguments.

        This method executes the script contained in the specified file with the specified arguments and returns the result of the execution. This is a convenience method that calls execute(File, Object[]) with the file converted to a File object.

        Parameters:
        script - the file containing the script to execute
        args - the arguments to pass to the script, or null if no arguments
        Returns:
        the result of executing the script
        Throws:
        java.lang.Exception - if an error occurs during execution
      • execute

        java.lang.Object execute​(java.io.File script,
                                 java.lang.Object[] args)
                          throws java.lang.Exception
        Executes a script from a file with the specified arguments.

        This method executes the script contained in the specified file with the specified arguments and returns the result of the execution.

        Parameters:
        script - the file containing the script to execute
        args - the arguments to pass to the script, or null if no arguments
        Returns:
        the result of executing the script
        Throws:
        java.lang.Exception - if an error occurs during execution
      • execute

        java.lang.Object execute​(java.lang.Object closure,
                                 java.lang.Object... args)
        Executes a script engine closure with the specified arguments.

        This method executes the specified closure (a callable object) with the specified arguments and returns the result of the execution.

        Parameters:
        closure - the closure to execute
        args - the arguments to pass to the closure
        Returns:
        the result of executing the closure