CacheListener


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 org.jgroups.View;
10  
11  import java.util.Map  ;
12  
13  /**
14   * A listener API where listeners can be attached to a running {@link Cache} so users can be notified of {@link Cache} events.
15   * <p/>
16   *
17   * @author <a HREF="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a>
18   * @see Cache
19   * @since 2.0.0
20   */
21  public interface CacheListener
22  {
23     public enum ModificationType
24     {
25        PUT_DATA, REMOVE_DATA, PUT_MAP
26     }
27  
28     /**
29      * Called before and after a {@link Node} is created.
30      *
31      * @param fqn     The affected Fqn
32      * @param pre     whether this notification event is before (pre=true) or after (pre=true) changes have been made to the cache.
33      * @param isLocal whether the event originated from a remote cache (isLocal=false) or locally.
34      */
35     void nodeCreated(Fqn fqn, boolean pre, boolean isLocal);
36  
37     /**
38      * Called before and after a {@link Node} is modified. Data passed in the <code>data</code> parameter can be used to
39      * determine what was modified.
40      * <p/>
41      * When called with <code>pre == true</code>, <code>data</code> is the initial state of the {@link Node} before
42      * modification.
43      * <p/>
44      * When called with <code>pre == false</code>, the contents of <code>data</code>
45      * depend on the value of <code>modType</code>:
46      * <ul>
47      * <li><b>{@link org.jboss.cache.CacheListener.ModificationType#PUT_DATA}</b>: Map contains the single key/value pair that was added or modified.</li>
48      * <li><b>{@link org.jboss.cache.CacheListener.ModificationType#REMOVE_DATA}</b>: Map contains the key/value pairs that were removed.</li>
49      * <li><b>{@link ModificationType#PUT_MAP}</b>: Map contains the new state of the {@link Node} following modification.  This map includes modified key/value
50      * pairs as well as any that were not affected.</li>
51      * </ul>
52      * <p/>
53      * Implementations interested in seeing the difference in the node data in the {@link ModificationType#PUT_MAP} case can cache the <code>data</code> map passed when
54      * <code>pre == true</code>, and then when the <code>pre == false</code> callback is received, pass the cached map and the new <code>data</code> to
55      * {@link org.jboss.cache.util.Util#diffNodeData(java.util.Map,java.util.Map)}
56      *
57      * @param fqn     Fqn of the node being modified
58      * @param pre     <code>true</code> if the modification is about to be applied, <code>false</code> if it has already been applied
59      * @param isLocal <code>true</code> if the modification originated locally, <code>false</code> if it was replicated from another cache instance in the cluster.
60      * @param modType PUT_KEY_VALUE, REMOVE_KEY_VALUE or PUT_MAP
61      * @param data    Unmodifiable {@link java.util.Map}; will not be <code>null</code>. See description above.
62      */
63     void nodeModified(Fqn fqn, boolean pre, boolean isLocal, ModificationType modType, Map  <Object  , Object  > data);
64  
65     /**
66      * Called before and after a {@link Node} is removed.  Data passed in is
67      * always an unmodifiable {@link Map} of the data in the {@link Node}.
68      * <p/>
69      * When called with pre=true, this is the initial state of the {@link Node} before
70      * removal.  When called with pre=false, this is null.
71      *
72      * @param fqn     The affected Fqn
73      * @param pre     whether this notification event is before (pre=true) or after (pre=true) changes have been made to the cache.
74      * @param isLocal whether the event originated from a remote cache (isLocal=false) or locally.
75      * @param data    an unmodifiable {@link Map} of data.
76      */
77     void nodeRemoved(Fqn fqn, boolean pre, boolean isLocal, Map  <Object  , Object  > data);
78  
79     /**
80      * Called when a {@link Node} is visisted, i.e., {@link Node#get(Object)} is called.
81      *
82      * @param fqn The affected Fqn
83      * @param pre whether this notification event is before (pre=true) or after (pre=true) changes have been made to the cache.
84      */
85     void nodeVisited(Fqn fqn, boolean pre);
86  
87     /**
88      * Called when a {@link Node} is about to be evicted or has been evicted from the
89      * in-memory cache.
90      *
91      * @param fqn     The affected Fqn
92      * @param pre     whether this notification event is before (pre=true) or after (pre=true) changes have been made to the cache.
93      * @param isLocal whether the event originated from a remote cache (isLocal=false) or locally.
94      */
95     void nodeEvicted(Fqn fqn, boolean pre, boolean isLocal);
96  
97     /**
98      * Called when a {@link Node} is loaded into memory via a {@link org.jboss.cache.loader.CacheLoader}. This is not the same
99      * as {@link #nodeCreated(Fqn,boolean,boolean)}.
100     * <p/>
101     * The data passed in is an unmodifiable {@link Map}.  If the {@link Node} is loaded but the data isn't
102     * (for example when calling {@link Node#getChildren()}) the data map is null.
103     *
104     * @param fqn  The affected Fqn
105     * @param pre  whether this notification event is before (pre=true) or after (pre=true) changes have been made to the cache.
106     * @param data an unmodifiable {@link Map} of data.
107     */
108    void nodeLoaded(Fqn fqn, boolean pre, Map  <Object  , Object  > data);
109 
110    /**
111     * Called when a {@link Node} is moved using the {@link org.jboss.cache.Cache#move(Fqn,Fqn)} API.
112     *
113     * @param from    The Fqn that is moved
114     * @param to      The new, resultant Fqn
115     * @param pre     whether this notification event is before (pre=true) or after (pre=true) changes have been made to the cache.
116     * @param isLocal whether the event originated from a remote cache (isLocal=false) or locally.
117     * @see Cache#move(Fqn,Fqn)
118     */
119    void nodeMoved(Fqn from, Fqn to, boolean pre, boolean isLocal);
120 
121    /**
122     * Called when a {@link Node} is activated.
123     *
124     * @param fqn The affected Fqn
125     * @param pre whether this notification event is before (pre=true) or after (pre=true) changes have been made to the cache.
126     */
127    void nodeActivated(Fqn fqn, boolean pre);
128 
129    /**
130     * Called when a {@link Node} is passivated.
131     *
132     * @param fqn The affected Fqn
133     * @param pre whether this notification event is before (pre=true) or after (pre=true) changes have been made to the cache.
134     */
135    void nodePassivated(Fqn fqn, boolean pre);
136 
137    /**
138     * Called when the {@link Cache} is started.
139     *
140     * @param cache a reference to the Cache
141     */
142    void cacheStarted(CacheSPI cache);
143 
144    /**
145     * Called when the {@link Cache} is stopped.
146     *
147     * @param cache a reference to the Cache
148     */
149    void cacheStopped(CacheSPI cache);
150 
151    /**
152     * Called whenever the cache is used in a cluster and the cluster topology changes (i.e., a member joins or leaves the cluster)
153     *
154     * @param new_view the new JGroups {@link org.jgroups.View} that is the result of the cluster topology change event.
155     */
156    void viewChange(View new_view);
157 }
158
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags