001package org.apache.commons.jcs3.engine.behavior;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.io.IOException;
023
024import org.apache.commons.jcs3.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     * A Queue is working unless it has reached its max failure count.
099     * <p>
100     * @return boolean
101     */
102    boolean isWorking();
103
104    /**
105     * Returns the number of elements in the queue.  If the queue cannot
106     * determine the size accurately it will return 1.
107     * <p>
108     * @return number of items in the queue.
109     */
110    int size();
111
112    /**
113     * Are there elements in the queue.
114     * <p>
115     * @return true if there are stil elements.
116     */
117    boolean isEmpty();
118
119    /**
120     * Returns the historical and statistical data for an event queue cache.
121     * <p>
122     * @return IStats
123     */
124    IStats getStatistics();
125}