Geomajas Community Documentation

1.3. API contract

The Geomajas project has a very strong API contract. To assure the project adheres to this contract, we have the following requirements;

  • No API classes or interfaces may be removed.

  • No API classes or interfaces may be renamed.

  • No API classes or interfaces may have their package name modified.

  • No API methods may be removed.

  • No API methods may have their signature changed.

  • No methods may be added to classes annotated using "@UserImplemented ".

  • Each class on which a "@Api" annotation is added should have a "@since" javadoc comment.

  • Each method on which a "@Api" annotation is added should have a "@since" javadoc comment.

  • Each public method which is added in a class which is annotated with "@Api(allMethods = true)", should have a "@since" javadoc comment.

The checkstyle configuration which is used for the project (which is defined in the geomajas-parent parent) tries to check the API contract. This required a api.txt file in src/main/resources which contains the API for the previous release version. The API for the compiled version is put in target/api.txt.

Note that apart from the class and method signatures, the behaviour should also remain constant (especially when documented or tested). Just keep a method and throwing NotImplementedException cannot be considered "maintaining a stable API".