Role of code generation in OSHI 5

[cilki]

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.

[cilki]

Here is the experimental generator that I wrote. I worked on a YAML version briefly, but never finished. If we decide to go this route, then the definitions file can be JSON, XML, etc...

[dbwiddis]

I would love to employ code generation for at least a portion of the code. I'll refrain from specifying JavaPoet vs. any other alternative. This would work extremely well to synchronize configuration objects (update frequency, etc.) and data objects and the API interfaces, so that adding a new feature is as simple as adding a few lines to the markup file, and then pointing it to a "driver" or whatever other source we're identifying as the calculation code -- that part we'd write ourselves without a generator, I presume.

[cilki]

as simple as adding a few lines to the markup file, and then pointing it to a "driver" or whatever other source we're identifying as the calculation code -- that part we'd write ourselves without a generator, I presume

Exactly.

There are quite a few libraries out there, but JavaPoet seems like the best choice because it's actively developed and simple to use.

[YoshiEnVerde]

I don't know if I'd use JavaPoet (or any other code generator) for most of the project, since even for something as simple as JavaPoet you're just trading POJO implementation costs with Poet implementation costs.

However, for the APIs themselves? That might be a huge resource saver.
While we'll have a bit of learning involved, for those that haven't had to use YAML for interface definitions yet, but having a nicely formatted YAML document with the APIs definitions, and have that automatically generate interfaces, facades, and javadocs? That's sounds great!

[dbwiddis]

I think we're on the same page here that we should generate the API stuff (interfaces, javadocs, POJO data objects and getters/setters, config files). We can consider generating junit tests. The actual platform implementation can have a standard "driver method" that is generated that we would then have to code up ourselves.