Unable to pass XML configuration via JCache's "getCacheManager"

[sctincman]

When using the JCache interface, I'm unable to configure the Cache2K provider at runtime using an XML configuration via getCacheManager(URI configURI, ClassLoader classLoader).

I receive the following exception when I attempt this:

java.lang.IllegalArgumentException: Cache name contains illegal character: ':', name="file:/path/to/cache2k.xml"
	at org.cache2k.core.CacheManagerImpl.checkName(CacheManagerImpl.java:165)
	at org.cache2k.core.Cache2kCoreProviderImpl.getManager(Cache2kCoreProviderImpl.java:116)
	at org.cache2k.jcache.provider.JCacheProvider.getCacheManager(JCacheProvider.java:86) 
	at org.cache2k.jcache.provider.JCacheProvider.getCacheManager(JCacheProvider.java:119)
        ...

The culprit appears to be the JCacheProvider::getCacheManager using the URI to generate a unique cache name, however the uri2name() method it uses only performs a toString() on the URI which creates the string "protocol:path" and thus the illegal character ':' ends up in the name.

As getCacheManager(...) only accepts URIs, I do not see a way around this.

[cruftex]

To get the default cache manager, do:

 provider.getCacheManager(null, classloader, properties);

or

provider.getCacheManager(getDefaultURI(), classloader, properties);

or simply, if you don't need to specify properties or classloader:

provider.getCacheManager();

In case there is a cache2k.xml present in the class path, this will be picked up automatically.

If you want to create a different cache manager, with a different configuration, then do:

provider.getCacheManager(new URI("special"), classloader, properties);

In this case special is used as the name of the manager and the configuration is expected to be at cache2k-special.xml. There is no need for an URI to have a scheme.

Background:

There is a conceptual mismatch between the cache manager designation in cache2k and JCache. In JCache it is an URI of the configuration file, which is probably an inheritance from Gregs' EHcache. In cache2k a cache manager simply has a name, which is a string.

The reason is that I'd like the cache2k API to be open and not tied to specific concepts. The XML configuration is one way that the cache configuration is provided, but its possible to provide other mechanisms to provide the cache configuration via the service provider interface CacheConfigurationProvider.

The second reason is that I don't like an URI like file:/path/to/cache2k.xml as the id of the cache manager. The ID should be more compact. Using an URI adds additional noise e.g. to logging outputs.

I think many first time users will probably stumble here, so I try to improve documentation and the exception.

In case there are any limitations from other frameworks that require the URI to include a scheme and/or path, please let me know.

[cruftex]

I added some remarks in the documentation and improved the exception messge and just released the version 1.2.0.Final. Compared to 1.0.2.Final there are some subtle changes to the JCache setup and XML configuration in general, see: https://cache2k.org/1/2.0.Final.html

Just let me know in case you hit another obstacle. I am happy to assist.