Contribute

To get started, sign the Contributor License Agreement.

IDE

Eclipse users will need to install either the Gradle STS plugin or official Buildship plugin (under development). These plugins support importing Gradle projects. When using the STS plugin, select Use hierarchical project names.

The project uses code generation to optimize the memory overhead for a particular cache configuration. Unfortunately the IDEs may not know, yet, to perform this task when compiling. You may need to build from the command line and reimport in order to have the generated source folders appear in the project.

gradlew build -x test

Code Format

Google's Java style should be adhered to and can be imported into Eclipse or Intellij.

Java Microbenchmark Harness

JMH benchmarks can be run using

gradlew jmh -PincludePattern=[class-name pattern]

Java Object Layout

JOL inspectors can be run using

gradlew [object-layout task] -PclassName=[class-name]

For convenience, the project's package is prepended to the supplied class name.

Static analysis

Static code analysis tasks are not enabled by default and can be run using

gradlew clean build -Dcheckstyle -Dfindbugs -Dpmd

Parameterized testing

Cache unit tests can opt into being run against all cache configurations that meet a specification constraint. A test method annotated with a configured @CacheSpec and using the CacheProvider will be executed with all possible combinations. The test case can inspect the execution configuration by accepting the CacheContext as a parameter.

Parameterized tests can take advantage of automatic validation of the cache's internal data structures to detect corruption. The CacheValidationListener is run after a successful test case and if an error is detected then the test is set with the failure information.

@Listeners(CacheValidationListener.class)
@Test(dataProviderClass = CacheProvider.class)
public final class CacheTest {

  @CacheSpec(
    keys = { ReferenceType.STRONG, ReferenceType.WEAK },
    values = { ReferenceType.STRONG, ReferenceType.WEAK, ReferenceType.SOFT },
    maximumSize = { MaximumSize.DISABLED, MaximumSize.FULL, MaximumSize.UNREACHABLE })
  @Test(dataProvider = "caches")
  public void getIfPresent_notFound(
      Cache<Integer, Integer> cache, CacheContext context) {
    // This test is run against at least 72 different cache configurations
    // (2 key types) * (3 value types) * (3 max sizes) * (4 population modes)
    assertThat(cache.getIfPresent(context.getAbsentKey()), is(nullValue());
    assertThat(cache.stats(), both(hasMissCount(1)).and(hasHitCount(0)));
  }
}