001package org.cache2k;
002
003/*
004 * #%L
005 * cache2k API
006 * %%
007 * Copyright (C) 2000 - 2016 headissue GmbH, Munich
008 * %%
009 * Licensed under the Apache License, Version 2.0 (the "License");
010 * you may not use this file except in compliance with the License.
011 * You may obtain a copy of the License at
012 * 
013 *      http://www.apache.org/licenses/LICENSE-2.0
014 * 
015 * Unless required by applicable law or agreed to in writing, software
016 * distributed under the License is distributed on an "AS IS" BASIS,
017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
018 * See the License for the specific language governing permissions and
019 * limitations under the License.
020 * #L%
021 */
022
023import org.cache2k.configuration.Cache2kConfiguration;
024import org.cache2k.spi.Cache2kExtensionProvider;
025import org.cache2k.spi.Cache2kCoreProvider;
026import org.cache2k.spi.SingleProviderResolver;
027
028import java.io.Closeable;
029import java.util.Properties;
030import java.util.ServiceLoader;
031
032/**
033 * A cache manager holds a set of caches. Caches within a cache manager share the
034 * same class loader and may have a different default configuration. If a cache manager
035 * is not specified a default manager is used.
036 *
037 * <p>Cache managers are identified by a unique name. If no name is specified the name
038 * {@code "default"} is used. The default name in use may be changed, see {@link #setDefaultName(String)}.
039 *
040 * @author Jens Wilke
041 */
042public abstract class CacheManager implements Closeable {
043
044  static protected final Cache2kCoreProvider PROVIDER;
045
046  static {
047    PROVIDER = SingleProviderResolver.resolveMandatory(Cache2kCoreProvider.class);
048    ServiceLoader<Cache2kExtensionProvider> _loader =
049      ServiceLoader.load(Cache2kExtensionProvider.class, CacheManager.class.getClassLoader());
050    for (Cache2kExtensionProvider p : _loader) {
051      p.registerCache2kExtension();
052    }
053  }
054
055  /**
056   * Name of the default cache manager, which is "default" by default.
057   */
058  public static String getDefaultName() {
059    return PROVIDER.getDefaultManagerName(PROVIDER.getDefaultClassLoader());
060  }
061
062  /**
063   * Change the default manager name. The method can only be called once early in application startup,
064   * before the default manager instance is requested.
065   *
066   * <p>It is also possible to set a different default manager name via JNDI context
067   * "java:comp/env" and name "org.cache2k.CacheManager.defaultName" or via the XML configuration.
068   *
069   * <p>The allowed characters in a manager name are identical to the characters in a cache name, this is
070   * documented at {@link Cache2kBuilder#name(String)}
071   *
072   * @see Cache2kBuilder#name(String)
073   */
074  public static void setDefaultName(String managerName) {
075    PROVIDER.setDefaultManagerName(PROVIDER.getDefaultClassLoader(), managerName);
076  }
077
078  /**
079   * Get the default cache manager for the default class loader. The default class loader
080   * is the class loader used to load the cache2k implementation classes.
081   */
082  public static CacheManager getInstance() {
083    ClassLoader _defaultClassLoader = PROVIDER.getDefaultClassLoader();
084    return PROVIDER.getManager(_defaultClassLoader, PROVIDER.getDefaultManagerName(_defaultClassLoader));
085  }
086
087  /**
088   * Get the default cache manager for the specified class loader.
089   */
090  public static CacheManager getInstance(ClassLoader cl) {
091    return PROVIDER.getManager(cl, PROVIDER.getDefaultManagerName(cl));
092  }
093
094  /**
095   * Retrieve a cache manager with the specified name. If not existing, a manager with that name
096   * is created. The default class loader is used. The default class loader
097   * is the class loader used to load the cache2k implementation classes.
098   *
099   * <p>The allowed characters in a manager name are identical to the characters in a cache name, this is
100   * documented at {@link Cache2kBuilder#name(String)}
101   *
102   * @see Cache2kBuilder#name(String)
103   */
104  public static CacheManager getInstance(String managerName) {
105    return PROVIDER.getManager(PROVIDER.getDefaultClassLoader(), managerName);
106  }
107
108  /**
109   * Retrieve a cache manager with the specified name using the specified classloader.
110   * If not existing, a manager with that name is created. Different cache managers are
111   * created for different class loaders. Manager names should be unique within one VM instance.
112   *
113   * <p>The allowed characters in a manager name are identical to the characters in a cache name, this is
114   * documented at {@link Cache2kBuilder#name(String)}
115   *
116   * @see Cache2kBuilder#name(String)
117   */
118  public static CacheManager getInstance(ClassLoader cl, String managerName) {
119    return PROVIDER.getManager(cl, managerName);
120  }
121
122  /**
123   * Close all cache managers.
124   */
125  public static void closeAll() {
126    PROVIDER.close();
127  }
128
129  /**
130   * Close all cache manager associated with this class loader.
131   */
132  public static void closeAll(ClassLoader cl) {
133    PROVIDER.close(cl);
134  }
135
136  /**
137   * Close the named cache manager.
138   */
139  public static void close(ClassLoader cl, String name) {
140    PROVIDER.close(cl, name);
141  }
142
143  /**
144   * True if this is the default manager of the application, returned by {@link #getInstance()}
145   */
146  public abstract boolean isDefaultManager();
147
148  /**
149   * The name to uniquely identify the manager within a VM instance.
150   *
151   * @see CacheManager#getInstance(String)
152   */
153  public abstract String getName();
154
155  /**
156   * Returns all caches created in this cache manager instance.
157   */
158  public abstract Iterable<Cache> getActiveCaches();
159
160  /**
161   * Return a known cache that must be created before via the {@link Cache2kBuilder}
162   * or {@link #createCache(Cache2kConfiguration)}
163   */
164  public abstract <K,V> Cache<K,V> getCache(String name);
165
166  /**
167   * Create a new cache from the configuration. The recommended way is to use the {@link Cache2kBuilder}
168   * to create a new cache. This method is identical to and a shorthand to:
169   *
170   * <pre>{@code
171   *    CacheManager manager = ...
172   *    Cache2kConfiguration<K,V> config = ...
173   *    Cache<K,V> cache = Cache2kBuilder.of(config).manager(manager).build();
174   * }</pre>
175   *
176   */
177  public abstract <K,V> Cache<K,V> createCache(Cache2kConfiguration<K, V> cfg);
178
179  /** Clear all currently active caches in this cache manager */
180  public abstract void clear();
181
182  /**
183   * @deprecated Use {@link #close()}
184   */
185  public abstract void destroy();
186
187  /**
188   * Free all resources from managed caches. Same as calling all {@link org.cache2k.Cache#close()} methods.
189   * A closed manager cannot be use the create new caches. A new instance of the same name may be requested
190   * via {@link #getInstance(String)}.
191   *
192   * <p>Multiple calls to close have no effect.
193   */
194  public abstract void close();
195
196  /**
197   *
198   * @deprecated use {@link #isClosed()}
199   */
200  public abstract boolean isDestroyed();
201
202  /**
203   * Returns true if this cache manager was closed.
204   *
205   * @see #close()
206   */
207  public abstract boolean isClosed();
208
209  /**
210   * Properties for the cache manager, never null. By default the properties are empty.
211   * Cache clients may store arbitrary information.
212   */
213  public abstract Properties getProperties();
214
215  /**
216   * Class loader this manager is using to load additional classes, resources or configuration.
217   */
218  public abstract ClassLoader getClassLoader();
219
220}