0
# Service Provider Interface
1

2
The Caffeine JCache Service Provider Interface (SPI) provides the entry point for JSR-107 cache discovery and CacheManager creation. The `CaffeineCachingProvider` is automatically discovered through the Java ServiceLoader mechanism when using `Caching.getCachingProvider()`.
3

4
## Capabilities
5

6
### CaffeineCachingProvider
7

8
Main SPI implementation that provides JCache CachingProvider backed by Caffeine. Manages CacheManager instances and their lifecycles.
9

10
```java { .api }
11
/**
12
 * A provider that produces a JCache implementation backed by Caffeine.
13
 * Typically instantiated using Caching.getCachingProvider() which discovers
14
 * this implementation through ServiceLoader.
15
 */
16
public final class CaffeineCachingProvider implements CachingProvider {
17
    
18
    /**
19
     * Get the default cache manager using default URI, ClassLoader, and Properties
20
     * @return CacheManager instance
21
     */
22
    public CacheManager getCacheManager();
23
    
24
    /**
25
     * Get cache manager with specific URI and ClassLoader, using default Properties
26
     * @param uri the URI to identify the cache manager
27
     * @param classLoader the ClassLoader for the cache manager
28
     * @return CacheManager instance
29
     */
30
    public CacheManager getCacheManager(URI uri, ClassLoader classLoader);
31
    
32
    /**
33
     * Get cache manager with full configuration
34
     * @param uri the URI to identify the cache manager
35
     * @param classLoader the ClassLoader for the cache manager
36
     * @param properties configuration properties
37
     * @return CacheManager instance
38
     */
39
    public CacheManager getCacheManager(URI uri, ClassLoader classLoader, Properties properties);
40
    
41
    /**
42
     * Close all cache managers managed by this provider
43
     */
44
    public void close();
45
    
46
    /**
47
     * Close all cache managers associated with the specified ClassLoader
48
     * @param classLoader the ClassLoader to close cache managers for
49
     */
50
    public void close(ClassLoader classLoader);
51
    
52
    /**
53
     * Close the specific cache manager identified by URI and ClassLoader
54
     * @param uri the URI identifying the cache manager
55
     * @param classLoader the ClassLoader of the cache manager
56
     */
57
    public void close(URI uri, ClassLoader classLoader);
58
    
59
    /**
60
     * Check if the specified optional feature is supported
61
     * @param optionalFeature the feature to check
62
     * @return true if supported (only STORE_BY_REFERENCE is supported)
63
     */
64
    public boolean isSupported(OptionalFeature optionalFeature);
65
    
66
    /**
67
     * Get the default URI for this provider
68
     * @return URI based on the provider class name
69
     */
70
    public URI getDefaultURI();
71
    
72
    /**
73
     * Get the default ClassLoader for this provider
74
     * @return ClassLoader that combines context and class ClassLoaders
75
     */
76
    public ClassLoader getDefaultClassLoader();
77
    
78
    /**
79
     * Get the default properties for this provider
80
     * @return empty Properties instance
81
     */
82
    public Properties getDefaultProperties();
83
}
84
```
85

86
**Usage Examples:**
87

88
```java
89
import javax.cache.Caching;
90
import javax.cache.CacheManager;
91
import com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider;
92

93
// Automatic discovery through ServiceLoader
94
CacheManager cacheManager = Caching.getCachingProvider().getCacheManager();
95

96
// Direct instantiation
97
CaffeineCachingProvider provider = new CaffeineCachingProvider();
98
CacheManager manager = provider.getCacheManager();
99

100
// With custom URI and ClassLoader
101
URI customUri = URI.create("custom://cache-config");
102
ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
103
CacheManager customManager = provider.getCacheManager(customUri, classLoader);
104

105
// With properties
106
Properties props = new Properties();
107
props.setProperty("custom.property", "value");
108
CacheManager configuredManager = provider.getCacheManager(customUri, classLoader, props);
109

110
// Cleanup
111
provider.close();
112
```
113

114
### Supported Features
115

116
The Caffeine JCache implementation supports the following JSR-107 optional features:
117

118
```java { .api }
119
// Only STORE_BY_REFERENCE is supported
120
OptionalFeature.STORE_BY_REFERENCE // true
121
OptionalFeature.STORE_BY_VALUE     // false (but can be enabled via configuration)
122
```
123

124
### ServiceLoader Registration
125

126
The provider is automatically registered through the ServiceLoader mechanism via:
127

128
- **Service file**: `META-INF/services/javax.cache.spi.CachingProvider`
129
- **Implementation class**: `com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider`
130

131
This allows automatic discovery when using:
132

133
```java
134
// Discovers CaffeineCachingProvider automatically
135
CachingProvider provider = Caching.getCachingProvider();
136
```
137

138
### Internal ClassLoader Handling
139

140
The provider includes a custom `JCacheClassLoader` that combines multiple ClassLoader sources:
141

142
- Thread context ClassLoader
143
- Provider class ClassLoader  
144
- Parent ClassLoader
145

146
This ensures proper class resolution in various deployment environments including OSGi containers.