sebhoss/annotated-contracts

h1. annotated-contracts

h2. "!https://www.ohloh.net/p/annotated-contracts/widgets/project_thin_badge.gif!":https://www.ohloh.net/p/annotated-contracts/ "!https://secure.travis-ci.org/sebhoss/annotated-contracts.png!":http://travis-ci.org/sebhoss/annotated-contracts !https://coveralls.io/repos/sebhoss/annotated-contracts/badge.png(Coverage Status)!:https://coveralls.io/r/sebhoss/annotated-contracts !https://www.versioneye.com/user/projects/5480dd186c476742c5000461/badge.svg?style=flat(Dependency Status)!:https://www.versioneye.com/user/projects/5480dd186c476742c5000461

p. "Design by Contract":http://en.wikipedia.org/wiki/Design_by_contract based on annotations. It allows easy usage of contracts without any need for extra JVM parameters, JVM agents, special classloaders or compilers. Instead it leverages "dependency injection":http://en.wikipedia.org/wiki/Dependency_injection to capture method calls which are annotation with a contract. The project is highly flexible and can be extended to support new contract annotations and other contract clause definitions (see below).

h2. Usage

p. Contracts can only be specified on methods. The following example shows how to do it:

bc.. public class ContractExample {

@Contract(
    preconditions = {
        @Clause(value = "damage > 0", message = "Reported damage must be positive!", exception = IllegalStateException.class),
        @Clause("damage <= 5000")
    },
    postconditions = {
        @Clause("return >= 0"),
        @Clause(value = "return <= 2000", exception = NotEnoughMoneyException.class)
    })
public double calculateCover(double damage) {
    // .. some calculations
}

}

p. The above example shows a method with two pre- and postconditions. The first precondition sets the optional message and exception fields, which are used in case the contract clause was violated. In case the exception message isn't set, a default no-argument constructor is used, otherwise a constructor with a single @String@ parameter is searched. See the integration matrix below for a framework/language usage guide.

h2. Integration

p. This library offers several implementations for a variety of other libraries/frameworks. The following configuration matrix shows what is currently supported. Anything missing? "Create an issue!":https://github.com/sebhoss/annotated-contracts/issues/new:

h2. Development

h3. License

p. This program is free software. It comes without any warranty, to the extent permitted by applicable law. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See LICENSE or "http://www.wtfpl.net/":http://www.wtfpl.net/ for more details.

h3. Setup

p. This projects uses "Java":http://www.java.com/, "Maven":http://maven.apache.org/ and "Git":http://git-scm.com/ as the main development tools. To build the project yourself just download & install at least Maven 3.0 and call mvn install inside the project folder. Maven should then proceed to clean, build, package and install this project.

h3. Versioning

p. This project follows the "semantic versioning":http://semver.org/ guidelines.

h2. Alternatives

p. Not what you are looking for? Try one of the alternatives:

sebhoss / annotated-contracts

readme