1 package org.metricshub.winrm;
2
3 /*-
4 * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
5 * WinRM Java Client
6 * ჻჻჻჻჻჻
7 * Copyright (C) 2023 - 2026 MetricsHub
8 * ჻჻჻჻჻჻
9 * Licensed under the Apache License, Version 2.0 (the "License");
10 * you may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
21 */
22
23 import java.util.Map;
24 import java.util.concurrent.TimeoutException;
25 import org.metricshub.winrm.exceptions.WindowsRemoteException;
26
27 /**
28 * A lazily-advancing cursor over the rows of a WQL enumeration, returned by
29 * {@link WindowsRemoteExecutor#streamWql(String, String, long, int, long)}. Rows are parsed and
30 * served page by page: advancing past the current WS-Enumeration page issues the next Pull
31 * request, so memory stays bounded by one page rather than the whole result set.
32 * <p>
33 * The cursor owns the executor's serial connection until it is exhausted or closed: no other
34 * operation can run on the same executor while the cursor is open (the same contract as a JDBC
35 * {@code ResultSet} on its connection). Exhaustion releases the connection on its own; closing
36 * before the end additionally sends a WS-Enumeration Release so the server frees the enumeration
37 * context immediately. Always close the cursor — use try-with-resources.
38 * <p>
39 * A cursor is not thread-safe: advance and close it from one thread at a time.
40 */
41 public interface WqlCursor extends AutoCloseable {
42 /**
43 * Advance to the next row, issuing the next WS-Enumeration Pull when the current page is
44 * exhausted.
45 *
46 * @return the next row as an ordered property map, or {@code null} once the enumeration is
47 * exhausted
48 * @throws TimeoutException when the server stays silent for a whole per-round-trip timeout
49 * (the inactivity timeout of the stream)
50 * @throws WindowsRemoteException for any other failure while pulling
51 */
52 Map<String, Object> next() throws TimeoutException, WindowsRemoteException;
53
54 /**
55 * Release the enumeration and the executor's connection. When the enumeration is not
56 * exhausted, a best-effort WS-Enumeration Release tells the server to free the enumeration
57 * context. Idempotent, and never throws: releasing the context is a courtesy the server can
58 * also handle on its own timeout.
59 */
60 @Override
61 void close();
62 }