Follow-up to #189 (PR #193), where WMI array properties were fixed to come back as a single string joined with | (configurable with WinRMClient.Builder.arraySeparator(String)).
Problem
Every WQL value is exposed as a String, whatever its CIM type. Consumers parse numbers, booleans, dates and now |-joined arrays themselves:
WqlRow.get(String) is declared Object but always returns a String.
- An array property is a joined string: a single-element array is indistinguishable from a scalar, and an element that contains the separator is ambiguous.
NULL is an empty string, indistinguishable from an empty string value.
- CIM datetimes arrive in the WS-Management form (
<cim:Datetime>2024-05-01T12:34:56.789Z</cim:Datetime> for CIM_DATETIME values, or an interval), which nobody wants to parse by hand.
Proposal
A typed result variant where the row values are native Java objects, alongside the existing string-based API (which stays the default, and the only one for the legacy WinRMWqlExecutor.getRows() / List<List<String>>).
Suggested shape, to be refined:
- Opt in per query, e.g.
client.wql(query).typed().execute(), or a WqlRow.typed(String) / WqlRow.list(String) accessor family; the legacy List<Map<String, Object>> of WindowsRemoteExecutor.executeWql could also carry typed values under an opt-in flag, so WinRMWqlExecutor keeps its strings.
- Mapping from the type information WS-Management gives us. The instance XML carries no
xsi:type; the CIM type must come from the class schema (a WSMan Get of the class definition, winrm get wmi/...?__CLASS, or the p: XML schema), or from the value form (<cim:Datetime> wrapper, xsi:nil, repeated elements).
Suggested mapping:
| CIM type |
Java |
string, char16 |
String |
boolean |
Boolean |
sint8/sint16/sint32/sint64, uint8/uint16/uint32 |
Integer / Long (uint64 → BigInteger or Long) |
real32/real64 |
Float / Double |
datetime |
java.time.Instant / OffsetDateTime for timestamps, Duration for intervals |
reference |
String (the object path) |
| embedded object |
nested WqlRow |
| array of any of the above |
List<T> |
NULL (xsi:nil="true") |
null |
Open questions
- Where the CIM type information comes from without an extra round trip per query (cache the class schema per client and class?).
- Whether the WS-Management datetime encoding is consistent across Windows versions (2008 R2 through 2022 are available as test hosts).
- Whether the CLI should emit JSON arrays/numbers/booleans/null when typed values are available (today it emits strings only).
Not in scope
The string API stays as it is: the | join and the empty-string NULL are documented behavior since 2.3.00.
Follow-up to #189 (PR #193), where WMI array properties were fixed to come back as a single string joined with
|(configurable withWinRMClient.Builder.arraySeparator(String)).Problem
Every WQL value is exposed as a
String, whatever its CIM type. Consumers parse numbers, booleans, dates and now|-joined arrays themselves:WqlRow.get(String)is declaredObjectbut always returns aString.NULLis an empty string, indistinguishable from an empty string value.<cim:Datetime>2024-05-01T12:34:56.789Z</cim:Datetime>forCIM_DATETIMEvalues, or an interval), which nobody wants to parse by hand.Proposal
A typed result variant where the row values are native Java objects, alongside the existing string-based API (which stays the default, and the only one for the legacy
WinRMWqlExecutor.getRows()/List<List<String>>).Suggested shape, to be refined:
client.wql(query).typed().execute(), or aWqlRow.typed(String)/WqlRow.list(String)accessor family; the legacyList<Map<String, Object>>ofWindowsRemoteExecutor.executeWqlcould also carry typed values under an opt-in flag, soWinRMWqlExecutorkeeps its strings.xsi:type; the CIM type must come from the class schema (a WSManGetof the class definition,winrm get wmi/...?__CLASS, or thep:XML schema), or from the value form (<cim:Datetime>wrapper,xsi:nil, repeated elements).Suggested mapping:
string,char16StringbooleanBooleansint8/sint16/sint32/sint64,uint8/uint16/uint32Integer/Long(uint64→BigIntegerorLong)real32/real64Float/Doubledatetimejava.time.Instant/OffsetDateTimefor timestamps,Durationfor intervalsreferenceString(the object path)WqlRowList<T>NULL(xsi:nil="true")nullOpen questions
Not in scope
The string API stays as it is: the
|join and the empty-stringNULLare documented behavior since 2.3.00.