001package org.apache.commons.jcs.engine.behavior; 002 003import java.io.IOException; 004 005/* 006 * Licensed to the Apache Software Foundation (ASF) under one 007 * or more contributor license agreements. See the NOTICE file 008 * distributed with this work for additional information 009 * regarding copyright ownership. The ASF licenses this file 010 * to you under the Apache License, Version 2.0 (the 011 * "License"); you may not use this file except in compliance 012 * with the License. You may obtain a copy of the License at 013 * 014 * http://www.apache.org/licenses/LICENSE-2.0 015 * 016 * Unless required by applicable law or agreed to in writing, 017 * software distributed under the License is distributed on an 018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 019 * KIND, either express or implied. See the License for the 020 * specific language governing permissions and limitations 021 * under the License. 022 */ 023 024import org.apache.commons.jcs.engine.stats.behavior.IStats; 025 026/** 027 * Interface for a cache event queue. An event queue is used to propagate 028 * ordered cache events to one and only one target listener. 029 */ 030public interface ICacheEventQueue<K, V> 031{ 032 enum QueueType 033 { 034 /** Does not use a thread pool. */ 035 SINGLE, 036 037 /** Uses a thread pool. */ 038 POOLED 039 } 040 041 /** 042 * Return the type of event queue we are using, either single or pooled. 043 * <p> 044 * @return the queue type: single or pooled 045 */ 046 QueueType getQueueType(); 047 048 /** 049 * Adds a feature to the PutEvent attribute of the ICacheEventQueue object 050 * <p> 051 * @param ce 052 * The feature to be added to the PutEvent attribute 053 * @throws IOException 054 */ 055 void addPutEvent( ICacheElement<K, V> ce ) 056 throws IOException; 057 058 /** 059 * Adds a feature to the RemoveEvent attribute of the ICacheEventQueue 060 * object 061 * <p> 062 * @param key 063 * The feature to be added to the RemoveEvent attribute 064 * @throws IOException 065 */ 066 void addRemoveEvent( K key ) 067 throws IOException; 068 069 /** 070 * Adds a feature to the RemoveAllEvent attribute of the ICacheEventQueue 071 * object 072 * <p> 073 * @throws IOException 074 */ 075 void addRemoveAllEvent() 076 throws IOException; 077 078 /** 079 * Adds a feature to the DisposeEvent attribute of the ICacheEventQueue 080 * object 081 * <p> 082 * @throws IOException 083 */ 084 void addDisposeEvent() 085 throws IOException; 086 087 /** 088 * Gets the listenerId attribute of the ICacheEventQueue object 089 * 090 * @return The listenerId value 091 */ 092 long getListenerId(); 093 094 /** Description of the Method */ 095 void destroy(); 096 097 /** 098 * Gets the alive attribute of the ICacheEventQueue object. Alive just 099 * indicates that there are active threads. This is less important that if 100 * the queue is working. 101 * <p> 102 * @return The alive value 103 */ 104 boolean isAlive(); 105 106 /** 107 * A Queue is working unless it has reached its max failure count. 108 * <p> 109 * @return boolean 110 */ 111 boolean isWorking(); 112 113 /** 114 * Returns the number of elements in the queue. If the queue cannot 115 * determine the size accurately it will return 1. 116 * <p> 117 * @return number of items in the queue. 118 */ 119 int size(); 120 121 /** 122 * Are there elements in the queue. 123 * <p> 124 * @return true if there are stil elements. 125 */ 126 boolean isEmpty(); 127 128 /** 129 * Returns the historical and statistical data for an event queue cache. 130 * <p> 131 * @return IStats 132 */ 133 IStats getStatistics(); 134}