Skip to content
Chili is a collection of Java annotations that simplify common tasks.
Java
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
chili-example
chili
.gitignore
.travis.yml
LICENSE
README.md
pom.xml

README.md

Chili

Build Status Maven Central License

Chili is a collection of Java annotations that simplify common tasks.

These annotations allow to dynamically alter the functionality of class methods without changing their implementation. Chili relies on Guice AOP to process the annotations and requires JDK 1.7 or higher.

The following annotations are currently implemented:

  • @Log - Log method invocation.
  • @Memoize - Cache the method computed result.
  • @Timeout - Interrupt method invocation if time limit is exceeded.
  • @ToString - Generate toString method automatically.

Configuration

You can get Chili straight from Maven central repository:

<dependency>
  <groupId>me.defying.chili</groupId>
  <artifactId>chili</artifactId>
  <version>1.0</version>
</dependency>

Alternatively, you may use the latest snapshot release from the Sonatype's repository (which may require additional repository configuration).

<dependency>
  <groupId>me.defying.chili</groupId>
  <artifactId>chili</artifactId>
  <version>1.1-SNAPSHOT</version>
</dependency>
<repositories>
  <repository>
    <id>sonatype.oss.snapshots</id>
    <name>Sonatype OSS Snapshot Repository</name>
    <url>http://oss.sonatype.org/content/repositories/snapshots</url>
    <releases>
      <enabled>false</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

Usage

Are you in a hurry? Please refer to the provided chili-example project.

To use Chili annotations you only need to perform three steps:

  1. Add annotations to your code;
  2. Create a Guice Injector registering a ChiliModule instance;
  3. Compile and run your project.

Not acquainted with Guice? Please read its documentation.

Lets create a simple class with a @Memoize annotation:

public class MemoizeService {

    /**
     * Returns the given value raised to the power of two.
     *
     * @param x the base value.
     * @return the value {@code x}<sup>2</sup>.
     */
    @Memoize
    public int power(int x) {
        return x * x;
    }
}

The @Memoize annotation will store the method results and return them when the same inputs occur again. That is, if we call multiple times the power method with the same argument it will only perform the calculation the first time and return cached results in the next invocations.

Nevertheless, the @Memoize annotation alone produces no effect. We need to introduce a Guice Injector to intercept the method invocation and inject new meaning to it.

To create an empty Injector you only need to write:

Guice.createInjector();

The createInjector method receives a list of modules that contain the application bindings. To simplify this process it is provided a ChiliModule class with all the Chili annotations bindings configured.

Guice.createInjector(new ChiliModule());

If your are already using Guice in you project you may add the ChiliModule next to yours.

Guice.createInjector(new MyExistingModule(), new ChiliModule());

Now that you have created the Injector you need to use it to inject the annotation bindings into your code.

public class MemoizeExample {

    public static void main(String[] args) {
        // create the injector
        Injector injector = Guice.createInjector(new ChiliModule());

        // create an injected instance of the service
        MemoizeService service = injector.getInstance(MemoizeService.class);

        // cache miss
        service.power(3);

        // cache hit
        service.power(3);
    }
}

Please refer to the chili-example project for further examples.

Annotations

@Log

Log method invocation with arguments, return value and execution time.

The @Log annotation accepts the following elements:

Element Type Default Description
level LogLevel INFO Log level to be used. Possible values are TRACE, DEBUG, INFO, WARNING and ERROR.

@Memoize

Stores results of expensive function calls and returns the cached result when the same inputs occur again. Please refer to Wikipedia for further details.

The @Memoize annotation accepts the following elements:

Element Type Default Description
size long 0L Maximum entries the cache may have.
time long 0L For how long the method invocation should be cached according to the unit value. If unspecified or equal to zero the cache will not be time bound.
unit TimeUnit MILLISECONDS The TimeUnit the time value refers to.
statistics boolean false Whether or not cache statistics should be logged.

When the size and time values are active, both are enforced.

@Timeout

Interrupts method invocation if time limit is exceeded. When time is exceeded invocation is interrupted and a TimeoutException exception is thrown.

The @Timeout annotation accepts the following elements:

Element Type Default Description
time long 0L For how long the method invocation should be time limited according to the unit value. If unspecified or equal to zero the method will not be time bound.
unit TimeUnit MILLISECONDS The TimeUnit the time value refers to.

@ToString

Generate toString method automatically including all or some class fields.

The @ToString annotation accepts the following elements:

Element Type Default Description
fields String[] {} List of class fields to include in the toString generation. If empty, all class fields will be included. Unknown fields will be silently ignored.
You can’t perform that action at this time.