Package org.metricshub.winrm

Class WqlRequest

java.lang.Object
org.metricshub.winrm.WqlRequest
public final class WqlRequest extends Object
A WQL query being prepared for execution, created by WinRMClient.wql(String). Every option has a sensible default; execute() runs the query and returns the complete result, stream() yields the rows lazily as they arrive.

  • Method Details

    • namespace

      public WqlRequest namespace(String namespace)
      Set the WMI namespace to query. Default: the client's namespace (ROOT\CIMV2 unless configured on the builder).
      Parameters:
      namespace - the WMI namespace, e.g. root\cimv2
      Returns:
      this request

    • timeout

      public WqlRequest timeout(Duration timeout)
      Set the timeout of this query. For execute() it is a wall-clock deadline covering every WSMan round trip and result collection; for stream() it is an inactivity timeout — the longest silence tolerated from the server between two responses, with no overall deadline. Default: the client's timeout.
      Parameters:
      timeout - the timeout (at least one millisecond)
      Returns:
      this request

    • pageSize

      public WqlRequest pageSize(int pageSize)
      Set the enumeration batch size: how many rows the server may return per WSMan Enumerate/Pull response (MaxElements). Default: 32000.
      Parameters:
      pageSize - the maximum number of rows per response (must be positive)
      Returns:
      this request

    • pullTimeout

      public WqlRequest pullTimeout(Duration pullTimeout)
      Set the maximum time the server may hold a single Pull request open before answering with the rows it has (MaxTime). Default: none — the server decides.
      Parameters:
      pullTimeout - the per-Pull timeout (at least one millisecond)
      Returns:
      this request

    • execute

      public WqlResult execute()
      Execute the query and collect the complete result.
      Returns:
      the query result: rows, columns in query order, and execution time
      Throws:
      WqlSyntaxException - when the WQL query is invalid
      WinRMTimeoutException - when the timeout elapses first
      WinRMAuthenticationException - when the credentials are rejected
      WinRMFaultException - when the remote service answers with a WSMan fault
      WinRMClientException - for any other failure

    • stream

      public Stream<WqlRow> stream()
      Execute the query and stream the rows lazily: each row is yielded as soon as it is parsed, and the next WS-Enumeration page is pulled from the server only as the stream advances — memory stays bounded by one page (pageSize(int)) instead of the whole result set. 
      
 try (Stream<WqlRow> rows = client.wql("SELECT * FROM Win32_NTLogEvent").stream()) {
 	rows.filter(row -> "Error".equals(row.string("Type"))).limit(100).forEach(this::process);
 }

      The stream must be closed (same contract as Files.lines(java.nio.file.Path, java.nio.charset.Charset)) — use try-with-resources. It holds the client's serial connection while open: other operations on the same client block until it is closed or exhausted. Closing before the last row tells the server to release the enumeration immediately (WS-Enumeration Release).

      The timeout acts as an inactivity timeout — the longest silence tolerated from the server between two responses — not an overall deadline: consuming a large result can take arbitrarily long as long as the server keeps answering. The initial request is sent here; later pages are fetched during consumption, so the exceptions below can also be thrown from the stream's operations while iterating.

      Returns:
      a lazy, sequential stream of rows, to use with try-with-resources
      Throws:
      WqlSyntaxException - when the WQL query is invalid
      WinRMTimeoutException - when the inactivity timeout elapses
      WinRMAuthenticationException - when the credentials are rejected
      WinRMFaultException - when the remote service answers with a WSMan fault
      WinRMClientException - for any other failure