{"action":"created","issue":{"url":"https://api.github.com/repos/oshi/oshi5/issues/4","repository_url":"https://api.github.com/repos/oshi/oshi5","labels_url":"https://api.github.com/repos/oshi/oshi5/issues/4/labels{/name}","comments_url":"https://api.github.com/repos/oshi/oshi5/issues/4/comments","events_url":"https://api.github.com/repos/oshi/oshi5/issues/4/events","html_url":"https://github.com/oshi/oshi5/issues/4","id":395777683,"node_id":"MDU6SXNzdWUzOTU3Nzc2ODM=","number":4,"title":"Role of code generation in OSHI 5","user":{"login":"cilki","id":10459406,"node_id":"MDQ6VXNlcjEwNDU5NDA2","avatar_url":"https://avatars2.githubusercontent.com/u/10459406?v=4","gravatar_id":"","url":"https://api.github.com/users/cilki","html_url":"https://github.com/cilki","followers_url":"https://api.github.com/users/cilki/followers","following_url":"https://api.github.com/users/cilki/following{/other_user}","gists_url":"https://api.github.com/users/cilki/gists{/gist_id}","starred_url":"https://api.github.com/users/cilki/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cilki/subscriptions","organizations_url":"https://api.github.com/users/cilki/orgs","repos_url":"https://api.github.com/users/cilki/repos","events_url":"https://api.github.com/users/cilki/events{/privacy}","received_events_url":"https://api.github.com/users/cilki/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":4,"created_at":"2019-01-04T01:01:20Z","updated_at":"2019-01-04T18:38:10Z","closed_at":null,"author_association":"COLLABORATOR","body":"About 5 months ago I wrote a small program with [JavaPoet](https://www.github.com/square/javapoet) that generates the API according to a set of general definitions.\r\n\r\nFor example, the following YAML file defines a small `Nic` component:\r\n```\r\n- Nic:\r\n  - name: The interface's name\r\n      type: String\r\n  - mtu: The interface's maximum transmission unit\r\n      type: Integer\r\n  - ipv4: The interface's IPv4 addresses\r\n      type: String[]\r\n  - luid: The interface's local UID\r\n      type: Long\r\n      platforms: windows\r\n  - guid: The interface's global UID\r\n      type: String\r\n      platforms: windows\r\n  - connected: Whether the interface is connected\r\n      type: Boolean\r\n      platforms: windows\r\n...\r\n```\r\nThe 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.\r\n\r\n**Advantages to generating the API**\r\n\r\n- Generate hundreds of source files in seconds\r\n- Places the essence of OSHI into a single definition file\r\n  - Makes it easier to produce a uniform/consistent API\r\n  - Makes it easier and less error-prone to add/change features\r\n- Changes to the API itself can be propagated quickly and error-free\r\n- Allows us to relax on DRY if doing so leads to a better API\r\n- No additional runtime dependencies and integrates well with Maven\r\n\r\n**Disadvantages to generating the API**\r\n\r\n- Flexibility to add special cases to the API is lost\r\n  - Doing so goes against one of our design goals, but could be permissible once or twice\r\n  - This means that the API we come up with must be general enough to suit **every** feature\r\n- Another piece of code to write and maintain\r\n\r\nI'll update this post with any additional concerns."},"comment":{"url":"https://api.github.com/repos/oshi/oshi5/issues/comments/451529976","html_url":"https://github.com/oshi/oshi5/issues/4#issuecomment-451529976","issue_url":"https://api.github.com/repos/oshi/oshi5/issues/4","id":451529976,"node_id":"MDEyOklzc3VlQ29tbWVudDQ1MTUyOTk3Ng==","user":{"login":"dbwiddis","id":9291703,"node_id":"MDQ6VXNlcjkyOTE3MDM=","avatar_url":"https://avatars0.githubusercontent.com/u/9291703?v=4","gravatar_id":"","url":"https://api.github.com/users/dbwiddis","html_url":"https://github.com/dbwiddis","followers_url":"https://api.github.com/users/dbwiddis/followers","following_url":"https://api.github.com/users/dbwiddis/following{/other_user}","gists_url":"https://api.github.com/users/dbwiddis/gists{/gist_id}","starred_url":"https://api.github.com/users/dbwiddis/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dbwiddis/subscriptions","organizations_url":"https://api.github.com/users/dbwiddis/orgs","repos_url":"https://api.github.com/users/dbwiddis/repos","events_url":"https://api.github.com/users/dbwiddis/events{/privacy}","received_events_url":"https://api.github.com/users/dbwiddis/received_events","type":"User","site_admin":false},"created_at":"2019-01-04T18:38:10Z","updated_at":"2019-01-04T18:38:10Z","author_association":"MEMBER","body":"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."}}
{"actor":{"display_login":"dbwiddis"}}