https://github.com/marmelo/chili
Chili is a collection of Java annotations that simplify common tasks.
https://github.com/marmelo/chili
annotations cache dependency-injection guice java log memoize timeout
Last synced: 11 months ago
JSON representation
Chili is a collection of Java annotations that simplify common tasks.
- Host: GitHub
- URL: https://github.com/marmelo/chili
- Owner: marmelo
- License: mit
- Created: 2015-02-03T10:25:41.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2018-11-22T01:52:51.000Z (over 7 years ago)
- Last Synced: 2025-04-09T00:04:27.049Z (12 months ago)
- Topics: annotations, cache, dependency-injection, guice, java, log, memoize, timeout
- Language: Java
- Homepage:
- Size: 53.7 KB
- Stars: 6
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Chili
[](https://travis-ci.org/marmelo/chili)
[](http://search.maven.org/#artifactdetails|me.defying.chili|chili|1.0|jar)
[](https://github.com/marmelo/chili/blob/master/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](https://github.com/google/guice/wiki/AOP)
to process the annotations and requires JDK 1.7 or higher.
The following [annotations](#annotations) are currently implemented:
- [@Log](#log) - Log method invocation.
- [@Memoize](#memoize) - Cache the method computed result.
- [@Timeout](#timeout) - Interrupt method invocation if time limit is exceeded.
- [@ToString](#tostring) - Generate ```toString``` method automatically.
## Configuration
You can get Chili straight from Maven central repository:
```xml
me.defying.chili
chili
1.0
```
Alternatively, you may use the latest snapshot release from the Sonatype's repository (which may require additional repository configuration).
```xml
me.defying.chili
chili
1.1-SNAPSHOT
```
```xml
sonatype.oss.snapshots
Sonatype OSS Snapshot Repository
http://oss.sonatype.org/content/repositories/snapshots
false
true
```
## Usage
Are you in a hurry? Please refer to the provided [```chili-example```](https://github.com/marmelo/chili/tree/master/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](https://github.com/google/guice/wiki/Motivation).
Lets create a simple class with a [@Memoize](#memoize) annotation:
```java
public class MemoizeService {
/**
* Returns the given value raised to the power of two.
*
* @param x the base value.
* @return the value {@code x}2.
*/
@Memoize
public int power(int x) {
return x * x;
}
}
```
The [@Memoize](#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](#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:
```java
Guice.createInjector();
```
The ```createInjector``` method receives a list of modules that contain the application
[bindings](https://github.com/google/guice/wiki/Bindings). To simplify this process it
is provided a ```ChiliModule``` class with all the Chili annotations bindings configured.
```java
Guice.createInjector(new ChiliModule());
```
If your are already using Guice in you project you may add the ```ChiliModule``` next to yours.
```java
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.
```java
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```](https://github.com/marmelo/chili/tree/master/chili-example)
project for further examples.
## Annotations
#### @Log
Log method invocation with arguments, return value and execution time.
The [@Log](#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](https://en.wikipedia.org/wiki/Memoization)
for further details.
The [@Memoize](#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](#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](#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. |