//
// Name
//  $RCSfile: CacheManager.java,v $
// 
//  Copyright 2014-2015 Cloud Software Group, Inc. ALL RIGHTS RESERVED. 
//  Cloud Software Group, Inc. Confidential Information
//
// History
//  $Revision: 1.1.2.12 $ $Date: 2015/02/06 19:44:42 $
//
package com.kabira.platform;

import com.kabira.platform.flusher.FlushManager;
import com.kabira.platform.cache.CacheManagerUtils;
import java.util.ArrayList;

/**
 * The CacheManager class. This is the main interface for managing
 * named caches.
 */
public final class CacheManager
{
    /**
     * Exception thrown when a Cache instance has been destroyed.
     */
    public final static class CacheDestroyed extends java.lang.Error
    {
        /**
         *  Serialization version.
         */
        public final static long serialVersionUID = 1L;

        /**
         *  Creates a CacheDestroyed exception.
         *  @param  message String to include in the exception.
         */
        public CacheDestroyed(String message)
        {
            super(message);
        }
    }

    /**
     * A Cache instance.
     * <p>
     * Created by the CacheManager, it is the main interface for configuring
     * and accessing information for a named cache.
     * <p>
     * When created, the default cache size is unlimited. 
     */
    public final static class Cache
    {
        /**
         * Associate the given class to a cache.
         *
         * Also associates any classes that extend the class, which
         * are not already associated with another named cache.
         * <p>
         * If the class is already associated with a named cache, it will
         * be removed from that cache, and added to this one.
         * If it is already associated with this cache, no changes are made.
         * @param klass Managed class to add.
         * @exception ManagedClassError Thrown if <code>klass</code>
         *   is not Managed.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public void addClass(Class<?> klass)
            throws ManagedClassError, CacheDestroyed
        {
            ManagedObject.checkManagedClass(klass, "addClass");
            try
            {
                CacheManagerUtils.addType(m_name, klass.getName());
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }
        }
        /**
         * Set the size of the cache in bytes.
         * <p>
         * The system cache flusher asynchronously attempts to keep
         * memory utilization at or below this level for objects in this
         * cache. Note that this is not a strict size limit; object sizes
         * will be estimated, and the flusher may run infrequently,
         * allowing the cache to exceed the size setting.
         * @param size size of cache in bytes.
         * @exception IllegalArgumentException
         *  The size is negative or is greater than the shared memory that
         *  is available.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public void setSizeBytes(long size)
            throws IllegalArgumentException, CacheDestroyed
        {
            if (size < 0 || size > m_memorySize)
            {
                throw new IllegalArgumentException("Invalid size " + size +
                    ", maximum size allowed is " + m_memorySize);
            }

            try
            {
                CacheManagerUtils.setSizeBytes(m_name, size);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }
        }

        /**
         * Set the size of the cache as a percentage.
         * <p>
         * A decimal number between 1 and 100.
         * Indicates the maximum percentage of shared memory
         * within the node to be used for this named cache.
         * <p>
         * If a percent of 100 is given, the cache will have no limit.
         * @param percent Percent of shared memory to use for this cache.
         * @exception IllegalArgumentException
         *  An invalid percent was passed in.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public void setSizePercent(int percent) throws CacheDestroyed
        {
            if (percent < 1 || percent > 100)
            {
                throw new IllegalArgumentException(
                    "Invalid percent " + percent);
            }

            try
            {
                CacheManagerUtils.setSizeBytes(m_name,
                        (percent * m_memorySize) / 100);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }
        }
        /**
         * Disable cache.
         * <p>
         * This disables further caching of objects. The flusher will
         * asynchronously remove objects if the cache utilization is
         * greater than the size, otherwise the currently cached
         * instances will remain. If the cache is already disabled, no
         * action is taken.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public void disable() throws CacheDestroyed
        {
            try
            {
                CacheManagerUtils.enable(m_name, false);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }
        }
        /**
         * Enable cache.
         * <p>
         * Enable caching of objects using the current configuration of this
         * named cache. If the cache is already enabled, no action is taken.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public void enable() throws CacheDestroyed
        {
            try
            {
                CacheManagerUtils.enable(m_name, true);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }
        }

        /**
         * Flush a cache.
         * <p>
         * This immediately flushes instances from the cache until the 
         * cache size criteria are met. Note that this may lock a
         * significant number of object instances in the caller's
         * transaction and should be used with care.
         * <p>
         * Index values are also removed from shared memory
         * when the object is flushed.
         * @param numberObjects Maximum number of objects to flush. A value
         *  of zero means to flush as many instances as needed. 
         * @return Number of instances flushed.
         * @exception IllegalArgumentException
         *  The numberObjects value is negative.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public long flush(long numberObjects)
                throws IllegalArgumentException, CacheDestroyed
        {
            checkNegative(numberObjects, "numberObjects");
            try
            {
                return FlushManager.flushCache(m_name, numberObjects);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }
        }

        /**
         * Return the name of the cache.
         * @return String containing the name.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public String getName() throws CacheDestroyed
        {
            // FIX THIS: Using isDisabled to throw CacheDestroyed
            isDisabled();
            return m_name;
        }
        /**
         * Return all known classes associated with this cache.
         * @return <code>Iterable<klass></code> containing all classes.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public Iterable<Class<?>> getClasses() throws CacheDestroyed
        {
            String [] classNames;
            
            try
            {
                classNames = CacheManagerUtils.getTypes(m_name);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }

            ArrayList<Class<?>> classes =
                    new ArrayList<Class<?>>(classNames.length);
            for (int i = 0; i < classNames.length; i++)
            {
                try
                {
                    classes.add(Class.forName(classNames[i]));
                }
                catch (ClassNotFoundException ex)
                {
                    ex.printStackTrace();
                }
            }
            return classes;
        }
        /**
         * Return if the cache is currently disabled.
         * @return True if the cache is disabled, otherwise false.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public boolean isDisabled() throws CacheDestroyed
        {
            try
            {
                return CacheManagerUtils.isDisabled(m_name);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }
        }

        /**
         * Return the number of instances currently cached.
         * @return Number of instances in memory.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public long getNumberInstances() throws CacheDestroyed
        {
            try
            {
                return CacheManagerUtils.getNumberInstances(m_name);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }
        }

        /**
         * Return the cache size in bytes.
         * @return The current cache size in bytes.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public long getCacheSizeBytes() throws CacheDestroyed
        {
            try
            {
                return CacheManagerUtils.getCacheSizeBytes(m_name);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }
        }

        /**
         * Return the amount of cache used as a percent.
         * <p>
         * If the cache setting has no limit, a value of 0 is returned.
         * To get the percentage of total shared memory used, use the {@link
         * Cache#getMemoryUtilization()} method.
         * <p>
         * Since the flushing of objects from the cache is asynchronous,
         * values larger than 100 percent can be returned from this
         * method.
         * @return Percentage of cache used.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public int getCacheUtilization() throws CacheDestroyed
        {
            long    cacheSize = getCacheSizeBytes();

            if (cacheSize == m_memorySize || cacheSize == 0)
            {
                return 0;
            }

            long memoryUsage;

            try
            {
                memoryUsage = CacheManagerUtils.getMemoryUsage(m_name);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }

            return (int)((100 * memoryUsage)/cacheSize);
        }
        /**
         * Return the amount of shared memory used as a percent.
         * <p>
         * The percentage of the node's shared memory currently in use by
         * this cache will be calculated and returned. This value will be
         * approximate.
         * @return Percentage of shared memory used.
         * @exception CacheDestroyed This cache instance no longer exists.
         */
        public int getMemoryUtilization() throws CacheDestroyed
        {
            long memoryUsage;

            try
            {
                memoryUsage = CacheManagerUtils.getMemoryUsage(m_name);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new CacheDestroyed(ex.getMessage());
            }

            return (int)((100 * memoryUsage)/m_memorySize);
        }

