001    /*
002     * Copyright 2001-2004 The Apache Software Foundation
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *     http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.apache.commons.cache.adt;
017    
018    import java.util.LinkedList; // only used in JavaDoc comments, but this makes the warnings go away
019    /**
020     * A simple linked-listed inteface, supporting
021     * both singly and doubly linked lists.
022     * <p>
023     * Unlike {@link java.util.LinkedList}, this interface
024     * provides access to the list elements themselves, which
025     * may necessary for some uses.
026     *
027     * @see java.util.LinkedList
028     *
029     * @version $Id: Listable.java 155435 2005-02-26 13:17:27Z dirkv $
030     * @author Rodney Waldhoff
031     */
032    public interface Listable {
033      /**
034       * Return the <tt>Listable</tt> element following me,
035       * or <tt>null</tt> if I am the last element in the
036       * list.
037       *
038       * @return the <tt>Listable</tt> element following me,
039       *         or <tt>null</tt>.
040       */
041      public abstract Listable getNext();
042    
043      /**
044       * Return <tt>true</tt> if there is a <tt>Listable</tt>
045       * element following me, <tt>false</tt> otherwise.
046       *
047       * @return <tt>true</tt> if there is a <tt>Listable</tt>
048       *         element following me, <tt>false</tt> otherwise.
049       */
050      public abstract boolean hasNext();
051    
052      /**
053       * Change my next element to <i>next</i>.
054       * Note that this does not change the {@link #getPrev}
055       * value of <i>next</i>.
056       *
057       * @param next my new following sibling.
058       * @throws UnsupportedOperationException if I am a read-only list.
059       */
060      public abstract void setNext(Listable next) throws UnsupportedOperationException;
061    
062      /**
063       * Return the <tt>Listable</tt> element preceeding me,
064       * or <tt>null</tt> if I am the last element in the
065       * list.
066       *
067       * @return the <tt>Listable</tt> element preceeding me,
068       *         or <tt>null</tt>.
069       * @throws UnsupportedOperationException if I am a singly-linked list.
070       */
071      public abstract Listable getPrev() throws UnsupportedOperationException;
072    
073      /**
074       * Return <tt>true</tt> if there is a <tt>Listable</tt>
075       * element preceeding me, <tt>false</tt> otherwise.
076       *
077       * @return <tt>true</tt> if there is a <tt>Listable</tt>
078       *         element preceeding me, <tt>false</tt> otherwise.
079       * @throws UnsupportedOperationException if I am a singly-linked list.
080       */
081      public abstract boolean hasPrev() throws UnsupportedOperationException;
082    
083      /**
084       * Change my preceeding element to <i>prev</i>.
085       * Note that this does not change the {@link #getNext}
086       * value of <i>prev</i>.
087       *
088       * @param prev my new preceeding sibling.
089       * @throws UnsupportedOperationException if I am a singly-linked or read-only list.
090       */
091      public abstract void setPrev(Listable prev) throws UnsupportedOperationException;
092    }