Interface SystemRegistry

  • All Superinterfaces:
    CommandRegistry, org.jline.builtins.ConsoleOptionGetter
    All Known Implementing Classes:
    SimpleSystemRegistryImpl, SystemRegistryImpl

    public interface SystemRegistry
    extends CommandRegistry, org.jline.builtins.ConsoleOptionGetter
    Interface for aggregating command registries and dispatching command executions in a console application.

    The SystemRegistry serves as the central registry for commands in a console application. It aggregates multiple command registries, handles command execution, and provides facilities for command completion, description, and error handling.

    The SystemRegistry is responsible for:

    • Aggregating multiple command registries
    • Dispatching command executions to the appropriate registry
    • Providing command completion and description
    • Handling command execution errors
    • Managing console options and variables
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      static void add​(SystemRegistry systemRegistry)
      Associates a system registry with the current thread.
      void cleanUp()
      Deletes temporary console variables and resets output streams.
      void close()
      Orderly closes this system registry.
      CmdDesc commandDescription​(CmdLine line)
      Returns a description for a command, method, or syntax for use in the JLine Widgets framework.
      org.jline.reader.Completer completer()
      Returns a command completer that includes console variable and script completion.
      java.lang.Object consoleOption​(java.lang.String name)
      Returns the value of a console option.
      <T> T consoleOption​(java.lang.String name, T defVal)
      Returns the value of a console option with a default value if the option doesn't exist.
      java.lang.Object execute​(java.lang.String line)
      Executes a command, script, or evaluates a script engine statement.
      static SystemRegistry get()
      Returns the system registry associated with the current thread.
      java.util.Collection<java.lang.String> getPipeNames()
      Returns the names of all pipes defined in this system registry.
      void initialize​(java.io.File script)
      Initializes the console engine environment by executing a console script.
      java.lang.Object invoke​(java.lang.String command, java.lang.Object... args)
      Executes a command with the specified arguments.
      boolean isCommandAlias​(java.lang.String alias)
      Checks if an alias is a known command alias.
      boolean isCommandOrScript​(java.lang.String command)
      Checks if a command or script is known to this registry.
      boolean isCommandOrScript​(org.jline.reader.ParsedLine line)
      Checks if a parsed line contains a command or script that is known to this registry.
      void register​(java.lang.String command, CommandRegistry subcommandRegistry)
      Registers a subcommand registry for a main command.
      static void remove()
      Removes the system registry association from the current thread.
      void setCommandRegistries​(CommandRegistry... commandRegistries)
      Sets the command registries to be used by this system registry.
      void setConsoleOption​(java.lang.String name, java.lang.Object value)
      Sets the value of a console option.
      org.jline.terminal.Terminal terminal()
      Returns the terminal associated with this system registry.
      void trace​(boolean stack, java.lang.Throwable exception)
      Prints an exception on the terminal with control over stack trace display.
      void trace​(java.lang.Throwable exception)
      Prints an exception on the terminal.
    • Method Detail

      • setCommandRegistries

        void setCommandRegistries​(CommandRegistry... commandRegistries)
        Sets the command registries to be used by this system registry.

        This method configures the command registries that will be aggregated by this system registry. Commands from all of these registries will be available for execution through this system registry.

        Parameters:
        commandRegistries - the command registries to be used by the application
      • register

        void register​(java.lang.String command,
                      CommandRegistry subcommandRegistry)
        Registers a subcommand registry for a main command.

        This method associates a subcommand registry with a main command, allowing the system registry to delegate subcommand execution to the appropriate registry. This is useful for implementing command hierarchies.

        Parameters:
        command - the main command name
        subcommandRegistry - the registry containing the subcommands for the main command
      • initialize

        void initialize​(java.io.File script)
        Initializes the console engine environment by executing a console script.

        This method executes the specified script to initialize the console engine environment. The script can set up variables, aliases, and other configuration needed for the console application.

        Parameters:
        script - the initialization script to execute
      • getPipeNames

        java.util.Collection<java.lang.String> getPipeNames()
        Returns the names of all pipes defined in this system registry.

        This method retrieves the names of all pipes that have been defined in this system registry. Pipes are used to connect the output of one command to the input of another.

        Returns:
        a collection of pipe names defined in this system registry
      • completer

        org.jline.reader.Completer completer()
        Returns a command completer that includes console variable and script completion.

        This method creates a completer that can provide completion for commands, console variables, and scripts. The completer can be used for tab completion in the console.

        Returns:
        a completer for commands, console variables, and scripts
      • commandDescription

        CmdDesc commandDescription​(CmdLine line)
        Returns a description for a command, method, or syntax for use in the JLine Widgets framework.

        This method generates a description for the specified command line, which can be displayed in the terminal status bar by JLine TailTipWidgets. The description includes information about the command's arguments, options, and usage.

        Parameters:
        line - the command line whose description to return
        Returns:
        a command description for JLine TailTipWidgets to be displayed in the terminal status bar
      • execute

        java.lang.Object execute​(java.lang.String line)
                          throws java.lang.Exception
        Executes a command, script, or evaluates a script engine statement.

        This method parses and executes the specified command line. If the line contains a known command, it will be executed. If it contains a script name, the script will be executed. Otherwise, the line will be evaluated as a script engine statement.

        Parameters:
        line - the command line to be executed
        Returns:
        the result of executing the command line
        Throws:
        java.lang.Exception - if an error occurs during execution
      • cleanUp

        void cleanUp()
        Deletes temporary console variables and resets output streams.

        This method cleans up temporary console variables and resets output streams to their default state. It should be called after command execution to ensure that temporary variables and redirected output streams don't affect subsequent commands.

      • trace

        void trace​(java.lang.Throwable exception)
        Prints an exception on the terminal.

        This method prints the specified exception on the terminal, including its message and stack trace. This is a convenience method that calls trace(boolean, Throwable) with stack=true.

        Parameters:
        exception - the exception to print on the terminal
      • trace

        void trace​(boolean stack,
                   java.lang.Throwable exception)
        Prints an exception on the terminal with control over stack trace display.

        This method prints the specified exception on the terminal. If stack is true, the full stack trace will be printed. Otherwise, only the exception message will be printed.

        Parameters:
        stack - whether to print the full stack trace (true) or just the message (false)
        exception - the exception to be printed
      • consoleOption

        java.lang.Object consoleOption​(java.lang.String name)
        Returns the value of a console option.

        This method retrieves the value of the console option with the specified name. Console options are used to configure the behavior of the console and its components.

        Specified by:
        consoleOption in interface org.jline.builtins.ConsoleOptionGetter
        Parameters:
        name - the name of the option to retrieve
        Returns:
        the value of the option, or null if the option doesn't exist
      • consoleOption

        <T> T consoleOption​(java.lang.String name,
                            T defVal)
        Returns the value of a console option with a default value if the option doesn't exist.

        This method retrieves the value of the console option with the specified name, returning a default value if the option doesn't exist. Console options are used to configure the behavior of the console and its components.

        Specified by:
        consoleOption in interface org.jline.builtins.ConsoleOptionGetter
        Type Parameters:
        T - the type of the option value
        Parameters:
        name - the name of the option to retrieve
        defVal - the default value to return if the option doesn't exist
        Returns:
        the value of the option, or the default value if the option doesn't exist
      • setConsoleOption

        void setConsoleOption​(java.lang.String name,
                              java.lang.Object value)
        Sets the value of a console option.

        This method sets the value of the console option with the specified name. Console options are used to configure the behavior of the console and its components.

        Parameters:
        name - the name of the option to set
        value - the value to assign to the option
      • terminal

        org.jline.terminal.Terminal terminal()
        Returns the terminal associated with this system registry.

        This method retrieves the terminal that is used by this system registry for input and output operations.

        Returns:
        the terminal associated with this system registry
      • invoke

        java.lang.Object invoke​(java.lang.String command,
                                java.lang.Object... args)
                         throws java.lang.Exception
        Executes a command with the specified arguments.

        This method executes the specified command with the specified arguments. The command is looked up in the command registries associated with this system registry.

        Parameters:
        command - the command to be executed
        args - the arguments to pass to the command
        Returns:
        the result of executing the command
        Throws:
        java.lang.Exception - if an error occurs during execution
      • isCommandOrScript

        boolean isCommandOrScript​(org.jline.reader.ParsedLine line)
        Checks if a parsed line contains a command or script that is known to this registry.

        This method determines whether the specified parsed command line contains a command or script that is known to this registry. This can be used to determine whether the line can be executed by this registry.

        Parameters:
        line - the parsed command line to test
        Returns:
        true if the specified line contains a command or script that is known to this registry, false otherwise
      • isCommandOrScript

        boolean isCommandOrScript​(java.lang.String command)
        Checks if a command or script is known to this registry.

        This method determines whether the specified command or script is known to this registry. This can be used to determine whether the command or script can be executed by this registry.

        Parameters:
        command - the command or script name to test
        Returns:
        true if the specified command or script is known to this registry, false otherwise
      • isCommandAlias

        boolean isCommandAlias​(java.lang.String alias)
        Checks if an alias is a known command alias.

        This method determines whether the specified alias is a known command alias. Command aliases are alternative names for commands that can be used to invoke them.

        Parameters:
        alias - the alias to test
        Returns:
        true if the specified alias is a known command alias, false otherwise
      • close

        void close()
        Orderly closes this system registry.

        This method performs an orderly shutdown of this system registry, releasing any resources it holds and performing any necessary cleanup operations. It should be called when the system registry is no longer needed.

      • get

        static SystemRegistry get()
        Returns the system registry associated with the current thread.

        This method retrieves the system registry that has been associated with the current thread using the add(SystemRegistry) method. This can be used to access the system registry from code that doesn't have a direct reference to it.

        Returns:
        the system registry associated with the current thread, or null if none is associated
      • add

        static void add​(SystemRegistry systemRegistry)
        Associates a system registry with the current thread.

        This method associates the specified system registry with the current thread, making it accessible via the get() method. This can be used to make the system registry available to code that doesn't have a direct reference to it.

        Parameters:
        systemRegistry - the system registry to associate with the current thread
      • remove

        static void remove()
        Removes the system registry association from the current thread.

        This method removes the association between the current thread and its system registry, making the system registry no longer accessible via the get() method. This should be called when the thread is done using the system registry.