Getting Started

Configure your environment

If you use JetBrains IDEA

Download/build and put a plugin jar into your idea plugins directory, e.g. /plugins/MxCache-Idea-Plugin.jar.

If you are using maven

Add this to dependencies of your pom.xml:

<dependency>
 <groupId>com.magenta.mxcache</groupId>
 <artifactId>mxcache-runtime</artifactId>
 <version>2.3.0</version>
</dependency>

Add this to plugins section of your pom.xml:

<plugin>
 <groupId>com.magenta.mxcache</groupId>
 <artifactId>mxcache-mavenplugin</artifactId>
 <version>2.2.2</version>
 <executions>
   <execution>
     <goals>
       <goal>instrument</goal>
       <goal>instrument-tests</goal>
     </goals>
   </execution>
 </executions>
</plugin>

Note: do this either in project root pom or in any module you need an instrumentation for.

If you build your project without maven

In this case you will have to use dynamic instrumentation mode.

###Annotate your code Add @Cached annotation to methods that you want to apply caching for. Cached methods are subject for the following limitations:

• They should have implementation. I.e. they should not be native or abstract (note: all interface methods are effectively abstract).
• They should return a value of any type, void methods are not allowed to be cached.

Example:

String value = "Initial value";

@Cached
public String getValue() {
  String result = value;
  value = "Altered value";
  return result;
}

Now check that caching works for you:

for (int i = 0; i<5; i++) {
  System.out.println(getValue());
}

This code will output "Initial value" five times.

###Don't forget to clean your caches Usually you will need to clean your caches somehow. There is a plenty of ways to do this manually:

MxCache.getCleaner().clearCacheByClass(MyClassWithCaches.class); // cleans all copies cache of its class and all statistic cache of the class 
MxCache.getCleaner().clearCacheByInstance(instanceOfClassWithCaches); // cleans all caches of the transferred copy 
MxCache.getCleaner().clearCacheByAnnotation(MyAnnotation.class); // cleans  all caches with given annotation

You can also clean caches selectively (in this case you will have to add "group" or "tags" attribute to @Cached annotation on some of your methods):

MxCache.getCleaner().clearCacheByGroup("group name"); // cleans all caches that have the indicated group
MxCache.getCleaner().clearCacheByTag("tag name"); // cleans all caches with given tag in its tag list.
MxCache.getCleaner().clearInstanceByTag(instanceOfClassWithCaches, "tag name"); // cleans all caches of the instance with given tag in its tag list.

You may also want to use automatic dependency tracking.

Add more advanced strategies

Add this to your pom.xml:

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>  
  <!-- Replace with your preferred Guava version -->
  <version>13.0.1</version>
</dependency>

<dependency>
  <groupId>com.maxifier.mxcache</groupId>
  <artifactId>mxcache-guava-integration</artifactId>
  <version>2.3.0</version>
</dependency>

And add @UseGuava annotation to your @Cached methods (Note: @Cached is still necessary):

@Cached
@UseGuava(expireAfterWrite = 2500 /*ms*/)
public String getValue() {
  ...
}

Now check that cache expires after 2.5 seconds:

for (int i = 0; i<5; i++) {
  System.out.println(getValue());
  Thread.sleep(1000);
}

This code should output

Initial value
Initial value
Altered value
Altered value
Altered value

or something like that.