Package org.metricshub.winrm

Interface WindowsRemoteExecutor

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
LightWinRMService
public interface WindowsRemoteExecutor extends AutoCloseable

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_WQL_MAX_ELEMENTS
    Default WS-Enumeration MaxElements batch size for WQL queries: how many rows the server may return per Enumerate/Pull response.
    static final Charset
    SHELL_OUTPUT_CHARSET
    Charset of the output of every command run through this executor: UTF-8, because the remote command shell is created with console code page 65001.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Close the executor and release its resources.
    WindowsRemoteCommandResult
    executeCommand(String command, String workingDirectory, Charset charset, long timeout)
    Execute the command on the remote
    List<Map<String,Object>>
    executeWql(String wqlQuery, long timeout)
    Execute a WQL query and process its result.
    default List<Map<String,Object>>
    executeWql(String namespace, String wqlQuery, long timeout, int maxElements, long pullTimeout)
    Execute a WQL query with explicit enumeration parameters: the WMI namespace, the WS-Enumeration MaxElements batch size, and the per-Pull MaxTime.
    String
    getHostname()
    Get the hostname.
    char[]
    getPassword()
    Get the password.
    String
    getUsername()
    Get the username.
    default CommandCursor
    startCommand(String command, String workingDirectory, long timeout)
    Start a command on the remote host and return a CommandCursor over its raw output: chunks can be consumed as the WSMan Receive responses arrive, before the command exits.
    default CommandCursor
    startCommand(String command, String workingDirectory, long timeout, boolean consoleModeStdin)
    Variant of startCommand(String, String, long) making the WINRS_CONSOLEMODE_STDIN option explicit.
    default WqlCursor
    streamWql(String namespace, String wqlQuery, long timeout, int maxElements, long pullTimeout)
    Start a WQL enumeration and return a lazy WqlCursor over its rows: rows can be consumed as the WS-Enumeration pages arrive, and memory stays bounded by one page.

  • Field Details

    • DEFAULT_WQL_MAX_ELEMENTS

      static final int DEFAULT_WQL_MAX_ELEMENTS
      Default WS-Enumeration MaxElements batch size for WQL queries: how many rows the server may return per Enumerate/Pull response.
      See Also:

    • SHELL_OUTPUT_CHARSET

      static final Charset SHELL_OUTPUT_CHARSET
      Charset of the output of every command run through this executor: UTF-8, because the remote command shell is created with console code page 65001. It is not the remote machine's ANSI or OEM code page, and it does not depend on the remote locale.

  • Method Details

    • executeWql

      List<Map<String,Object>> executeWql(String wqlQuery, long timeout) throws TimeoutException, WqlQuerySyntaxException, WindowsRemoteException

      Execute a WQL query and process its result.

      Parameters:
      wqlQuery - the WQL query (required)
      timeout - Timeout in milliseconds (throws an IllegalArgumentException if negative or zero)
      Returns:
      a list of result rows. A result row is a Map(LinkedHashMap to preserve the query order) of properties/values.
      Throws:
      TimeoutException - to notify userName of timeout.
      WqlQuerySyntaxException - if WQL query syntax is invalid
      WindowsRemoteException - For any problem encountered

    • executeWql

      default List<Map<String,Object>> executeWql(String namespace, String wqlQuery, long timeout, int maxElements, long pullTimeout) throws TimeoutException, WqlQuerySyntaxException, WindowsRemoteException

      Execute a WQL query with explicit enumeration parameters: the WMI namespace, the WS-Enumeration MaxElements batch size, and the per-Pull MaxTime.

      The default implementation throws UnsupportedOperationException: only executors that can honor the namespace and enumeration parameters (such as the built-in lightweight backend) implement this method, and silently ignoring a namespace would query the wrong resource.

      Parameters:
      namespace - the WMI namespace to query, e.g. ROOT\CIMV2 (required)
      wqlQuery - the WQL query (required)
      timeout - Timeout in milliseconds (throws an IllegalArgumentException if negative or zero)
      maxElements - maximum number of rows per Enumerate/Pull response (throws an IllegalArgumentException if negative or zero); see DEFAULT_WQL_MAX_ELEMENTS
      pullTimeout - maximum time in milliseconds the server may hold a single Pull open before answering with the rows it has (MaxTime); 0 leaves it to the server default
      Returns:
      a list of result rows. A result row is a Map(LinkedHashMap to preserve the query order) of properties/values.
      Throws:
      TimeoutException - to notify userName of timeout.
      WqlQuerySyntaxException - if WQL query syntax is invalid
      WindowsRemoteException - For any problem encountered

    • streamWql

      default WqlCursor streamWql(String namespace, String wqlQuery, long timeout, int maxElements, long pullTimeout) throws TimeoutException, WqlQuerySyntaxException, WindowsRemoteException

      Start a WQL enumeration and return a lazy WqlCursor over its rows: rows can be consumed as the WS-Enumeration pages arrive, and memory stays bounded by one page.

      The default implementation throws UnsupportedOperationException: only executors that support streaming (such as the built-in lightweight backend) implement this method.

      Parameters:
      namespace - the WMI namespace to query, e.g. ROOT\CIMV2 (required)
      wqlQuery - the WQL query (required)
      timeout - timeout in milliseconds of each WSMan round trip — the inactivity timeout of the stream, not an overall deadline (throws an IllegalArgumentException if negative or zero)
      maxElements - maximum number of rows per Enumerate/Pull response (throws an IllegalArgumentException if negative or zero); see DEFAULT_WQL_MAX_ELEMENTS
      pullTimeout - maximum time in milliseconds the server may hold a single Pull open before answering with the rows it has (MaxTime); 0 leaves it to the server default
      Returns:
      a cursor over the result rows, owning the executor's connection until exhausted or closed — always close it (try-with-resources)
      Throws:
      TimeoutException - when the server does not answer the initial Enumerate in time
      WqlQuerySyntaxException - if WQL query syntax is invalid
      WindowsRemoteException - For any problem encountered

    • startCommand

      default CommandCursor startCommand(String command, String workingDirectory, long timeout) throws TimeoutException, WindowsRemoteException

      Start a command on the remote host and return a CommandCursor over its raw output: chunks can be consumed as the WSMan Receive responses arrive, before the command exits.

      The default implementation throws UnsupportedOperationException: only executors that support streaming (such as the built-in lightweight backend) implement this method.

      Parameters:
      command - The command to execute
      workingDirectory - Path of the directory for the spawned process on the remote system (can be null)
      timeout - timeout in milliseconds of each WSMan round trip — the inactivity timeout of the stream, not an overall deadline (throws an IllegalArgumentException if negative or zero)
      Returns:
      a cursor over the command output, owning the executor's connection until the command completes or the cursor is closed — always close it (try-with-resources)
      Throws:
      TimeoutException - when the server does not answer the command startup in time
      WindowsRemoteException - For any problem encountered

    • startCommand

      default CommandCursor startCommand(String command, String workingDirectory, long timeout, boolean consoleModeStdin) throws TimeoutException, WindowsRemoteException

      Variant of startCommand(String, String, long) making the WINRS_CONSOLEMODE_STDIN option explicit. The three-argument variant keeps the historical console semantics (TRUE); pass false when the command will be fed standard input through CommandCursor.send(byte[], boolean) and must see it as an ordinary pipe — a console-mode stdin never reaches EOF for tools like sort or more.

      The default implementation delegates console-mode requests to startCommand(String, String, long) — an executor that overrides only the historical three-argument variant keeps working for ordinary commands — and throws UnsupportedOperationException for pipe mode: only executors that support command input (such as the built-in lightweight backend) implement it.

      Parameters:
      command - The command to execute
      workingDirectory - Path of the directory for the spawned process on the remote system (can be null)
      timeout - timeout in milliseconds of each WSMan round trip — the inactivity timeout of the stream, not an overall deadline (throws an IllegalArgumentException if negative or zero)
      consoleModeStdin - the value of the WINRS_CONSOLEMODE_STDIN option: true for console semantics (the historical default), false for pipe semantics
      Returns:
      a cursor over the command output, owning the executor's connection until the command completes or the cursor is closed — always close it (try-with-resources)
      Throws:
      TimeoutException - when the server does not answer the command startup in time
      WindowsRemoteException - For any problem encountered

    • executeCommand

      WindowsRemoteCommandResult executeCommand(String command, String workingDirectory, Charset charset, long timeout) throws WindowsRemoteException, TimeoutException
      Execute the command on the remote
      Parameters:
      command - The command to execute
      workingDirectory - Path of the directory for the spawned process on the remote system (can be null)
      charset - The charset decoding the command output; null uses SHELL_OUTPUT_CHARSET, which is what the remote shell actually emits
      timeout - Timeout in milliseconds
      Returns:
      The command result
      Throws:
      WindowsRemoteException - For any problem encountered
      TimeoutException - To notify userName of timeout.

    • getHostname

      String getHostname()
      Get the hostname.
      Returns:

    • getUsername

      String getUsername()
      Get the username.
      Returns:

    • getPassword

      char[] getPassword()
      Get the password.
      Returns:

    • close

      void close()
      Close the executor and release its resources. Narrows AutoCloseable.close() so it does not declare a checked exception, letting callers use try-with-resources without catching Exception.
      Specified by:
      close in interface AutoCloseable