/**
 * Redistribution and use of this software and associated documentation
 * ("Software"), with or without modification, are permitted provided
 * that the following conditions are met:
 *
 * 1. Redistributions of source code must retain copyright
 *    statements and notices.  Redistributions must also contain a
 *    copy of this document.
 *
 * 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 name "Exolab" must not be used to endorse or promote
 *    products derived from this Software without prior written
 *    permission of Exoffice Technologies.  For written permission,
 *    please contact info@exolab.org.
 *
 * 4. Products derived from this Software may not be called "Exolab"
 *    nor may "Exolab" appear in their names without prior written
 *    permission of Exoffice Technologies. Exolab is a registered
 *    trademark of Exoffice Technologies.
 *
 * 5. Due credit should be given to the Exolab Project
 *    (http://www.exolab.org/).
 *
 * THIS SOFTWARE IS PROVIDED BY EXOFFICE TECHNOLOGIES AND CONTRIBUTORS
 * ``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
 * EXOFFICE TECHNOLOGIES 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.
 *
 * Copyright 2001-2004 (C) Exoffice Technologies Inc. All Rights Reserved.
 *
 * $Id: GarbageCollectionService.java,v 1.1 2004/11/26 01:50:42 tanderson Exp $
 */
package org.exolab.jms.gc;

import java.util.LinkedList;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import org.exolab.jms.config.Configuration;
import org.exolab.jms.config.ConfigurationManager;
import org.exolab.jms.config.GarbageCollectionConfiguration;
import org.exolab.jms.service.BasicService;
import org.exolab.jms.service.ServiceException;
import org.exolab.jms.service.ServiceState;
import org.exolab.jms.events.BasicEventManager;
import org.exolab.jms.events.Event;
import org.exolab.jms.events.EventHandler;
import org.exolab.jms.events.IllegalEventDefinedException;


/**
 * The garbage collection service is responsible for managing all transient
 * garbage collection for OpenJMS, which includes messages, destinations,
 * endpoints etc. It does not deal with persistent data, which is handled
 * through the database service. Other services or managers can register
 * themselves with GarbageCollectionService if they implement the
 * {@link GarbageCollectable} interface.
 * <p>
 * Gargabe collection will be initiated when the amount of free memory falls
 * below a low water mark, which is calculated as a percentage of total memory.
 * By default garbage collection will run when free memory falls below 20%
 * of total memory, this can be changed through the configuration file.
 * <p>
 * The service will check the memory usage every 30 seconds by default. but
 * this can also be modified through the configuration file.
 * <p>
 * In addition the garbage collection service can also be configured to
 * execute at regular intervals regardless the amount of residual free memory.
 * This option can be employed to ease the burden of performing wholesale
 * garbage collection when memory falls below the low water mark threshold. The
 * default value for this is 300 seconds. Setting this value to 0 will disable
 * this capability.
 * <p>
 * This service makes use of the {@link BasicEventManager} to register events 
 * for garbage collection.
 *
 * @version     $Revision: 1.1 $ $Date: 2004/11/26 01:50:42 $
 * @author      <a href="mailto:jima@intalio.com">Jim Alateras</a>
 */
public class GarbageCollectionService
    extends BasicService
    implements EventHandler {

    /**
     * The name of the service
     */
    private final static String GC_SERVICE_NAME = "GCCollectionService";

    /**
     * This is the value of the trnasient garbage collection event that
     * is used to register with the {@link BasicEventManager}. When this event
     * is received the memory utilization is checked to determine whether
     * we need to perform some garbage collection.
     */
    private final static int CHECK_FREE_MEMORY_EVENT = 1;

    /**
     * This event is used to unconditionally trigger garbage collection.
     */
    private final static int GARBAGE_COLLECT_EVENT = 2;

    /**
     * Maintains a singleton instance of the gc service
     */
    private static GarbageCollectionService _instance = null;

    /**
     * Used to synchronize the creation of the transaction manager
     */
    private static final Object _creator = new Object();

    /**
     * The default low water threshold value before GC is initiated.
     * This is specified as a percentage with valid values ranging from
     * 10-50.
     */
    private int _gcLowWaterThreshold = 20;

    /**
     * The default interval, in seconds, that memory is checked for
     * the low water threshold. The default is 30 seconds.
     */
    private int _memoryCheckInterval = 30 * 1000;

    /**
     * The default interval, in seconds, between successive executions
     * of the garbage collector. This will execute regardless the amount
     * of free memory left in the VM.
     */
    private int _gcInterval = 300 * 1000;

    /**
     * This is the priority of that the GC thread uses to collect garbage.
     * Changing it effects how aggressive GC is performed. The default value
     * is 5.
     */
    private int _gcThreadPriority = 5;

    /**
     * This is used to serialize access to the _collectingGarbage flag
     */
    private final Object _gcGuard = new Object();

    /**
     * This flag indicates whether garabage collection is in progress
     */
    private boolean _collectingGarbage = false;

    /**
     * Maintains a list of all GarbageCollectable instances
     */
    private LinkedList _gcList = new LinkedList();

    /**
     * The logger
     */
    private static final Log _log =
        LogFactory.getLog(GarbageCollectionService.class);


    /**
     * Return the singleton instance of the GarbageCollectionService
     *
     * @return GarbageCollectionService
     * @throws GarbageCollectionServiceException
     */
    public static GarbageCollectionService instance()
        throws GarbageCollectionServiceException {
        if (_instance == null) {
            synchronized (_creator) {
                // we need to check again if multiple threads
                // have blocked on the creation of the singleton
                if (_instance == null) {
                    _instance = new GarbageCollectionService();
                }
            }
        }

        return _instance;
    }

    /**
     * Create an instance of a garbage collection service. It uses the
     * configuration manager to extract the service parameters.
     *
     * @throws GarbageCollectionServiceException
     */
    GarbageCollectionService() {
        super(GC_SERVICE_NAME);

        // access the configuration file.
        Configuration config = ConfigurationManager.getConfig();
        GarbageCollectionConfiguration gc_config =
            config.getGarbageCollectionConfiguration();

        // read the value and ensure that it is within
        // the specified limits
        int low = gc_config.getLowWaterThreshold();
        if (low < 10) {
            low = 10;
        }

        if (low > 50) {
            low = 50;
        }