001    package org.rakeshv.utils;
002    
003    /**
004     * An interface for all the datastructures implemented in this package.
005     *
006     * <p>Copyright 2004-2006 Rakesh Vidyadharan</p>
007     * @author Rakesh Vidyadharan 2004 September 1
008     * @version $Id: DataStructure.java,v 1.6 2006/03/11 16:30:38 rakesh Exp $
009     */
010    public interface DataStructure<T>
011    {
012      /**
013       * A constant to designate the {@link FIFO} implementation.
014       */
015      public static final int FIFO = 0;
016    
017      /**
018       * A constant to designate the {@link FIFO} implementation.
019       *
020       * @deprecated Use {@link #FIFO}
021       */
022      @Deprecated public static final int FIFO_IMPLEMENTATION = FIFO;
023    
024      /**
025       * A constant to designate the {@link LRU} implementation.
026       */
027      public static final int LRU = 1;
028    
029      /**
030       * A constant to designate the {@link LRU} implementation.
031       *
032       * @deprecated Use {@link #LRU}
033       */
034      @Deprecated public static final int LRU_IMPLEMENTATION = LRU;
035    
036      /**
037       * A constant to designate the {@link DynamicCache} implementation.
038       */
039      public static final int DYNAMIC = 2;
040    
041      /**
042       * Return the current <code>Object</code> in the datastructure.
043       *
044       * @return The Object that is at the current location within the 
045       *   datastructure.
046       */
047      public T get();
048    
049      /**
050       * Add the specified object to datastructure.
051       *
052       * <p><b>Note:</b> This method does not perform any <code>
053       * synchronisation</code>, and hence is not <code>thread-safe</code>.
054       * Client's must perform their own synchronisation if they so desire.
055       * </p>
056       *
057       * @param object The object to be added to the datastructure.
058       * @throws IllegalArgumentException If a <code>null</code> value was
059       *   specified for the object.
060       */
061      public void add( T object );
062    
063      /**
064       * Removes the current <code>Object</code> designated for removal
065       * from the datastructure.
066       *
067       * @return The Object that was removed.
068       */
069      public T remove();
070    
071      /**
072       * Removes the specified object from the datastructure.
073       *
074       * <p><b>Note:</b> This method does not perform any <code>
075       * synchronisation</code>, and hence is not <code>thread-safe</code>.
076       * Client's must perform their own synchronisation if they so desire.
077       * </p>
078       *
079       * @param object The object that is to be removed from the 
080       *   datastructure.
081       * @return Returns <code>true</code> if the specified object was
082       *   found and removed from the datastructure.
083       */
084      public boolean remove( T object );
085    
086      /**
087       * Removes all the objects from the datastructure.
088       *
089       * <p><b>Note:</b> This method does not perform any <code>
090       * synchronisation</code>, and hence is not <code>thread-safe</code>.
091       * Client's must perform their own synchronisation if they so desire.
092       * </p>
093       */
094      public void clear();
095    
096      /**
097       * Returns the size of the datastructure.  This may be total capacity
098       * of the datastructure, or the total number of valid objects 
099       * stored in the datastructure.
100       *
101       * @return The size of the datastructure.
102       */
103      public int size();
104    }