        //
        // Private constructor
        //
        private Cache(String name, long memorySize)
        {
            m_name = name;
            m_memorySize = memorySize;
        }

        //
        // Private fields
        //
        private String      m_name;
        private long        m_memorySize;
    }

    /**
     * The Cache flusher.
     * <p>
     * Configure the asynchronous thread that periodically
     * removes instances from all active caches, flush notifications,
     * and support for explicit object flushing.
     */
    public final static class CacheFlusher
    {
        /**
         * Set the number of seconds to sleep between runs of the flusher.
         * <p>
         * The default value is to have the flusher run every second, a
         * value of 0 disables the flusher. Note that disabling the
         * flusher will allow caches bounded by size to exceed their
         * configured sizes.
         * @param seconds Number of seconds.
         * @exception IllegalArgumentException
         *  The seconds value is negative.
         */
        public void setFlushIntervalSeconds(long seconds)
            throws IllegalArgumentException
        {
            checkNegative(seconds, "seconds");
            CacheManagerUtils.setFlushIntervalSeconds(seconds);
        }
        /**
         * Set the maximum number of object instances to flush.
         * <p>
         * Sets the number of object instances to flush each time the
         * flush thread executes. A value of 0 indicates no limit.
         * @param numberObjects Maximum number of objects to flush.
         * @exception IllegalArgumentException
         *  The numberObjects value is negative.
         */
        public void setMaximumObjectsPerFlush(long numberObjects)
            throws IllegalArgumentException
        {
            checkNegative(numberObjects, "numberObjects");
            CacheManagerUtils.setMaxObjectsPerFlush(numberObjects);
        }

