XML configuration

MxCache can be configured by using xml. Configuration files can be located in the following locations (all found configuration files are used):

• META-INF/mxcache.xml in application classpath (in each classloader there can be its own mxcache.xml, which is valid only on the classes loaded by this classloader and by child loaders)
• in the file specified via System.property mxcache.xml.path: -Dmxcache.xml.path="C:\MyConfig\MxCache.xml"
• in url, specified through System.property mxcache.xml.url: -Dmxcache.xml.url="http://server/mxcache.xml"
• in the file mxcache.xml of the current directory.

This file must contain a root mxcache element, containing a set of rules for the cache. Each rule is a rules tag .

The rules can have the following attributes:

• name - the name of the rule (for display in the interface);
• important - true means that the rule overrides all other rules without this attribute and annotations;
• disabled - true means that the rule will not be considered.

The rules can contain:

• One or more <selector> tags. Each of them sets a different set of caches to apply this rule.
• One or more <resourceDependency> tags. Each of them must contain the name of the resource, which all the caches, to which this rule applies, will depend on.
• The <cacheName> tag. Allows you to define the name of the cache displayed in plugins and avaliable to the strategies.
• The tag. Must contain the name of the strategy’s class that will handle all of the caches to which the rule applies. In contrast to the class names in the selector, the name of the class strategy should contain "binary name" ("Canonical name" - the name that is used in the code to access the class. In "binary name" points are used only to separate the packages. For nested classes use $: my.package.SomeClass$InnerClass$NestedClass in contrast to the canonical name my.package.SomeClass.InnerClass.nestedclass. Even the anonymous classes , that does not have a canonical name, have binary name. In the binary name of anonymous classes after the parent name is put "$" and the numeral: my.package.SomeClass$InnerClass$1. You can read more about it in JLS )
• Tag <trackDependency>. in this tag you can specify automatic resource dependency tracking mode for this cache: DEFAULT, NONE (only explicit dependencies, no automatic tracking), STATIC (caches of all instances of the class for this particular method are considered having same dependencies: if one instance has a dependency on cache X, all instances will be considered having this dependency), INSTANCE (dependencies are tracked on per-instance basis - each cache of each instance of class with this method will have distinct dependency set).
• Tag <disableCache>. If set in true, then methods to which the rule applies, will not be cached one or more tags defining the settings that can be used by strategy. Selectors Each selector specifies the set of caches to which the rule will be applied.

A selector can contain several conditions – it is necessary to fulfill all the requirements for the selector application.

Conditions:

• className - specifies the canonical name of the class in which the method should be located; if ends with "", then the condition satisfy all caches, starting with this line. For example, the condition <className>java.lang.*</className> is used only for cached methods, the class of which is in the package java.lang, and the condition of the <className>java.lang.Scanner</className> is used only for Scanner class; group - specifies the name of the group to which the cache should be related; similarly to className, you can use the "" character;
• tag - specifies the tag that must have a cache.
• annotated - specifies the canonical name of the class annotation, which must have a cache.

There may be few tag and annotation conditions in the selector, but only one class and group condition.

###Properties

Strategies properties are defined in rule tag:

 <property name="property name" value="property value" />

For properties that accepts few values at once, the values, instead of the attribute value, must be in the form of nested tags (if certain property has one element, you can set it through the attribute).

###Rules priority If a cached method is subject to multiple rules with overlapping settings,then rules overlap similar to css:

• rules defined closer to the end mxcache.xml have higher priority
• settings configured through annotation have higher priority
• strategies properties with the same name completely replace each other
• settings defined through annotations directly from the method, overlaps all the rules mxcache.xml;
• rules with important attribute="true" overlap all other settings while determining dependencyTracking, the DEFAULT value does not overlap the previously defined value (i.e. the DEFAULT value is generally ignored!);
• rules of the configuration files defined through System.property, have more weight
• rules defined through mxcache.xml in the current directory have more weight
• rules of the child class loaders have more weight
• in this list more weight have the rules defined closer to the end.

Configuration example:

<?xml version="1.0" encoding="UTF-8"?>
<mxcache>
  <rule>
    <selector>
      <tag>SomeTag</tag>
      <annotated>com.magenta.SomeAnnotation</annotated>
    </selector>
    <selector>
      <annotated>com.magenta.OtherAnnotation</annotated>
    </selector>
    <resourceDependency>SomeResource</resourceDependency>
    <strategy>com.magenta.SomeStrategy</strategy>
    <property name="SimpleProperty" value="3" />
    <property name="ArrayProperty">
      <value>SOME_ENUM</value>
      <value>OTHER_ENUM</value>
    </property>
  </rule>
</mxcache>

This rule effects all caches that have: tag SomeTag AND annotation com.magenta.SomeAnnotation; OR annotation com.magenta.OtherAnnotation.