Official definitions of common terms

[cilki]

We need to agree on some common definitions to make it easier to discuss design and write documentation. I propose the following initial set:

Term	Definition	Example
Attribute	A specific property of some aspect of the system	guid, vendor, name
Component	A POJO container for related attributes	Cpu, Gpu, ...
Index	An interface that defines all attributes of a component	CpuIndex, GpuIndexWindows
Driver	TBD

[dbwiddis]

Attribute needs not only the property, but the API "tree" to get there. For example, hardware.memory.available.

Not sure I like the term "Component" for the POJO container. While the interfaces can be names of (physical) components, I am leaning toward (in OSHI 4) the POJO containers being called *Data.

The Interfaces will be the API and should be the simple component names, rather than the "Index".

[YoshiEnVerde]

Not sure I like the term "Component" [...]
I'm sure we're talking terms only here, not how they'll be named in the implementation. Just how we'll reference them in the documentation, and in any further design conversation.

I stumbled over this issue myself while trying to give the explanation of how layers should work in #2 and #3

Just like in those issues, I have a more nuanced structure for the components in my head. I'll draw a quick diagram and share it later today.
Until then, my contributions to this:

Term	Definition	Example	My ¢2
Result	The content of any Attribute. Follows a pattern similar to Optional		These should be able to contain the resulting variable from a valid Value flowing up all the way from the Driver, if available, or error details if something goes wrong in the process
Attribute	A specific property of some aspect of the system	guid, vendor, name	I like this one, with @dbwiddis caveat of using full paths for their individual names
Endpoint	An interface that defines a container for related attributes	Processor, ProcessorWithFrequencyRates, ...	Instead of having indexes, I agree with @dbwiddis on using the API interfaces for this
Entity	A POJO container that implements one or more Endpoints	PhysicalProcessor, LogicalProcessor, ...	Any of these should correspond to a main Endpoint it implements, while maybe implementing extra minor Endpoints depending on their internals or references. Like I told @dbwiddis in #2, a LogicalProcessor would be one of the implementations of Processor, while also implementing ProcessorWithFrequencyRates and DependentOnProcessor (for having a parent PhysicalProcessor to reference)
Component	Non-POJO implementation of an underlying system element. Maps between the underlying layers and the Entities/Endpoints	PhysicalProcessorIntel, NetworkInterfaceCommon, HardDriveWindows, ...	These correspond, more or less, to the objects being output by current OSHI3
Cache	Any element, collection, or framework we'll use for caching values. No specific details, since we should use this transparently		Value refresh will be handled here
Strategy	A configurable object that knows how to effectively recover attribute values from the underlying system	MotherboardDetailsStrategyWindows, ProcessorStrategyMac, ...	These will make sure to call the corresponding drivers, handle any errors they throw, etc
Driver	A configurable low-level object that knows how to interact with a specific system service for data	WmicDriver, LinuxCommandDmiDecodeDriver, ...	These know how to handle one single service well. They are charged with calling the service, and parsing the recovered values
Value	Any value fetched and parsed by a Driver		We should strive for these to be only primitives, String, and enums

[YoshiEnVerde]

This chart would correspond to the higher level API I was proposing. If we also want a lower level API closer to the drivers, we can have a second set of Components that may, or not, have a caching layer, and work in a straight coupling with the Strategies

[YoshiEnVerde]

In that case, we're talking about building a whole second API.

And no, the drivers don't have to implement anything you don't need them to implement. Their job is only to fetch the values.

If you want timestamps, that would go wherever you're handling caching of the values.
Same with callbacks and listeners, which should happen above the caching layer.

Those are all high level concerns that should never fall in the lower layers.

---

For example, change events require some kind of threading model that will keep a constant/periodical check on the values of the system to allow you to know if something's changed.

This means implementing at least a single thread that goes through a full list of every single value of interest, requesting the drivers for the latest value (irregardless of the cache state), and comparing it to the cached values to see if an event must be triggered.

Timestamps are a bit easier: the caching solution already implements timestamps for the cached values, so you just need to keep the full cache record when requesting values, instead of just the value itself

---

Finally, AutoClosable is technically dependent on your underlying layers having an Open/Closed state of some type, that you will invoke within a single scope (no matter how big that scope is).

OSHI, in general, doesn't work that way.
More so, this would go against the whole point of having unmodifiable POJOs at the public facing side of the library, since those are set once read.

The correct thing for such a use case would be for the user to write some AutoClosableOshiWrapper that handles the auto-closable part of the request

[YoshiEnVerde]

Not saying the use cases aren't there, or interesting, just that we should focus on designing and implementing OSHI here, and leaving any high level functionalities to a separate module.

The problem with adding extra functionalities is that we start clashing with the try to be more performant part of the OSHI design.

What we can do, is build each layer of the library as a separate module (or set of modules). For example, a module with the Win Drivers, one for the Mac Drivers, one for Components, etc.

That way, adding a module with the functionality you want would be as easy as adding another module to the OSHI catalog, that depends on the Strategy/Driver level modules, and works as a standalone from the standard OSHI library

[cilki]

Sorry for completely derailing this. I'll make an issue for the driver state thing and hide the tangential comments to get back on track since this is a very important issue.

I'm curious as to what @dbwiddis thinks about your terms. The only two that bother me are strategy and entity. Strategy is just a specialized driver, so that's why I've been saying driver and generic driver. Also, strategy doesn't really suit the concept in my opinion.

[YoshiEnVerde]

No problem. We're here to design all this, so any issue is welcome, I guess.

I used Entity and Strategy because they're the more common pattern names for what I was thinking. I'll welcome any name that might be better.
Let's not forget that we're defining terms only here to be able to throw around designs and ideas without having (too many) communication failures.

In the case of Strategies, my idea would be that on OSHI3 we have multiple ways of recovering a value from the system, and we need to be able to use them.

For example, recovering some random system detail from Windows might trigger a request to WMIC, if that fails, we'll ask another Windows API, if that fails, we'll check the Register, and if that fails, we'll ask some file in the system folder.
That kind of logic flow is pretty common in OSHI3.

For such a case, we'd actually have 4 different drivers involved there:

• The WMIC Driver
• The Secondary API Driver
• The WinRegistry Driver
• The WinSysFile Driver

As such, the Strategy object would handle the flow between drivers depending on their priority, raise/throw the errors as needed, check the config for disabled drivers, etc

[dbwiddis]

I'm curious as to what @dbwiddis thinks about your terms.

Don't give me any special consideration! You're the professionals!

That said...

Result -- Agreed, we need Value (or null/NaN/flag for failure), Error details, and also a Timestamp.

Entity/Endpoint -- don't understand the example ProcessorWithFrequencyRates. This seems overly complicated.

Strategy -- ok. I prefer "Fallback Logic"

Driver -- ok. Should think about a generic "text column parsing" utility that we can use for a lot of the command line stuff that returns outputs in delimited columns, which is essentially like a "database query" equivalent.

Value -- not sure I like Enum, just return the string name for it. We expect Values to be eventually represented in JSON so generally need to follow that spec (numeric, string, arrays). Need a way to represent unsigned long (BigInteger).

[dbwiddis]

WMIC Driver

Since we're being all official with definitions let me make sure this one's clear. Windows Management Instrumentation (WMI) is the infrastructure that gives us access to a lot of data on Windows. Component Object Model (COM) is the API available to us in C (or Java via JNA) to query WMI via WMI Query Language (SQL). WMI command-line (WMIC) is a command line utility with its own syntax similar to, but unique from WQL. Early versions of OSHI used the wmic.exe command line, but that has since been replaced by WQL calls using the COM API.