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  ;
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   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   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   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  [] 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  [] 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags