View Javadoc

1   package org.apache.jcs.engine.behavior;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.io.IOException;
23  import java.io.Serializable;
24  
25  import org.apache.jcs.engine.stats.behavior.IStats;
26  
27  /***
28   * Interface for a cache event queue. An event queue is used to propagate
29   * ordered cache events to one and only one target listener.
30   */
31  public interface ICacheEventQueue
32  {
33      /***
34       * Initializes the queue.
35       * <,p>
36       * @param listener
37       * @param listenerId
38       * @param cacheName
39       * @param maxFailure
40       * @param waitBeforeRetry
41       * @param threadPoolName
42       */
43      public void initialize( ICacheListener listener, long listenerId, String cacheName, int maxFailure,
44                              int waitBeforeRetry, String threadPoolName );
45      
46      /***
47       * Does not use a thread pool.
48       */
49      public static final String SINGLE_QUEUE_TYPE = "SINGLE";
50  
51      /***
52       * Uses a thread pool
53       */
54      public static final String POOLED_QUEUE_TYPE = "POOLED";
55      
56  
57      /***
58       * Return the type of event queue we are using, either single or pooled.
59       * <p>
60       * @return the queue type: single or pooled
61       */
62      public abstract String getQueueType();
63  
64      /***
65       * Adds a feature to the PutEvent attribute of the ICacheEventQueue object
66       * <p>
67       * @param ce
68       *            The feature to be added to the PutEvent attribute
69       * @throws IOException
70       */
71      public void addPutEvent( ICacheElement ce )
72          throws IOException;
73  
74      /***
75       * Adds a feature to the RemoveEvent attribute of the ICacheEventQueue
76       * object
77       * <p>
78       * @param key
79       *            The feature to be added to the RemoveEvent attribute
80       * @throws IOException
81       */
82      public void addRemoveEvent( Serializable key )
83          throws IOException;
84  
85      /***
86       * Adds a feature to the RemoveAllEvent attribute of the ICacheEventQueue
87       * object
88       * <p>
89       * @throws IOException
90       */
91      public void addRemoveAllEvent()
92          throws IOException;
93  
94      /***
95       * Adds a feature to the DisposeEvent attribute of the ICacheEventQueue
96       * object
97       * <p>
98       * @throws IOException
99       */
100     public void addDisposeEvent()
101         throws IOException;
102 
103     /***
104      * Gets the listenerId attribute of the ICacheEventQueue object
105      *
106      * @return The listenerId value
107      */
108     public long getListenerId();
109 
110     /*** Description of the Method */
111     public void destroy();
112 
113     /***
114      * Gets the alive attribute of the ICacheEventQueue object. Alive just
115      * indicates that there are active threads. This is less important that if
116      * the queue is working.
117      * <p>
118      * @return The alive value
119      */
120     public boolean isAlive();
121 
122     /***
123      * A Queue is working unless it has reached its max failure count.
124      * <p>
125      * @return boolean
126      */
127     public boolean isWorking();
128 
129     /***
130      * Returns the number of elements in the queue.  If the queue cannot
131      * determine the size accurately it will return 1.
132      * <p>
133      * @return number of items in the queue.
134      */
135     public int size();
136 
137     /***
138      * Are there elements in the queue.
139      * <p>
140      * @return true if there are stil elements.
141      */
142     public boolean isEmpty();
143 
144     /***
145      * Returns the historical and statistical data for an event queue cache.
146      * <p>
147      * @return IStats
148      */
149     public IStats getStatistics();
150 }