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}