Package org.metricshub.winrm

Class WinRMClient

java.lang.Object
org.metricshub.winrm.WinRMClient
All Implemented Interfaces:
AutoCloseable
public final class WinRMClient extends Object implements AutoCloseable
The fluent entry point of the library: a reusable WinRM connection to one host, created with a builder and closed with try-with-resources. One client authenticates once and can run any number of WQL queries and commands over the same connection. 

 try (
 	WinRMClient client = WinRMClient.builder("server01.acme.com")
 		.credentials("ACME\\admin", password)
 		.timeout(Duration.ofSeconds(30))
 		.build()) {

 	WqlResult services = client.wql("SELECT Name, State FROM Win32_Service").execute();
 	for (WqlRow row : services) {
 		System.out.println(row.string("Name") + " is " + row.string("State"));
 	}

 	CommandResult result = client.command("ipconfig /all").execute();
 	System.out.println(result.stdout());
 }

Besides the blocking execute() terminals, both operations can stream: WqlRequest.stream() yields WQL rows lazily page by page, and CommandRequest.start() returns a RemoteProcess whose output is consumed while the command is still running.

Thread-safety: a client may be shared between threads, but a WinRM connection is a serial channel — concurrent operations are executed one at a time, and an open stream or process holds the connection until it is closed.

Failures are reported through the unchecked WinRMClientException hierarchy; the legacy static helpers (WinRMWqlExecutor, WinRMCommandExecutor) and their checked exceptions are unaffected.

  • Method Details

    • builder

      public static WinRMClient.Builder builder(String hostname)
      Start building a client for the given host.
      Parameters:
      hostname - the host to connect to (mandatory; for Kerberos, use the FQDN the KDC knows)
      Returns:
      a new WinRMClient.Builder

    • wql

      public WqlRequest wql(String query)
      Prepare a WQL query. Nothing is sent until WqlRequest.execute() is called.
      Parameters:
      query - the WQL query, e.g. SELECT Name, State FROM Win32_Service
      Returns:
      the request, to configure and execute

    • command

      public CommandRequest command(String commandLine)
      Prepare a command execution. Nothing is sent until CommandRequest.execute() is called.
      Parameters:
      commandLine - the command line to execute (run through cmd.exe by the remote shell)
      Returns:
      the request, to configure and execute

    • uploadFile

      public void uploadFile(Path localFile, String remoteFile)
      Copy a local file to an explicit path on the remote host, through the WinRM connection itself (no SMB, no extra port). The transfer is digest-verified and skipped when the destination already has identical content; the destination directory is created when needed. The client's timeout applies.
      Parameters:
      localFile - the local file to copy
      remoteFile - the absolute destination path on the remote host, e.g. C:\Windows\Temp\collect.ps1
      Throws:
      WinRMTimeoutException - when the timeout elapses first
      WinRMClientException - for any other failure

    • hostname

      public String hostname()
      Get the hostname this client connects to.
      Returns:
      the hostname

    • close

      public void close()
      Close the client and release its connection. Idempotent; operations attempted after closing throw IllegalStateException.
      Specified by:
      close in interface AutoCloseable