oshi / oshi6 Goto Github PK

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

Early in OSHI's development, the code was littered with UnsupportedOperationExceptions. This seems an appropriate response when we're asking for data that simply doesn't exist (e.g., load average on Windows). But it requires the user to explicitly handle these exceptions.

I moved away from exceptions into log messages, which allowed a more finely grained control of what was a normal problem vs. failure (warnings vs. errors etc.) and just returned sensible defaults (negative values, or 0, or empty strings, or empty collections). This introduces the opposite problem, of not allowing the user to handle exception types.

OSHI needs a standardized method of handling these types of situations:

• Data is undefined on a platform (Windows load avg.)
• Data is not easily obtained on a platform (Windows open files)
• Data requires elevated permissions and/or software installs that the user doesn't have (lots of Linux stuff)
• Data should normally return but happened to fail in this case (Sensor readings) but the user can try again
• Data wasn't updated because you asked for it too recently (tick counts < 1 second apart).

We can use Optional results in key places, or encapsulate the result in our own OshiResult class that includes:

• Result object
• Result type (similar to how VARIANT is used in JNA)
• Result timestamp
• Result error value/enum/etc.

For this version, now that we'll start decoupling the fetching, the caching, and the API - plus the implementation of a more standard vs specialized set of APIs -, we should start looking into setting a mechanism (or two) for configuring OSHI.

Linux serial number, for example, requires user cooperation (elevated permissions for user or a file, or a software package). What do we return?

There are a few places in the code where we have "fallback" sensible defaults. Should we flag that these are different due to a permissions issue?

From oshi/oshi#427

I am more than happy to test in more places and on more systems. I have very little time to figure out how to set it all up myself! Can you help set it up?

I can do it and I can probably host it at my house. It's just a matter of finding suitable, inexpensive hardware and identifying what the test environments need to be. I think ideally we would want a few bare metal setups in certain cases (specifically for testing battery/power states), a raspberry pi, and VMs for the rest. Maybe we can setup a gofundme or something for getting hardware.

Since we'll know exactly what the hardware (either real or virtual), then we can try unit tests that only run on that specific environment and confirm exact values for the configuration. It would go a long way in terms of confirm accurate measurements and operating system compatibility.

So if i host it, it will not be publicly accessible however it will have its own github account and will add comments to pull requests based on test results (i think).

Finally, as an added bonus, I actually want to setup something for some of my other android projects.

Another thought is if this code base is donated to the apache software foundation, i know they have both a large jenkins cluster and buildbot configurations available with a variety of operating systems. There's a lot of benefits to it and then i wouldn't have to manage a bunch of miscellaneous hardware

I've been thinking on this strongly for a while.
Between issues like #310, and the kind of issues that keep cropping up (specially when asking for new features), I can't help but think that OSHI's model is starting to become a bit of a Frankenstein's monster...

Right now, it's not strange to have somebody ask for a feature only available in a single platform, and OSHI ending up with an extra feature on that platform alone.
In direct opposition, however, the current model will abstract or rename things in some platforms to have them fall in line with another platform.

As far as I can see, we have a few model/design details that need to be addressed:

1. We need a consolidated model across all platforms
2. We need to keep the API as far away from the non-consolidated parts as possible
3. We need a better way of recovering and updating the system info

I'm opening this issue to follow a converstion that started on #7:
OSHI having the ability to add event handlers to things like changes in values, errors in drivers, etc.

This was brought up by @cilki , and I responded that we should avoid such things in the standard library, to avoid the impact of the extra functionalities to performance, when it's not part of the base requirements of the OSHI library.

My idea for this follows from another idea that we should split the different layers of OSHI5 into separate modules. If so, we can implement multiple OSHI libraries, that connect at different levels with the base modules.

Like every library, OSHI needs a solid set of unit tests for the api. With the Driver design pattern, a mock driver can be created that returns configurable values with configurable timings. This should be sufficient for thoroughly testing the api and caching layers.

Testing the drivers (platform testing) will require some additional infrastructure. Travis CI isn't a good fit for this kind of testing because they only have a few images. The platform tests should ideally be run on every architecture of every major OS family and distribution. So that's like 60+ (virtual) machines at least. This is likely to take a long time which is another reason why platform testing should be separate from unit testing.

Docker could reduce the burden for Linux testing, but the sandbox effect may also reduce the benefit of testing on a container. The same could also be said (to a lesser degree I think) for virtual machines.

Most projects wouldn't bother with testing on so many platforms, but I argue that this is important for OSHI considering its purpose.

the way the driver works should not reflect on the way the API works, since the whole point of a Driver Pattern is to abstract such concerns from the API

The only problem is, how can you determine when to release a driver's resources without a cue from a higher layer? Making the lowest layer stateful introduces a session-like architecture to the higher layers.

Originally posted by @cilki in #7 (comment)

Hi,
If you are planning to implement handlings which might require an elevated privilege using machines credentials, you can also check whether querying remote machine is viable.
I know this is out of scope for oshi, but adding this feature might be a booster for oshi.
Thanks.

I'm finding a lot more API imporovements/adjustments that I want to make, and foresee an OSHI 5 release long before I expect to see this new project released. I wanted to give a heads up that we might not want to put a specific number on this future redesign/release.

About 5 months ago I wrote a small program with JavaPoet that generates the API according to a set of general definitions.

For example, the following YAML file defines a small Nic component:

- Nic:
  - name: The interface's name
      type: String
  - mtu: The interface's maximum transmission unit
      type: Integer
  - ipv4: The interface's IPv4 addresses
      type: String[]
  - luid: The interface's local UID
      type: Long
      platforms: windows
  - guid: The interface's global UID
      type: String
      platforms: windows
  - connected: Whether the interface is connected
      type: Boolean
      platforms: windows
...

The program produced the API component and the interface for the driver (which I call the Index) along with proper JavaDoc on everything. I'm confident that JavaPoet can generate just about any kind of API we come up with, so the question is whether it's a good fit for the project.

Advantages to generating the API

• Generate hundreds of source files in seconds
• Places the essence of OSHI into a single definition file
  • Makes it easier to produce a uniform/consistent API
  • Makes it easier and less error-prone to add/change features
• Changes to the API itself can be propagated quickly and error-free
• Allows us to relax on DRY if doing so leads to a better API
• No additional runtime dependencies and integrates well with Maven

Disadvantages to generating the API

• Flexibility to add special cases to the API is lost
  • Doing so goes against one of our design goals, but could be permissible once or twice
  • This means that the API we come up with must be general enough to suit every feature
• Another piece of code to write and maintain

I'll update this post with any additional concerns.