|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
PojoCache.java | - | - | - | - |
|
1 | /* | |
2 | * JBoss, the OpenSource J2EE webOS | |
3 | * | |
4 | * Distributable under LGPL license. | |
5 | * See terms of license at gnu.org. | |
6 | */ | |
7 | package org.jboss.cache.pojo; | |
8 | ||
9 | import java.util.Collection; | |
10 | import java.util.Map; | |
11 | import java.util.regex.Pattern; | |
12 | ||
13 | import org.jboss.cache.Cache; | |
14 | import org.jboss.cache.pojo.notification.annotation.PojoCacheListener; | |
15 | ||
16 | /** | |
17 | * <p>Main PojoCache APIs. PojoCache is an in-memory, transactional, fine-grained, and | |
18 | * object-oriented POJO (plain old Java object) distributed cache system. It | |
19 | * differs from the traditional generic distributed cache library by operating on the | |
20 | * POJO level directly without requiring that object to be serializable. It can preserve | |
21 | * object graph relationship during replication or persistency. It also track the | |
22 | * replication via fine-grained maner, i.e., only modified fields are replicated.</p> | |
23 | * | |
24 | * @author Ben Wang | |
25 | * @since 2.0 | |
26 | */ | |
27 | public interface PojoCache | |
28 | { | |
29 | /** | |
30 | * <p>Attach a POJO into PojoCache. It will also recursively put any | |
31 | * sub-POJO into the cache system. A POJO can be the following and have the | |
32 | * consqeuences when attached:</p> <p/> <li>it is Replicable, that is, it | |
33 | * has been annotated with {@link @org.jboss.cache.pojo.annotation.Replicable} annotation (or via XML), | |
34 | * and has | |
35 | * been "instrumented" either compile- or load-time. The POJO will be mapped | |
36 | * recursively to the system and fine-grained replication will be | |
37 | * performed.</li> <li>It is Serializable. The POJO will still be stored in | |
38 | * the cache system. However, it is treated as an "opaque" object per se. | |
39 | * That is, the POJO will neither be intercepted | |
40 | * (for fine-grained operation) or object relantionship will be | |
41 | * maintained.</li> | |
42 | * <li>Neither of above. In this case, a user can specify whether it wants | |
43 | * this POJO to be stored (e.g., replicated or persistent). If not, a | |
44 | * PojoCacheException will be thrown.</li> | |
45 | * | |
46 | * @param id An id String to identify the object in the cache. To promote | |
47 | * concurrency, we recommend the use of hierarchical String separating by a | |
48 | * designated separator. Default is "/" but it can be set differently via a | |
49 | * System property, jbosscache.separator in the future release. E.g., "ben", | |
50 | * or "student/joe", etc. | |
51 | * @param pojo object to be inerted into the cache. If null, it will nullify | |
52 | * the fqn node. | |
53 | * @return Existing POJO or null if there is none. | |
54 | * @throws PojoCacheException Throws if there is an error related to the cache operation. | |
55 | */ | |
56 | Object attach(String id, Object pojo) throws PojoCacheException; | |
57 | ||
58 | /** | |
59 | * Remove POJO object from the cache. | |
60 | * | |
61 | * @param id Is string that associates with this node. | |
62 | * @return Original value object from this node. | |
63 | * @throws PojoCacheException Throws if there is an error related to the cache operation. | |
64 | */ | |
65 | Object detach(String id) throws PojoCacheException; | |
66 | ||
67 | /** | |
68 | * Return the POJO id that is associated with PojoCache. Note that if a POJO has not yet | |
69 | * attached to the cache system, it will simply return null. | |
70 | * | |
71 | * @param pojo The POJO that is attached to PojoCache. | |
72 | * @return String ID. Null if not existed. | |
73 | */ | |
74 | String getPojoID(Object pojo); | |
75 | ||
76 | /** | |
77 | * Retrieve POJO from the cache system. Return null if object does not exist in the cache. | |
78 | * Note that this operation is fast if there is already a POJO instance attached to the cache. | |
79 | * | |
80 | * @param id that associates with this node. | |
81 | * @return Current content value. Null if does not exist. | |
82 | * @throws PojoCacheException Throws if there is an error related to the cache operation. | |
83 | */ | |
84 | Object find(String id) throws PojoCacheException; | |
85 | ||
86 | /** | |
87 | * Query all managed POJO objects under the id recursively. Note that this will not return | |
88 | * the sub-object POJOs, e.g., if <em>Person</em> has a sub-object of <em>Address</em>, it | |
89 | * won't return <em>Address</em> pojo. Also note also that this operation is not thread-safe | |
90 | * now. In addition, it assumes that once a POJO is found with a id, no more POJO is stored | |
91 | * under the children of the id. That is, we don't mix the id with different POJOs. | |
92 | * | |
93 | * @param id The starting place to find all POJOs. | |
94 | * @return Map of all POJOs found with (id, POJO) pair. Return size of 0, if not found. | |
95 | * @throws PojoCacheException Throws if there is an error related to the cache operation. | |
96 | */ | |
97 | Map findAll(String id) throws PojoCacheException; | |
98 | ||
99 | /** | |
100 | * Lifecycle method to start PojoCache. | |
101 | * | |
102 | * @throws PojoCacheException | |
103 | */ | |
104 | void create() throws PojoCacheException; | |
105 | ||
106 | /** | |
107 | * Lifecycle method to start PojoCache. | |
108 | * | |
109 | * @throws PojoCacheException | |
110 | */ | |
111 | void start() throws PojoCacheException; | |
112 | ||
113 | /** | |
114 | * Lifecycle method to stop PojoCache. Note that PojoCache can be stopped and started | |
115 | * repeatedly. | |
116 | * | |
117 | * @throws PojoCacheException | |
118 | */ | |
119 | void stop() throws PojoCacheException; | |
120 | ||
121 | /** | |
122 | * Lifecycle method to destroy PojoCache. | |
123 | * | |
124 | * @throws PojoCacheException | |
125 | */ | |
126 | void destroy() throws PojoCacheException; | |
127 | ||
128 | /** | |
129 | * <p> | |
130 | * Add a PojoCache listener. A given listener instance can only be added once. | |
131 | * To have a duplicate listener simply create a new instance. | |
132 | * | |
133 | * <p> | |
134 | * The listener must be annotated with the {@link PojoCacheListener} annotation, and | |
135 | * all callback methods need to be annotated with the respective event annotations. | |
136 | * Otherwise, an exception will be thrown. | |
137 | * | |
138 | * @param listener the listener instance to register | |
139 | * @throws IllegalArgumentException if listener does not conform to annotation requirements | |
140 | * @see PojoCacheListener for examples | |
141 | */ | |
142 | void addListener(Object listener); | |
143 | ||
144 | /** | |
145 | * <p> | |
146 | * Add a PojoCache listener that will only monitor a specific ID(FQN) pattern. | |
147 | * A given listener instance can only be added once, whether or not there is | |
148 | * a pattern. To have a duplicate listener simply create a new instance. | |
149 | * | |
150 | * <p> | |
151 | * The listener must be annotated with the {@link PojoCacheListener} annotation, and | |
152 | * all callback methods need to be annotated with the respective event annotations. | |
153 | * Otherwise, an exception will be thrown. | |
154 | * | |
155 | * @param listener the listener instance to register | |
156 | * @param pattern the ID pattern for notifications of interest | |
157 | * @throws IllegalArgumentException if listener does not conform to annotation requirements | |
158 | * @see PojoCacheListener for examples | |
159 | */ | |
160 | void addListener(Object listener, Pattern pattern); | |
161 | ||
162 | /** | |
163 | * Retrieve a read-only list of listeners. | |
164 | */ | |
165 | Collection<Object> getListeners(); | |
166 | ||
167 | /** | |
168 | * Remove the specific listener. | |
169 | * | |
170 | * @param listener the listener to remove | |
171 | */ | |
172 | void removeListener(Object listener); | |
173 | ||
174 | /** | |
175 | * Obtain the underlying generic cache system. Use this for non-POJO cache operation, e.g. | |
176 | */ | |
177 | Cache<Object, Object> getCache(); | |
178 | } |
|