|
Note
|
If you are looking to use the JSR-107, aka javax.cache API, you may want to start reading
the Ehcache 3.x JSR-107 Provider page
|
|
Warning
|
This is still work in progress. while this represents the API as it exists today, the plan is to only close it down, when addressing the OSS Beta milestone. Today, the focus is on the 107 Alpha milestone, which aims at providing a TCK compliant on-heap implementation… |
CacheManager cacheManager
= newCacheManagerBuilder() /* <1> */
.withCache("preConfigured", newCacheConfigurationBuilder().buildConfig(Long.class, String.class)) /* <2> */
.build(); /* <3> */
Cache<Long, String> preConfigured = cacheManager.getCache("preConfigured", Long.class, String.class); /* <4> */
Cache<Long, String> myCache = cacheManager.createCache("myCache", /* <5> */
newCacheConfigurationBuilder().buildConfig(Long.class, String.class));
myCache.put(1L, "da one!"); /* <6> */
String value = myCache.get(1L); /* <7> */
cacheManager.removeCache("preConfigured"); /* <8> */
StandaloneCache<Long, String> standaloneCache = newCacheBuilder(Long.class, String.class).build(); /* <9> */
standaloneCache.init(); /* <10> */
cacheManager.close(); /* <11> */
standaloneCache.close(); /* <12> */-
Static method org.ehcache.CacheManagerBuilder.newCacheManagerBuilder that returns a new org.ehcache.CacheManagerBuilder instance;
-
Using the builder to register a pre-configured Cache to be create when we .build() the actual CacheManager. The first String argument is the alias to use to interact with the Cache through the CacheManager; the second argument is the org.ehcache.config.CacheConfiguration to use to configure the Cache. We use the static .newCacheConfigurationBuilder() method on org.ehcache.config.CacheConfigurationBuilder to create a default config;
-
finally, invoking .build() returns a fully instantiated and initialized CacheManager we can use.
-
We can retrieve the preConfigured aliased Cache we declared in step 2. For type-safety, we ask for both key and value types to be passed in. If these differ from the ones we expect, the CacheManager throws a ClassCastException early in the application’s lifecycle. It also guards the Cache from being polluted by random types.
-
The CacheManager can also be used to create new Cache as needed. Just as in step 2, it requires passing in an alias as well as a CacheConfiguration. The instantiated and fully initialized Cache added will be returned and/or can be accessed through the CacheManager.getCache API.
-
We can now use the newly added Cache to store and …
-
… retrieve data.
-
We can also CacheManager.remove() a given Cache. The CacheManager will not only remove it’s reference to the Cache, but will also close it. The Cache releases all locally held transient resources (such as memory). References held to this Cache become unusable.
-
A new feature of Ehcache 3.0, is the ability to create StandaloneCache instances, i.e. ones not managed by a CacheManager;
-
As there is nothing that manages them, it is up to you to StandaloneCache.init() them, prior to using them.
-
In order to release all transient resources (memory, threads, …) a CacheManager provides to Cache instances it manages, you have to invoke CacheManager.close(), which in turns closes all Cache instances known at the time.
-
In the same vein, a StandaloneCache requires you to StandaloneCache.close() it explicitly. The CacheManager.close() in step #11, didn’t affect our StandaloneCache in any way.
|
Note
|
This code example is lifted from GettingStarted#testWikiExample |
You can create a XML file to configure a CacheManager:
<config
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns='http://www.ehcache.org/v3'>
<cache alias="foo"> <!--(1)-->
<key-type>java.lang.String</key-type> <!--(2)-->
<capacity>2000</capacity> <!--(3)-->
</cache>
<cache-template name="myDefaults"> <!--(4)-->
<key-type>java.lang.Long</key-type>
<value-type>java.lang.String</value-type>
<capacity>200</capacity>
</cache-template>
<cache alias="bar" usesTemplate="myDefaults"> <!--(5)-->
<key-type>java.lang.Number</key-type>
</cache>
<cache alias="simpleCache" usesTemplate="myDefaults" /> <!--(6)-->
</config>-
Declares a
Cachealiased tofoo -
Its keys will be of type
String, as not specified the values will be of any typeObject -
Its declared to hold up to 2,000 entries before it starts evicting
-
<cache-template>elements let you create an abstract configuration that further<cache>configuration can then extend -
baris such aCache, it uses the<cache-template>namedmyDefaultsand overrides itskey-typeto a wider type. -
simpleCacheis such aCacheagain, but simply usesmyDefaultsconfiguration for its soleCacheConfiguration
Refer to the XML README file for more details on the XML format
In order to parse these XML configuration, you can use the XmlConfiguration type as so:
final URL myUrl = this.getClass().getResource("/my-config.xml"); // (1)
Configuration xmlConfig = new XmlConfiguration(myUrl); // (2)
CacheManager myCacheManager = CacheManagerBuilder.newCacheManager(xmlConfig); // (3)-
Obtain a
URLto your XML file’s location -
Instantiate a
XmlConfigurationpassing the XML file’s URL to it -
Using the static
org.ehcache.CacheManagerBuilder.newCacheManager(org.ehcache.config.Configuration)lets you create yourCacheManagerinstance using theConfigurationfrom theXmlConfiguration
We currently have two main milestones planned, probably work leading into early next year until we have a GA release available. But here’s how we are splitting the work:
-
107 Alpha (on going): This is all the work to get a JSR-107 compliant on-heap implementation of the new Ehcache 3.0 line. The idea being to lay the ground work for the future work, knowing we pass the TCK and maintain that set of test passing as we move forward in the next milestone. Even though the focus is on 107, we still want to have our decisions as we move along have the future work in mind.
-
OSS Beta (coming up next): All the work to get all the features we want to port from the existing Ehcache 2.x line, exposed using the new API. This includes things not covered by the 107 spec, such as WriteBehind, DiskPersistence, EvictionListener et al.
Additional tasks, as they come up, would only be targeted to the 107 Alpha milestone, only if implementing it would mean not being able to pass the 107 TCK. Any other task gets assigned to OSS Beta.
See the milestones on github for more details on the current status.