/*
 * ====================================================================
 *
 * The Apache Software License, Version 1.1
 *
 * Copyright (c) 1999-2002 The Apache Software Foundation.  All rights
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution, if
 *    any, must include the following acknowlegement:
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowlegement may appear in the software itself,
 *    if and wherever such third-party acknowlegements normally appear.
 *
 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
 *    Foundation" must not be used to endorse or promote products derived
 *    from this software without prior written permission. For written
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache"
 *    nor may "Apache" appear in their names without prior written
 *    permission of the Apache Group.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */


package org.apache.commons.collections;

import java.util.*;
import java.lang.ref.*;


/**
 *  <p>A <code>HashSet</code> that only maintains weak references to its values.
 *  A value in a <code>WeakHashSet</code> can automatically be removed when it
 *  is no longer refereneced outside of this set.  In other words, objects that
 *  can only be referenced through this set will be removed and discarded when
 *  the garbage collector runs.</p>
 *
 *  <p>Other than maintaining a weak reference to its values, this class
 *  functions exactly as its {@link HashSet} superclass.
 *
 *  @see HashSet
 *  @see WeakReference
 */
public class WeakHashSet
    extends HashSet {

    // Queue of weak references whose objects have been garbage collected.
    private ReferenceQueue  cleanupQueue;


    /** Implements the {@link java.util.HashSet#HashSet()} constructor. */
    public WeakHashSet(
    ) {

        super( );
        initialize( );

    }


    /** Implements the {@link java.util.HashSet#HashSet(Collection)} constructor. */
    public WeakHashSet(
        Collection c
    ) {

        super( c.size( ) );


        // Iterator for objects in the existing collection
        Iterator    collectionIterator;


        initialize( );

        // Add each item from the old collection to this one
        collectionIterator = c.iterator( );
        while( collectionIterator.hasNext( ) ) {

            add( collectionIterator.next( ) );

        }

    }


    /** Implements the {@link java.util.HashSet#HashSet(int)} constructor. */
    public WeakHashSet(
        int    initialCapacity
    ) {

        super( initialCapacity );
        initialize( );

    }


    /** Implements the {@link java.util.HashSet#HashSet(int,float)} constructor. */
    public WeakHashSet(
        int     initialCapacity,
        float   loadFactor
    ) {

        super( initialCapacity, loadFactor );
        initialize( );

    }


    /**
     *  Performs common initialization for all constructors.
     */
    private void initialize(
    ) {

        // Create the cleanup queue for references that have been gc'ed.
        cleanupQueue = new ReferenceQueue( );

    }


    /**
     *  Checks the dereference queue for all objects that have been retrieved.
     *  References to these objects are then removed from the superclass
     *  HashSet.
     */
    private void removeDereferencedElements(
    ) {

        // One reference whose object has been dereferenced
        Reference   nextElement;


        // Loop through each reference element and remove it from the superclass HashSet.
        nextElement = cleanupQueue.poll( );
        while( nextElement != null ) {

            super.remove( nextElement );
            nextElement = cleanupQueue.poll( );

        }

    }


    /** Implements the {@link java.util.HashSet#iterator()} method. */
    public Iterator iterator(
    ) {

        removeDereferencedElements( );

        // Return the custom iterator for this Set
        return new WeakHashSetIterator( super.iterator( ) );

    }


    /** Implements the {@link java.util.HashSet#size()} method. */
    public int size(
    ) {

        removeDereferencedElements( );
        return super.size( );

    }


    /** Implements the {@link java.util.HashSet#isEmpty()} method. */
    public boolean isEmpty(
    ) {

        removeDereferencedElements( );
        return super.isEmpty( );

    }


    /** Implements the {@link java.util.HashSet#contains(Object)} method. */
    public boolean contains(
        Object  obj
    ) {

        removeDereferencedElements( );

        // Wrap the new element with a weak reference object, and check if it exists
        return super.contains( new WeakHashSetElement( obj, cleanupQueue ) );

    }


    /** Implements the {@link java.util.HashSet#add(Object)} method. */
    public boolean add(
        Object    obj
    ) {

        removeDereferencedElements( );

        // Wrap the new element with a weak reference object, and add it
        return super.add( new WeakHashSetElement( obj, cleanupQueue ) );

    }


    /** Implements the {@link java.util.HashSet#remove(Object)} method. */
    public boolean remove(
        Object    obj
    ) {

        removeDereferencedElements( );

        // Wrap the new element with a weak reference object, and remove it
        return super.remove( new WeakHashSetElement( obj, cleanupQueue ) );

    }


    /** Implements the {@link java.util.HashSet#clone()} method. */
    public Object clone(
    ) {

        removeDereferencedElements( );
        return new WeakHashSet( this );

    }

}