1 /***
2 * Copyright 2003-2010 Terracotta, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.ehcache.writer;
17
18 import net.sf.ehcache.CacheEntry;
19 import net.sf.ehcache.CacheException;
20 import net.sf.ehcache.Ehcache;
21 import net.sf.ehcache.Element;
22
23 import java.util.Collection;
24
25 /***
26 * A CacheWriter is an interface used for write-through and write-behind caching to a underlying resource.
27 * <p/>
28 * If configured for a cache, CacheWriter's methods will be called on a cache operation. A cache put will cause a CacheWriter write
29 * and a cache remove will cause a writer delete.
30 * <p/>
31 * Implementers should create an implementation which handles storing and deleting to an underlying resource.
32 * <p/>
33 * <h4>Write-Through</h4>
34 * In write-through mode, the cache operation will occur and the writer operation will occur before CacheEventListeners are notified. If
35 * the write operation fails an exception will be thrown. This can result in a cache which is inconsistent with the underlying resource.
36 * To avoid this, the cache and the underlying resource should be configured to participate in a transaction. In the event of a failure
37 * a rollback can return all components to a consistent state.
38 * <p/>
39 * <h4>Write-Behind</h4>
40 * In write-behind mode, writes are written to a write-behind queue. They are written by a separate execution thread in a configurable
41 * way. When used with Terracotta Server Array, the queue is highly available. In addition any node in the cluster may perform the
42 * write-behind operations.
43 * <p/>
44 * It's important to note that the operations that are handled by the {@code CacheWriter} don't have any guaranteed ordering in write-behind mode.
45 * The processing ordering can be different than the scheduling ordering, so your application needs to be written with this
46 * in mind. More information in the CacheWriter chapter of the documentation.
47 * <p/>
48 * <h4>Creation and Configuration</h4>
49 * CacheWriters can be created using the CacheWriterFactory or explicitly by instantiating them through Java code, giving
50 * you access to local resources.
51 * <p/>
52 * The manner upon which a CacheWriter is actually called is determined by the {@link net.sf.ehcache.config.CacheWriterConfiguration} that is set up for cache
53 * that is using the CacheWriter.
54 * <p/>
55 * See the CacheWriter chapter in the documentation for more information on how to use writers.
56 *
57 * @author Greg Luck
58 * @author Geert Bevin
59 * @version $Id: CacheWriter.html 13146 2011-08-01 17:12:39Z oletizi $
60 */
61 public interface CacheWriter {
62
63 /***
64 * Creates a clone of this writer. This method will only be called by ehcache before a
65 * cache is initialized.
66 * <p/>
67 * Implementations should throw CloneNotSupportedException if they do not support clone
68 * but that will stop them from being used with defaultCache.
69 *
70 * @return a clone
71 * @throws CloneNotSupportedException if the extension could not be cloned.
72 */
73 public CacheWriter clone(Ehcache cache) throws CloneNotSupportedException;
74
75
76 /***
77 * Notifies writer to initialise themselves.
78 * <p/>
79 * This method is called during the Cache's initialise method after it has changed it's
80 * status to alive. Cache operations are legal in this method. If you register a cache writer
81 * manually after a cache has been initialised already, this method will be called on the
82 * cache writer as soon as it has been registered.
83 * <p/>
84 * Note that if you reuse cache writer instances or create a factory that returns the
85 * same cache writer instance as a singleton, your <code>init</code> method should be able
86 * to handle that situation. Unless you perform this multiple usage of a cache writer yourself,
87 * Ehcache will not do this though. So in the majority of the use cases, you don't need to do
88 * anything special.
89 *
90 * @throws net.sf.ehcache.CacheException
91 */
92 void init();
93
94 /***
95 * Providers may be doing all sorts of exotic things and need to be able to clean up on
96 * dispose.
97 * <p/>
98 * Cache operations are illegal when this method is called. The cache itself is partly
99 * disposed when this method is called.
100 */
101 void dispose() throws CacheException;
102
103 /***
104 * Write the specified value under the specified key to the underlying store.
105 * This method is intended to support both key/value creation and value update for a specific key.
106 *
107 * @param element the element to be written
108 */
109 void write(Element element) throws CacheException;
110
111 /***
112 * Write the specified Elements to the underlying store. This method is intended to support both insert and update.
113 * If this operation fails (by throwing an exception) after a partial success,
114 * the convention is that entries which have been written successfully are to be removed from the specified mapEntries,
115 * indicating that the write operation for the entries left in the map has failed or has not been attempted.
116 *
117 * @param elements the Elements to be written
118 */
119 void writeAll(Collection<Element> elements) throws CacheException;
120
121
122 /***
123 * Delete the cache entry from the store
124 *
125 * @param entry the cache entry that is used for the delete operation
126 */
127 void delete(CacheEntry entry) throws CacheException;
128
129
130 /***
131 * Remove data and keys from the underlying store for the given collection of keys, if present. If this operation fails
132 * (by throwing an exception) after a partial success, the convention is that keys which have been erased successfully
133 * are to be removed from the specified keys, indicating that the erase operation for the keys left in the collection
134 * has failed or has not been attempted.
135 *
136 * @param entries the entries that have been removed from the cache
137 */
138 void deleteAll(Collection<CacheEntry> entries) throws CacheException;
139
140 }