← Back to branch summary

~ubuntu-branches/ubuntu/trusty/ehcache/trusty

« back to all changes in this revision

Viewing changes to src/main/java/net/sf/ehcache/Ehcache.java

  • Committer: Package Import Robot
  • Author(s): Emmanuel Bourg
  • Date: 2013-05-06 14:53:07 UTC
  • mfrom: (1.1.7) (2.1.8 sid)
  • Revision ID: package-import@ubuntu.com-20130506145307-v5bhw5yu70re00l3
Tags: 2.6.7-1
* Team upload.
* New upstream release

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/main/java/net/sf/ehcache/Ehcache.java
1
1
/**
2
 
 *  Copyright 2003-2010 Terracotta, Inc.
 
2
 *  Copyright Terracotta, Inc.
3
3
 *
4
4
 *  Licensed under the Apache License, Version 2.0 (the "License");
5
5
 *  you may not use this file except in compliance with the License.
25
25
import net.sf.ehcache.bootstrap.BootstrapCacheLoader;
26
26
import net.sf.ehcache.config.CacheConfiguration;
27
27
import net.sf.ehcache.config.NonstopConfiguration;
 
28
import net.sf.ehcache.event.CacheEventListener;
28
29
import net.sf.ehcache.event.RegisteredEventListeners;
29
30
import net.sf.ehcache.exceptionhandler.CacheExceptionHandler;
30
31
import net.sf.ehcache.extension.CacheExtension;
31
32
import net.sf.ehcache.loader.CacheLoader;
32
33
import net.sf.ehcache.search.Attribute;
33
34
import net.sf.ehcache.search.Query;
 
35
import net.sf.ehcache.search.attribute.DynamicAttributesExtractor;
34
36
import net.sf.ehcache.statistics.CacheUsageListener;
35
37
import net.sf.ehcache.statistics.LiveCacheStatistics;
36
38
import net.sf.ehcache.statistics.sampled.SampledCacheStatistics;
54
56
 * Statistics on cache usage are collected and made available through public methods.
55
57
 *
56
58
 * @author Greg Luck
57
 
 * @version $Id: Ehcache.java 4843 2011-10-15 09:04:35Z amaheshw $
 
59
 * @version $Id: Ehcache.java 6879 2013-01-17 07:54:30Z vfunshte $
58
60
 */
59
61
public interface Ehcache extends Cloneable {
60
62
 
102
104
 
103
105
 
104
106
    /**
105
 
     * Puts a collection of elements in the cache. Throws a NullPointerException if any element in the
106
 
     * collection is null. Also notifies the CacheEventListener that:
107
 
     * <ul>
108
 
     * <li>the elements were put. The puts{@link net.sf.ehcache.Ehcache#put(net.sf.ehcache.Element)} happen in batches and the notifications are thrown for every put in the
109
 
     * batch irrespective of whether the element is present in the cache or not i.e this method consider
110
 
     * each element as new entry.
111
 
     * </li>
112
 
     * </ul>
113
 
     * This operation is partially completed if any element or any key is null
114
 
     * @param elements a collection of elements to be put in the cache.
115
 
     *        If elements are Serializable it can fully participate in replication and the DiskStore.
116
 
     * @throws IllegalStateException    if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
 
107
     * Puts a collection of elements in to the cache.
 
108
     * <p>
 
109
     * This method will throw a {@code NullPointerException} if a null element or null key is encountered
 
110
     * in the collection, and a partial completion may result (as only some of the elements may have been put).
 
111
     * <p>
 
112
     * For each element that is put the registered {@code CacheEventListener}s are notified of a newly put item
 
113
     * ({@link net.sf.ehcache.event.CacheEventListener#notifyElementPut(net.sf.ehcache.Ehcache, net.sf.ehcache.Element) notifyElementPut(...)})
 
114
     * regardless of whether the individual put is a new put or an update.
 
115
     *
 
116
     * @param elements the collection of elements to be put in the cache.
 
117
     * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
117
118
     * @throws CacheException
118
119
     */
119
120
    void putAll(Collection<Element> elements) throws IllegalArgumentException, IllegalStateException,
185
186
    Element putIfAbsent(Element element) throws NullPointerException;
186
187
 
187
188
    /**
 
189
     * Put an element in the cache if no element is currently mapped to the elements key.
 
190
     *
 
191
     * @param element element to be added
 
192
     * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
 
193
     *                                    further notification to doNotNotifyCacheReplicators cache peers
 
194
     * @return the element previously cached for this key, or null if none.
 
195
     *
 
196
     * @throws NullPointerException if the element is null, or has a null key
 
197
     */
 
198
    Element putIfAbsent(Element element, boolean doNotNotifyCacheReplicators) throws NullPointerException;
 
199
 
 
200
    /**
188
201
     * Remove the Element mapped to the key for the supplied element if the value of the supplied Element
189
202
     * is equal to the value of the cached Element.
190
203
     *
198
211
    /**
199
212
     * Replace the cached element only if the current Element is equal to the supplied old Element.
200
213
     *
 
214
     * With eventual consistency two simultaneous replace operations in different nodes (or threads) can return true.
 
215
     * But at the Terracotta Server Array, only one of the operations is allowed to succeed and all competing values are invalidated,
 
216
     * eventually making the caches consistent in all nodes.
 
217
     *
201
218
     * @param old Element to be test against
202
219
     * @param element Element to be cached
203
 
     * @return true is the Element was replaced
 
220
     * @return true if the Element was replaced
204
221
     * @throws NullPointerException if the either Element is null or has a null key
205
222
     * @throws IllegalArgumentException if the two Element keys are non-null but not equal
206
223
     */
242
259
    Element get(Object key) throws IllegalStateException, CacheException;
243
260
 
244
261
    /**
245
 
     * Gets all the elements from the cache for the keys provided. Updates Element Statistics
 
262
     * Gets all the elements from the cache for the keys provided. Updates Element Statistics.
 
263
     * Returned Map may contain less or more keys if collection is modified before call completes.
246
264
     * Throws a NullPointerException if any key in the collection is null
247
265
     * <p/>
248
266
     * Note that the Element's lastAccessTime is always the time of this get.
860
878
 
861
879
 
862
880
    /**
863
 
     * DiskStore paths can conflict between CacheManager instances. This method allows the path to be changed.
864
 
     *
865
 
     * @param diskStorePath the new path to be used.
866
 
     * @throws CacheException if this method is called after the cache is initialized
867
 
     */
868
 
    void setDiskStorePath(String diskStorePath) throws CacheException;
869
 
 
870
 
    /**
871
881
     * Newly created caches do not have a {@link net.sf.ehcache.store.MemoryStore} or a {@link net.sf.ehcache.store.disk.DiskStore}.
872
882
     * <p/>
873
883
     * This method creates those and makes the cache ready to accept elements
933
943
    /**
934
944
     * Register a {@link CacheLoader} with the cache. It will then be tied into the cache lifecycle.
935
945
     * <p/>
936
 
     * If the CacheLoader is not initialised, initialise it.
 
946
     * The CacheLoader instance will be initialized when the cache itself is being initialized.
 
947
     * Should the cache already be initialized, {@link net.sf.ehcache.loader.CacheLoader#init CacheLoader.init()} will not be invoked.
 
948
     * If the loader requires initialization, the user will have to call it manually before registering it with a Cache instance
 
949
     * that's already alive
937
950
     *
938
951
     * @param cacheLoader A Cache Loader to register
 
952
     * @since While the javadoc has changed in 2.5.2, the behavior has not.
939
953
     */
940
954
    public void registerCacheLoader(CacheLoader cacheLoader);
941
955
 
953
967
    public List<CacheLoader> getRegisteredCacheLoaders();
954
968
 
955
969
    /**
 
970
     * Allows user to register a dynamic attribute extractor with a searchable cache that is dynamically indexable,
 
971
     * as indicated by its configuration. Calling this method on such a cache is optional, but doing so more than once
 
972
     * replaces previously registered extractor with the given one; i.e., there can be at most one extractor instance
 
973
     * configured for each such cache. If the cache was not configured for dynamic indexing, an exception will be thrown
 
974
     * @param extractor
 
975
     */
 
976
    public void registerDynamicAttributesExtractor(DynamicAttributesExtractor extractor);
 
977
 
 
978
    /**
956
979
     * Register the {@link CacheWriter} for this cache. It will then be tied into the cache lifecycle.
957
980
     * <p/>
958
981
     * If the {@code CacheWriter} is not initialised, initialise it.