        /**
         * Associate a flush notifier with a Managed class.
         * <p>
         * The Managed class is the type T from the user implementation
         * of Notifier<T>.
         * <p>
         * If a Notifier instance is already associated with a class,
         * the new value overwrites the previous one. The lifecycle of
         * the returned instance is not affected.
         * <p>
         * The system automatically unregisters the passed in Notifier
         * instance when this JVM shutdowns down. The lifecycle of
         * the Notifier instance is not affected. If the JVM is
         * restarted, the Notifer is not automatically reregistered.
         * <p>
         * <b>Inheritance</b>
         * <p>
         * The Notifier will also be used for any classes which
         * extend type T which don't have their own Notifier set.
         * <p>
         * During an object flush, if there are Notifiers set on
         * multiple classes in the inheritance chain, only a single
         * Notifier will be called.
         * The Notifier is selected by first looking at the target
         * object's class, and if no Notifier is set, searching up
         * the inheritance chain until a Notifier is found.
         *
         * @param notifier User defined Notifier instance.
         *
         * @return Previous Notifier instance associated with
         * the notifier's managed type, or null if no Notifier was set
         * for that type.
         *
         * @exception ManagedClassError
         *  The managedClass is not a Managed object.
         *
         * @see CacheFlusher#clearNotifier
         */
        public static final com.kabira.platform.flusher.Notifier<?> setNotifier(
            final com.kabira.platform.flusher.Notifier<?> notifier)
            throws ManagedClassError
        {
            return FlushManager.setNotifier(notifier);
        }

        /**
         * Clear the flush notifier for the given managed class.
         * <p>
         * If no flush notifier is associated with the managed class,
         * this operation does nothing.
         *<p>
         * Notifiers registered for parent or child classes are not
         * affected.
         *
         * @param managedClass Managed object class.
         *
         * @return Previous Notifier instance associated with
         * the notifier's managed type, or null if no Notifier was set
         * for that type.
         *
         * @exception ManagedClassError
         *  The managedClass parameter is not a Managed class.
         *
         * @see CacheFlusher#setNotifier
         */
        public static final com.kabira.platform.flusher.Notifier<?>
            clearNotifier(final Class<?> managedClass) throws ManagedClassError
        {
            try
            {
                return (com.kabira.platform.flusher.Notifier<?>)
                    FlushManager.clearNotifier(managedClass);
            }
            catch (ResourceUnavailableException ex)
            {
                throw new ManagedClassError(ex.getMessage());
            }
        }

