KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jboss > cache > invalidation > InvalidationGroup


1 /*
2 * JBoss, Home of Professional Open Source
3 * Copyright 2005, JBoss Inc., and individual contributors as indicated
4 * by the @authors tag. See the copyright.txt in the distribution for a
5 * full listing of individual contributors.
6 *
7 * This is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU Lesser General Public License as
9 * published by the Free Software Foundation; either version 2.1 of
10 * the License, or (at your option) any later version.
11 *
12 * This software is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this software; if not, write to the Free
19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21 */

22 package org.jboss.cache.invalidation;
23
24 import java.io.Serializable JavaDoc;
25
26 /**
27  * An InvalidationGroup (IG) is the meeting point of all caches and invaliders
28  * working for the same cached information.
29  * For example, two entity beans based
30  * on the same database information will share their cache invalidation so that
31  * a modification performed on the bean of one of the deployed EJB will imply
32  * a cache invalidation in the cache of the other EJB.
33  * In this case, we say that both EJBs work in the same InvalidationGroup.
34  * @see InvalidationManagerMBean
35  * @author <a HREF="mailto:sacha.labourey@cogito-info.ch">Sacha Labourey</a>.
36  * @version $Revision: 37459 $
37  *
38  * <p><b>Revisions:</b>
39  *
40  * <p><b>21 septembre 2002 Sacha Labourey:</b>
41  * <ul>
42  * <li> First implementation </li>
43  * </ul>
44  */

45
46 public interface InvalidationGroup
47 {
48    /**
49     * Return the name (i.e. identifier) of the current IG
50     * @return Name of the current IG
51     */

52    public String JavaDoc getGroupName ();
53    
54    /**
55     * Invalidate a single key in all caches associated with this IG
56     * @param key The key to be invalidated
57     */

58    public void invalidate (Serializable JavaDoc key);
59    
60    /**
61     * Invalidate a single key in all caches associated with this IG specifying a
62     * prefered invalidation mode (synchronous vs. asynchronous)
63     * @param key The key to be invalidated in the cache
64     * @param asynchronous if true, the invalidation will be, if possible, performed asynchronously
65     */

66    public void invalidate (Serializable JavaDoc key, boolean asynchronous);
67    
68    /**
69     * Invalidate a set of keys in all caches associated with this IG
70     * @param keys Set of keys to be invalidated
71     */

72    public void invalidate (Serializable JavaDoc[] keys);
73
74    /**
75     * Invalidate a set of keys in all caches associated with this IG specifying a
76     * prefered invalidation mode (synchronous vs. asynchronous)
77     * @param keys keys to be invalidated
78     * @param asynchronous if true, the invalidation will be, if possible, performed asynchronously
79     */

80    public void invalidate (Serializable JavaDoc[] keys, boolean asynchronous);
81
82    /**
83     * All entries in all the caches associated with this invalidation group should be invalidated.
84     */

85    public void invalidateAll();
86
87    /**
88     * All entries in all the caches associated with this invalidation group should be invalidated
89     * using specified mode.
90     */

91    public void invalidateAll(boolean asynchronous);
92    
93    /**
94     * Used to know when to definitively remove this IG. Every component using this IG
95     * must increment the counter, otherwise, the group may be dropped while they are still
96     * using it. Exceptions:
97     * - When calling InvalidationManager.getInvalidationGroup, the counter is automatically
98     * called. Consequently, code accessing this IG through this mean must not call
99     * addReference. Nevertheless, they *must* still call removeReference
100     * appropriatly
101     * - When calling InvalidationGroup.unregister, the counter is automatically
102     * decreased
103     *
104     * Consequenlty, users such as cache generally don't need to increment or decrement
105     * the reference count because it is automatically done while getting access to the
106     * InvalidationGroup and unsubscribing. Invaliders do need to correctly unsubscribe.
107     *
108     * When the reference count drops to 0, the group is removed from the Manager
109     * Thus, any active user of this group should appropriatly increment the reference
110     * count. Passive listener (JMS/JG bridge for example) should not subscribe.
111     */

112    public void addReference ();
113    
114    /**
115     * Decrease the usage counter. When the counter drops to 0, the group is removed.
116     */

117    public void removeReference ();
118    
119    /**
120     * Return the value of the usage counter for this IG.
121     * @return Actual usage counter
122     */

123    public int getReferenceCount ();
124
125    /**
126     * Register an Invalidatable instance has a subscriber of this InvalidationGroup.
127     * @param registered Subscribing instance
128     */

129    public void register (Invalidatable registered);
130    
131    /**
132     * Unregister an Invalidatable instance
133     * @param registered Unsubscribing instance
134     */

135    public void unregister (Invalidatable registered);
136    
137    /**
138     * Set the default mode for managing invalidations in this IG: synchronous or
139     * asynchronous.
140     * Note: this is a best effort setting.
141     * @param async If true, asynchronous communication should be used if possible.
142     */

143    public void setAsynchronousInvalidation (boolean async);
144    
145    /**
146     * Return the default (a-)synchronous communication scheme used
147     */

148    public boolean getAsynchronousInvalidation ();
149
150    /**
151     * Return the InvalidationManager (IM) to which is linked this group (IG)
152     */

153    public InvalidationManagerMBean getInvalidationManager ();
154    
155 }
156
Popular Tags