Package org.metricshub.winrm

Class WinRMClient.Builder

java.lang.Object
org.metricshub.winrm.WinRMClient.Builder
Enclosing class:
WinRMClient
public static final class WinRMClient.Builder extends Object
Builder of WinRMClient instances: connection-scoped settings with sensible defaults. Only the hostname and the credentials are mandatory.

  • Method Details

    • https

      public WinRMClient.Builder https()
      Connect over HTTPS (port 5986 unless port(int) is set). The server certificate is validated against the platform trust store and the hostname is verified, unless trustAllCertificates() or sslContext(SSLContext) says otherwise.
      Returns:
      this builder

    • http

      public WinRMClient.Builder http()
      Connect over HTTP (port 5985 unless port(int) is set) — the default. With NTLM (the default scheme) the SOAP messages are NTLM-encrypted on the wire, so plaintext HTTP is still protected. Other schemes change that guarantee: HTTP Basic sends both the credential and the SOAP in cleartext, so use https() with Basic. Kerberos requires HTTPS; it is rejected fail-closed at build() for ANY scheme list that contains it — including an ordered fallback such as (KERBEROS, NTLM) — rather than being silently dropped and downgraded to another scheme.
      Returns:
      this builder

    • port

      public WinRMClient.Builder port(int port)
      Set the port. Default: 5985 for HTTP, 5986 for HTTPS.
      Parameters:
      port - the TCP port (1-65535)
      Returns:
      this builder

    • credentials

      public WinRMClient.Builder credentials(String username, char[] password)
      Set the credentials (mandatory).
      Parameters:
      username - the user name, plain (user) or domain-qualified (DOMAIN\\user)
      password - the password; the array is deliberately not copied, so the caller can wipe the single authoritative copy of the secret after closing the client
      Returns:
      this builder

    • namespace

      public WinRMClient.Builder namespace(String namespace)
      Set the default WMI namespace for WQL queries. Default: ROOT\CIMV2. Each query can override it with WqlRequest.namespace(String).
      Parameters:
      namespace - the WMI namespace
      Returns:
      this builder

    • authentication

      public WinRMClient.Builder authentication(AuthScheme... schemes)
      Set the authentication schemes, tried in the given order until one succeeds. Default: NTLM only. Kerberos requires HTTPS.
      Parameters:
      schemes - the schemes in fallback order, e.g. KERBEROS, NTLM or BASIC
      Returns:
      this builder

    • ticketCache

      public WinRMClient.Builder ticketCache(Path ticketCache)
      Set the Kerberos ticket cache path. Default: none — Kerberos logs in with the password.
      Parameters:
      ticketCache - the ticket cache path
      Returns:
      this builder

    • trustAllCertificates

      public WinRMClient.Builder trustAllCertificates()
      Trust every server certificate and skip hostname verification over HTTPS — for self-signed test hosts. Insecure: do not use in production. This per-client setting replaces the global org.metricshub.winrm.tls.insecure system property.
      Returns:
      this builder

    • sslContext

      public WinRMClient.Builder sslContext(SSLContext sslContext)
      Use a custom SSLContext for HTTPS — e.g. one built around a dedicated trust store. Hostname verification stays on. Mutually exclusive with trustAllCertificates().
      Parameters:
      sslContext - the TLS context providing the socket factory
      Returns:
      this builder

    • timeout

      public WinRMClient.Builder timeout(Duration timeout)
      Set the default timeout of every operation — a wall-clock deadline covering authentication, every WSMan round trip, and result collection. Default: 30 seconds. Each operation can override it.
      Parameters:
      timeout - the timeout (at least one millisecond)
      Returns:
      this builder

    • retries

      public WinRMClient.Builder retries(int retries, Duration delay)
      Retry transient connection failures. Default: no retry — any failure is reported immediately.

      The policy is deliberately narrow, to preserve at-most-once execution for non-idempotent commands: a WSMan round trip is retried only when it failed to establish and authenticate the connection — TCP connect, DNS resolution, the TLS handshake, or a transport error during the authentication handshake — because there the request provably never reached the server. A request that was actually sent (a command that may have started, a query that may be executing) is never retried; neither are credential rejections (WinRMAuthenticationException) or WSMan faults (WinRMFaultException).

      The policy is connection-scoped: it applies to every operation on the client, including reconnections in the middle of one (WinRM connections are re-established transparently when the server drops an idle one). Retries stay inside each operation's wall-clock deadline — when the timeout elapses mid-pause, the operation fails with WinRMTimeoutException exactly as it would without a retry policy. For the streaming terminals (whose timeout is an inactivity timeout with no overall deadline), each connection attempt is bounded by that timeout, so a retried reconnection can extend the tolerated silence accordingly. 

      
 WinRMClient client = WinRMClient.builder("server01")
 	.credentials("ACME\\admin", password)
 	.retries(2, Duration.ofSeconds(5)) // up to 2 retries, pausing 5 s before each
 	.build();
      Parameters:
      retries - how many times a failed connection attempt is retried (0 disables retrying)
      delay - the pause before each retry (Duration.ZERO retries immediately)
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when retries is negative, or delay is null or negative

    • consoleCodePage

      public WinRMClient.Builder consoleCodePage(int consoleCodePage)
      Set the console code page of the remote command shell. Default: 65001 (UTF-8), which makes command output UTF-8 whatever the remote locale — the right choice for reading output and for piping data to a program.

      An interactive session needs a different setting: under code page 65001 a remote cmd.exe decodes the command lines it reads from its standard input one byte at a time, so every non-ASCII character is lost. Pin a single-byte code page (typically the remote machine's ANSI one, Win32_OperatingSystem.CodeSet) and use the matching charset for both directions, as the CLI's shell subcommand does.

      Parameters:
      consoleCodePage - the console code page (e.g. 1252), or 0 for the default
      Returns:
      this builder

    • build

      public WinRMClient build()
      Build the client. This does not connect yet: the connection is established and authenticated by the first operation.
      Returns:
      the client, to use with try-with-resources
      Throws:
      WinRMClientException - when the configuration is rejected (e.g. Kerberos requested over HTTP)