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. The SOAP messages are NTLM-encrypted on the wire.
      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
      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

    • 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)