|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
CacheFactory.java | - | - | - | - |
|
1 | /* | |
2 | * JBoss, Home of Professional Open Source | |
3 | * | |
4 | * Distributable under LGPL license. | |
5 | * See terms of license at gnu.org. | |
6 | */ | |
7 | package org.jboss.cache; | |
8 | ||
9 | import net.jcip.annotations.ThreadSafe; | |
10 | import org.jboss.cache.config.Configuration; | |
11 | import org.jboss.cache.config.ConfigurationException; | |
12 | ||
13 | /** | |
14 | * This factory constructs a cache from a given or default configuration set. | |
15 | * <p/> | |
16 | * Typical usage would be: | |
17 | * <p/> | |
18 | * <pre> | |
19 | * CacheFactory factory = DefaultCacheFactory.getInstance(); | |
20 | * Cache cache = factory.createCache("replSync-service.xml"); // expects this file to be in classpath | |
21 | * cache.stop(); | |
22 | * </pre> | |
23 | * Factory methods provide options for creating a cache using | |
24 | * <ul> | |
25 | * <li>default configuration settings</li> | |
26 | * <li>an XML file containing the configuration</li> | |
27 | * <li>a constructed and populated {@link org.jboss.cache.config.Configuration} object</li> | |
28 | * </ul> | |
29 | * In addition, methods provide anadditional option to create and return a cache without starting it. | |
30 | * | |
31 | * @author <a href="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a> | |
32 | * @see org.jboss.cache.Cache | |
33 | * @see org.jboss.cache.DefaultCacheFactory | |
34 | * @see org.jboss.cache.pojo.PojoCacheFactory | |
35 | * @since 2.0.0 | |
36 | */ | |
37 | @ThreadSafe | |
38 | public interface CacheFactory<K, V> | |
39 | { | |
40 | /** | |
41 | * Creates and starts a {@link Cache} instance using default configuration settings. See {@link Configuration} for default values. | |
42 | * | |
43 | * @return a cache | |
44 | * @throws ConfigurationException if there are problems with the default configuration | |
45 | */ | |
46 | Cache<K, V> createCache() throws ConfigurationException; | |
47 | ||
48 | /** | |
49 | * Creates and optionally starts a {@link Cache} instance using default configuration settings. See {@link Configuration} for default values. | |
50 | * | |
51 | * @param start if true, starts the cache | |
52 | * @return a cache | |
53 | * @throws ConfigurationException if there are problems with the default configuration | |
54 | */ | |
55 | Cache<K, V> createCache(boolean start) throws ConfigurationException; | |
56 | ||
57 | /** | |
58 | * Creates and starts a {@link org.jboss.cache.Cache} instance. The following are all valid calls: | |
59 | * <pre> | |
60 | * factory.createCache("myCacheService.xml"); // file is in class path | |
61 | * factory.createCache("etc/myCacheService.xml"); // file is in etc/ relative to the directory you started the JVM | |
62 | * factory.createCache("/home/jbosscache/myCacheService.xml"); // file is in the /home/jbosscache directory | |
63 | * </pre> | |
64 | * | |
65 | * @param configFileName the named XML file should exist in the classpath or should be a fully qualified or relative (to your JVM working directory) path to a file on the local file system. Note that the classpath is checked first for the existence of this file. | |
66 | * @return a running {@link org.jboss.cache.Cache} instance | |
67 | * @throws org.jboss.cache.config.ConfigurationException | |
68 | * if there are problems with the configuration | |
69 | */ | |
70 | Cache<K, V> createCache(String configFileName) throws ConfigurationException; | |
71 | ||
72 | /** | |
73 | * Creates {@link Cache} instance, and optionally starts it. | |
74 | * | |
75 | * @param configFileName the named XML file should exist in the classpath or should be a fully qualified or relative (to your JVM working directory) path to a file on the local file system. Note that the classpath is checked first for the existence of this file. | |
76 | * @param start if true, the cache is started before returning. | |
77 | * @return an optionally running {@link Cache} instance | |
78 | * @throws org.jboss.cache.config.ConfigurationException | |
79 | * if there are problems with the configuration | |
80 | * @see #createCache(String) for examples on valid config file names. | |
81 | */ | |
82 | Cache<K, V> createCache(String configFileName, boolean start) throws ConfigurationException; | |
83 | ||
84 | /** | |
85 | * Creates a {@link Cache} instance based on a {@link org.jboss.cache.config.Configuration} passed in. | |
86 | * <p/> | |
87 | * Ensure that the Configuration you pass in is not used by another cache instance in the same JVM, | |
88 | * as it may be concurrently modified. Clone the configuration, if shared, using | |
89 | * {@link org.jboss.cache.config.Configuration#clone()}. | |
90 | * | |
91 | * @param configuration the {@link Configuration} object that is passed in to setCache the {@link Cache}. | |
92 | * @return a running {@link Cache} instance | |
93 | * @throws org.jboss.cache.config.ConfigurationException | |
94 | * if there are problems with the configuration | |
95 | */ | |
96 | Cache<K, V> createCache(Configuration configuration) throws ConfigurationException; | |
97 | ||
98 | /** | |
99 | * Creates {@link Cache} instance, and optionally starts it, based on a {@link org.jboss.cache.config.Configuration} passed in. | |
100 | * <p/> | |
101 | * Ensure that the Configuration you pass in is not used by another cache instance in the same JVM, | |
102 | * as it may be concurrently modified. Clone the configuration, if shared, using | |
103 | * {@link org.jboss.cache.config.Configuration#clone()}. | |
104 | * | |
105 | * @param configuration the {@link Configuration} object that is passed in to setCache the {@link Cache}. | |
106 | * @param start if true, the cache is started before returning. | |
107 | * @return an optionally running {@link Cache} instance | |
108 | * @throws org.jboss.cache.config.ConfigurationException | |
109 | * if there are problems with the configuration | |
110 | */ | |
111 | Cache<K, V> createCache(Configuration configuration, boolean start) throws ConfigurationException; | |
112 | } |
|