//
// Name
//  $RCSfile: Extent.java,v $
//
// Copyright
//  Copyright 2014 Cloud Software Group, Inc. ALL RIGHTS RESERVED.
//  Cloud Software Group, Inc. Confidential Information
//
// History
//  $Revision: 1.1.2.7 $ $Date: 2014/11/26 22:22:11 $
//
package com.kabira.store;

import com.kabira.platform.annotation.Managed;
import com.kabira.platform.LockMode;
import com.kabira.platform.ManagedClassError;
import com.kabira.platform.ManagedObject;
import com.kabira.platform.Transaction;

import java.util.HashSet;

/**
 * Class for receiving notifications of
 * {@link com.kabira.platform.ManagedObject#extent} calls.
 * <p>
 * An <code>Extent</code> notifier does not directly return results.
 * The notification provides an opportunity to change the contents of
 * a Managed object extent (creating or deleting Managed objects)
 * before the extent iteration is done.
 * For example, it could be used for creating Managed objects from data
 * in a database.
 *
 * @param <T>   Managed type parameter
 */
@Managed
public abstract class Extent<T> extends ExtentBase
{
    // force usage of protected ctor
    private Extent()
    {
    }

    /** Constructor.
     * <p>
     * Creating an instance automatically installs it
     * as the extent notifier for Managed class <code>T</code>.
     * <p>
     * If a notifier is already installed for the class,
     * the new instance replaces the previous instance.
     * <p>
     * Deleting a notifier automatically uninstalls it.
     * <p>
     * Notifiers are automatically deleted when the JVM shuts down.
     * Notifiers created in other JVMs are not affected.
     * <p>
     * A separate notifier may be set for each class in a hierarchy.
     * <p>
     * If no notifier is installed for a class,
     * it inherits the notifier of its parent.
     * <p>
     * When a {@link ManagedObject#extent} result set is iterated,
     * the installed notifier for its type and subtypes are called
     * before executing the extent call.
     *
     * The notifiers are called starting at the most extended
     * subtype up through the type hierarchy ending on the class
     * passed to the extent call.
     * The order of notifier invocation for multiple types at the
     * same level of the type hierarchy is undefined.
     *
     * @param klass The Managed class base to receive
     *              ManagedObject.extent() notifications for.
     * @throws ManagedClassError <code>klass</code> is not managed.
     */
    protected Extent(final Class<T> klass)
        throws ManagedClassError
    {
        audit(klass);

        m_className = klass.getName();
        install();
        NotifierHash.addToHash(this);
    }

    private static void audit(final Class<?> klass)
    {
        if (! ManagedObject.isManagedClass(klass))
        {
            throw new ManagedClassError(
                    klass.getName() + " is not @Managed");
        }
    }

    /**
     * Return the currently installed notifier for a Managed class.
     * Inheritance is not considered.
     * <p>
     * If there is no notifier for the Managed class null is returned.
     *
     * @param klass The class to search.
     * @return Extent or null.
     * @throws com.kabira.platform.ManagedClassError If
     *         <code>klass</code> is not managed.
     */
    public static Extent<?> getNotifier(final Class<?> klass)
    {
        audit(klass);
        return (Extent)StoreUtil.getExtentNotifier(klass.getName());
    }

    /**
     * Notifier method for
     * {@link com.kabira.platform.ManagedObject#extent(Class)} calls.
     * May be used to create (or delete) objects in the extent before
     * the extent is iterated.
     * <p>
     * Called by the system when a {@link ManagedObject#extent} result set is
     * iterated, before executing the extent call.
     * <p>
     * Called on each of the nodes in the
     * {@link com.kabira.platform.QueryScope} of the extent call.
     * <p>
     * Called before the ManagedObject.extent() is performed.
     * <p>
     * Work done within Extent.extent() will not
     * generate calls to com.kabira.store notifiers on the local node.
     * <p>
     * <b>Note:</b> work done within Extent.extent() will generate
     * calls to com.kabira.store notifiers on remote nodes.
     *
     * @param klass     The Managed class for the extent() call.
     *                  This may be a subtype of the notifier's managed
     *                  class type.
     *
     * @param lockMode The lock mode for the extent call. The notifier
     *                 implementation should attempt to honor this lock mode,
     *                 but there is no enforcement.
     */
    public abstract void extent(
            final Class<? extends T> klass,
            final LockMode lockMode);

    private void extentInternal(
            final Class<? extends T> klass,
            final int lockMode)
    {
        extent(klass, LockMode.values()[lockMode]);
    }

    static
    {
        Runtime.getRuntime().addShutdownHook(new Thread()
        {
            @Override
            public void run()
            {
                new Transaction("Extent notifier shutdown")
                {
                    @Override
                    protected void run()
                    {
                        NotifierHash.clearNotifiers();
                    }
                }.execute();
            }
        });
    }

    private static class NotifierHash
    {
        static final HashSet<Extent<?>> m_installedNotifiers
            = new HashSet<Extent<?>>();

        static void addToHash(final Extent<?> notifier)
        {
            m_installedNotifiers.add(notifier);
        }

        static void clearNotifiers()
        {
            for (Extent<?> extent : m_installedNotifiers)
            {
                if (! ManagedObject.isEmpty(extent))
                {
                    ManagedObject.delete(extent);
                }
            }
        }
    }
}