Clarify how a Cache, CacheManager and CachingProvider may be accessed / injected in a Java EE environment

[brianoliver]

We need to clarify this so that Java EE containers can correctly provide Caching resources to applications, especially using injection and/or via JNDI.

[brianoliver]

I propose that we following the approach used by JMS 2.0 in Java EE 7. This would ensure consistency with the rest of the platform. An introduction to this is here:

http://www.oracle.com/technetwork/articles/java/jms20-1947669.html

Importantly however I don't think there's a requirement on behalf of the implementors to provide this functionality. It would be up to Java EE containers to ensure that these requirements are fulfilled using the standard API implemented by implementations.

[brianoliver]

New Section on "Java EE Recommendations"

Applications deployed in a Java EE container must not bundle Java Caching Providers. It is the responsibility of
a Java EE container to provide appropriately configured Caching Providers to deployed applications. The result of
bundling Caching Providers within Java EE applications deployed in a Java EE container is undefined.

[brianoliver]

As part of detailing the integration of JCache with Java EE containers, we need to consider the following:

Injection:
The ability to inject (using CDI) CacheManagers and Caches into Session Beans, Message Driven Beans and Servlets using the javax.inject.Inject and javax.annotation.Resource annotations. eg:

@Inject
private CacheManager manager;  //inject the default CacheManager

@Resource(name = "cache/myCache")  
private Cache<K, V> cache;  //inject using the JNDI defined Cache

Importantly this requires us to define the standard JNDI naming convention for Cache Managers and Caches.

Instance Scoping:
Specifically the requirement or ability to share CacheManager and Cache instances across a series of nested calls in a Java EE container. eg: if a Servlet is injected with a Cache and then calls a Session Bean that also requires the same Cache, is the same Cache instance injected into the session bean?

The answer is yes. Sharing should occur. What is not clear however is when the Cache is closed. Unlike JMS/JDBC etc, Caches should not be closed until an application is un-deployed as doing so (early) may reduce the benefit of caching in the first place.

Transaction Scoping:
Specifically the requirement for Caches to be part of a JTA transaction (whether container-managed or bean-managed) when they are requested or injected. eg: if a Servlet starts a JTA transaction and then accesses a Session Bean that requires a Cache to be injected, the injected Cache, should the Cache be transaction scoped or session scoped?

The solution for this requirement is non-trivial. We need to consider:
i). How a transactional Cache is acquired (from what Caching Provider)
ii). What happens if a transactional Cache can't be acquired?
iii). The effect on Caching annotations (are they also transactional)?

Default Caching Providers and Cache Managers:
The definition of a Default Caching Provider (much like JMS Default Connection Factory) and Default Cache Manager.

This could be injected from a well known JNDI resource.

@Resource(name="java:comp/DefaultCachingProvider")
private CachingProvider provider;

@Resource(name="java:comp/DefaultCacheManager")
private CacheManager manager;

Configuration Through Annotations:
The ability to define CacheManager and Cache configurations using annotations.

@CacheManager(
    name="java:comp/cache/myCacheManager",
    uri="some-custom-uri",
    properties= {
        "myProperty=value",
        "myOtherProperty=otherValue"
    }
)

@CacheDefinition(
    name="java:comp/cache/mycache",
    manager="java:comp/cache/myCacheManager",
    storeByValue=true,
    keyClass=String.class,
    valueClass=MyCustomClass.class
)

Importantly, CacheManagers and Caches defined in this way must be in the java:comp, java:module, java:app, or java:global namespaces, and they typically exist for as long as the application that defines them is deployed.

Configuration Through Xml:
How to define CacheManagers and Caches using beans.xml.

[gregrluck]

Moved to JCache Next.

[Quix0r]

So how is this now done "container-generic"? Please see my ticket #397 for details (Payara currently being used).