API:Client code/Evaluations/Java Wiki Bot Framework (JWBF)

Java Wiki Bot Framework is a Java framework, intended to make it easy to write Java bots that interact with the MediaWiki API. It handles login/logout, cookies, query continuations, and tokens, and has a range of helper methods for common tasks as well as for basic interaction with the MediaWiki API.

Particularly notable or useful features of JWBF include:
 * Designed and implemented as framework for writing bots
 * Solid codebase and a good set of features
 * Has frequently updated unit and integration tests
 * A responsive and helpful maintainer

Easy to install
No installation instructions.
 * Installation instructions are correct and easy to find

Maven Central
 * Library is packaged for installation through appropriate package library (PyPI, CPAN, npm, Maven, rubygems, etc.)

It is unusual to ship Java packages with Linux distributions.
 * Platinum standard: library is packaged for and made available through Linux distributions

Easy to understand
Intended as a framework, so exposes the lower-level API calls. Also has many helper methods.
 * Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies

In progress: Basic Queries - Fast forward branch - Exchange with Wikidata Toolkit
 * Platinum standard: makes the Wikidata API available


 * Well documented:
 * Code is commented and readable


 * Documentation is comprehensive, accurate, and easy to find
 * Javadoc is accurate but very incomplete, and also difficult to find (no online version)


 * Deprecated functions are clearly marked as such


 * Platinum standard: Documentation is understandable by a novice programmer
 * Documentation is very sparse and does not make it easier for someone new to Java to understand the structure of the JavaDoc.

Solidly written Java.
 * Code uses idioms appropriate to the language the library is written in

Easy to use

 * Has functioning, simple, and well-written code samples for common tasks
 * Demonstrates queries


 * Demonstrates edits


 * Handles API complications or idiosyncrasies so the user doesn't have to:
 * Login/logout


 * Cookies


 * Tokens


 * Query continuations
 * Uses the new  parameter for newer versions of the API.


 * Requests via https, including certificate validation
 * Test Login with override default certificate validation


 * Courteous API usage is promoted through code samples and smart defaults
 * gzip compression is used by default
 * ??? There are examples of using gzip in some of the tests ( and  ),  but it is not a default.


 * Examples show how to create and use a meaningful and unique user-agent header (as in https://meta.wikimedia.org/wiki/User-agent_policy)


 * Platinum standard: generates a unique user-agent string given name/email address/repository location


 * Efficient usage of API calls
 * API calls are combined when working in multiple namespaces, but not in other ways (combining requests for multiple titles/users/etc.)


 * Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

Easy to debug
The framework has integration tests as well. Comments include TODOs and comments like "not sure if this is the best way" Some do, others do not.
 * Contains unit tests for the longest and most frequently modified functions in the library
 * Platinum standard: Unit tests for many code paths exist and are maintained
 * Terrible hacks/instances of extreme cleverness are clearly marked as such in comments
 * Documentation links to the relevant section/subpage of the API documentation

Easy to improve
Maintainer is actively involved and helpful.
 * Library maintainers are responsive and courteous, and foster a thoughtful and inclusive community of developers and users
 * Platinum standard: Project sets clear expectations for conduct for spaces where project-related interactions occur (mailing list, IRC, repository, issue tracker). It should:
 * State desired attitudes and behaviors
 * Provide examples of unwelcome and harassing behavior
 * Specify how these expectations will be enforced

none submitted There is usually a response within 1-2 days. n/a Apache 2.0
 * Pull requests are either accepted or rejected with reason within 3 weeks (Platinum standard: 3 business days)
 * Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)
 * The library is updated and a new version is released within 3 weeks (Platinum standard: 3 business days) when breaking changes are made to the API
 * Platinum standard: library maintainers contact MediaWiki API maintainers with feedback on the API's design and function
 * Library specifies the license it is released under

=Suggested TODOs=
 * Code-related:
 * Make efficient usage of API calls easier, possibly by creating a method that combines calls for multiple items (e.g. ).
 * Default to gzip encoding in API requests.


 * Process-related:
 * Improve documentation, especially the JavaDoc. Consistently add method and class descriptions.
 * Make documentation easier to find; put the JavaDoc online, or give instructions to compile it.
 * Provide installation instructions for new users.

If these issues are addressed, Java Wiki Bot Framework will meet the gold standard and will be listed as such on API:Client code.