Collections Data Structure Java

 * By default this list can contain 25 elements, where the first element is stored using a strong reference, which is
 * not garbage collected.
 * 

 * Restoring the elements is not implemented, concrete implementations will have to override the
 * restoreChild(int) method. The getMaxChildCount method defines the maxmimum number of
 * children in the list. When more than maxChildCount elements are contained in this list, add will always
 * return false to indicate that adding the element failed.
 * 

 * To customize the list, override createReference to create a different kind of reference.
 * 

 * This list is able to add or replace elements, but inserting or removing of elements is not possible.
 *
 * @author Thomas Morgner
 */
public abstract class WeakReferenceList implements Serializable, Cloneable
{
  /**
   * The master element.
   */
  private Object master;
  /**
   * Storage for the references.
   */
  private transient Reference[] childs;
  /**
   * The current number of elements.
   */
  private int size;
  /**
   * The maximum number of elements.
   */
  private final int maxChilds;
  /**
   * Creates a new weak reference list. The storage of the list is limited to getMaxChildCount() elements.
   *
   * @param maxChildCount the maximum number of elements.
   */
  protected WeakReferenceList(final int maxChildCount)
  {
    this.maxChilds = maxChildCount;
    this.childs = new Reference[maxChildCount - 1];
  }
  /**
   * Returns the maximum number of children in this list.
   *
   * @return the maximum number of elements in this list.
   */
  protected final int getMaxChildCount()
  {
    return maxChilds;
  }
  /**
   * Returns the master element of this list. The master element is the element stored by a strong reference and cannot
   * be garbage collected.
   *
   * @return the master element
   */
  protected Object getMaster()
  {
    return master;
  }
  /**
   * Attempts to restore the child stored on the given index.
   *
   * @param index the index.
   * @return null if the child could not be restored or the restored child.
   */
  protected abstract Object restoreChild(int index);
  /**
   * Returns the child stored at the given index. If the child has been garbage collected, it gets restored using the
   * restoreChild function.
   *
   * @param index the index.
   * @return the object.
   */
  public Object get(final int index)
  {
    if (isMaster(index))
    {
      return master;
    }
    else
    {
      final Reference ref = childs[getChildPos(index)];
      if (ref == null)
      {
        throw new IllegalStateException("State: " + index);
      }
      Object ob = ref.get();
      if (ob == null)
      {
        ob = restoreChild(index);
        childs[getChildPos(index)] = createReference(ob);
      }
      return ob;
    }
  }
  /**
   * Replaces the child stored at the given index with the new child which can be null.
   *
   * @param report the object.
   * @param index  the index.
   */
  public void set(final Object report, final int index)
  {
    if (isMaster(index))
    {
      master = report;
    }
    else
    {
      childs[getChildPos(index)] = createReference(report);
    }
  }
  /**
   * Creates a new reference for the given object.
   *
   * @param o the object.
   * @return a WeakReference for the object o without any ReferenceQueue attached.
   */
  private Reference createReference(final Object o)
  {
    return new WeakReference(o);
  }
  /**
   * Adds the element to the list. If the maximum size of the list is exceeded, this function returns false to indicate
   * that adding failed.
   *
   * @param rs the object.
   * @return true, if the object was successfully added to the list, false otherwise
   */
  public boolean add(final Object rs)
  {
    if (size == 0)
    {
      master = rs;
      size = 1;
      return true;
    }
    else
    {
      if (size < getMaxChildCount())
      {
        childs[size - 1] = createReference(rs);
        size++;
        return true;
      }
      else
      {
        // was not able to add this to this list, maximum number of entries reached.
        return false;
      }
    }
  }
  /**
   * Returns true, if the given index denotes a master index of this list.
   *
   * @param index the index.
   * @return true if the index is a master index.
   */
  protected boolean isMaster(final int index)
  {
    return index % getMaxChildCount() == 0;
  }
  /**
   * Returns the internal storage position for the child.
   *
   * @param index the index.
   * @return the internal storage index.
   */
  protected int getChildPos(final int index)
  {
    return index % getMaxChildCount() - 1;
  }
  /**
   * Returns the size of the list.
   *
   * @return the size.
   */
  public int getSize()
  {
    return size;
  }
  /**
   * Serialisation support. The transient child elements were not saved.
   *
   * @param in the input stream.
   * @throws IOException            if there is an I/O error.
   * @throws ClassNotFoundException if a serialized class is not defined on this system.
   */
  private void readObject(final ObjectInputStream in)
      throws IOException, ClassNotFoundException
  {
    in.defaultReadObject();
    childs = new Reference[getMaxChildCount() - 1];
    for (int i = 0; i < childs.length; i++)
    {
      childs[i] = createReference(null);
    }
  }
  /**
   * Creates and returns a copy of this object.  The precise meaning of "copy" may depend on the class of the object.
   * The general intent is that, for any object x, the expression: 

   * 

   * x.clone() != x

   * 

   * x.clone().getClass() == x.getClass()

   * 

   * x.clone().equals(x)

   * By convention, the returned object should be obtained by calling super.clone.  If a class and all of its
   * superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() ==
   * x.getClass().
   * 

   * By convention, the object returned by this method should be independent of this object (which is being cloned).  To
   * achieve this independence, it may be necessary to modify one or more fields of the object returned by
   * super.clone before returning it.  Typically, this means copying any mutable objects that comprise the
   * internal "deep structure" of the object being cloned and replacing the references to these objects with references
   * to the copies.  If a class contains only primitive fields or references to immutable objects, then it is usually
   * the case that no fields in the object returned by super.clone need to be modified.
   * 

   * The method clone for class Object performs a specific cloning operation. First, if the class of
   * this object does not implement the interface Cloneable, then a CloneNotSupportedException is
   * thrown. Note that all arrays are considered to implement the interface Cloneable. Otherwise, this method
   * creates a new instance of the class of this object and initializes all its fields with exactly the contents of the
   * corresponding fields of this object, as if by assignment; the contents of the fields are not themselves cloned.
   * Thus, this method performs a "shallow copy" of this object, not a "deep copy" operation.
   *