        /** Flush a Managed object from shared memory.
          * <p>
          * If the operand is a partitioned object on the active node
          * the flush is equivalent to ManagedObject.delete() and will
          * remove the object and its keys for all nodes in its partition.
          * <p>
          * If the operand is a partitioned object on a replica node,
          * no action is taken.
          * <p>
          * If the operand is a non-partitioned, remote object, it
          * will be removed along with its keys, from the local node,
          * where flush() is being invoked.
          * <p>
          * If the operand is a local object, flush is equivalent
          * to ManagedObject.delete().
          * <p><b>Delete Triggers</b> 
          * <p>
          * Any defined delete triggers will be called on the local
          * node for flushes of local objects and partitioned objects
          * on the active node.
          * <p><b>Flush Notifier</b>
          * <p>
          * If a flush Notifier has been set for the class type of
          * the operand (or a class in its parent inheritance chain),
          * it is called before the flush occurs.
          * If the Notifier.isFlushable() method returns false
          * flush() returns immediately without having flushed
          * the operand.
          * See the setNotifier <b>Inheritance</b> section for
          * for a description of how the Notifier is chosen.
          *
          * @param object Object to flush.
          * @exception ManagedClassError if object is not Managed.
          * @see CacheFlusher#setNotifier
          * @see com.kabira.platform.flusher.Notifier
          * @see com.kabira.platform.DeleteTrigger
          */
        public static void flush(Object object)
            throws ManagedClassError
        {
            if (! ManagedObject.isManaged(object))
            {
                throw new ManagedClassError("Class "
                    + object.getClass().getName()
                    + " is not Managed. Cache.flush() can only be "
                    + " applied to Managed classes.");
            }

            FlushManager.flush(object);
        }

        // Private constructor
        private CacheFlusher() { }
    }

    /**
     * Get or create a named cache.
     * <p>
     * This method creates a named Cache instance. If one already exists, that
     * instance is returned.
     * @param cacheName Name of Cache.
     * @return Cache instance that was created or found.
     */
    public static Cache getOrCreateCache(final String cacheName)
    {
        long memorySize = _getOrCreateCache(cacheName);
        return new Cache(cacheName, memorySize);
    }

    /**
     * Delete a named cache.
     * <p>
     * This method deletes the named Cache instance. 
     * <p>
     * @param cacheName Name of a Cache to delete.
     * @return True if cache instance was deleted, false if the named
     *  cache was not found.
     */
    public static boolean deleteCache(final String cacheName)
    {
        return CacheManagerUtils.deleteCache(cacheName);
    }

    /**
     * Return all known caches on this node.
     * @return <code>Iterable<Cache></code> containing all caches.
     */
    public static Iterable<Cache> getCaches()
    {
        String [] cacheNames = CacheManagerUtils.getCacheNames();
        ArrayList<Cache> caches = new ArrayList<Cache>(cacheNames.length);
        for (int i = 0; i < cacheNames.length; i++)
        {
            caches.add(getOrCreateCache(cacheNames[i]));
        }
        return caches;
    }

    /**
     * Get the cache flusher.
     * <p>
     * This method returns the CacheFlusher instance. 
     * @return Active CacheFlusher instance.
     */
    public static CacheFlusher getCacheFlusher()
    {
        return new CacheFlusher();
    }

    // Private constructor, never executed.
    private CacheManager() { }

    private static void checkNegative(long val, String param)
        throws IllegalArgumentException
    {
        if (val < 0)
        {
            throw new IllegalArgumentException(
                "Invalid " + param + " " + val);
        }
    }

    private static long _getOrCreateCache(String name)
    {
        return CacheManagerUtils.getOrCreateReferenceCache(name);
    }
}