//
// Name
//  $RCSfile: ManagedObject.java,v $
//
// Copyright
//  Copyright 2007-2015 Cloud Software Group, Inc. ALL RIGHTS RESERVED.
//  Cloud Software Group, Inc. Confidential Information
//
// History
//  $Revision: 1.1.2.47 $ $Date: 2015/01/27 03:25:12 $
//

package com.kabira.platform;

import com.kabira.platform.annotation.Managed;
import java.util.Iterator;

/**
  * Class to manipulate and find shared memory backed objects.
  * To create a Java object that persists in shared memory, see the
  * <code>&#64;Managed</code> annotation.
  * <p>
  *  Example:
  *<pre>&#64;Managed
public class Account {
    public Account(String userName) {
    super();
    m_userName = userName;
    }

    public Account(String userName, Account referrer) {
    this(userName);
    allocateMailbox();
    addToFriendList(referrer);
    }

    public void addToFriendList(Account friendlyAccount) {
    ...
    }

    private void allocateMailbox() {
    ...
    }

    private String m_userName;
    private Account[] m_friendList;
}</pre>
 *  Some example usage of the above type:
 <pre>
    //
    //  create a new account in shared memory:
    //
    Account newCustomer = new Account("Fred Rogers", referrer);
    System.out.println("Added " + newCustomer.toString());

    //
    //  delete all expired accounts from shared memory.
    //  Note extent access, and use of the delete() method
    //  to delete the shared memory instance.
    //
    for (Account acc : ManagedObject.extent(Account.class)) {
    if (acc.expireDate &lt; today) {
        ManagedObject.delete(acc);
    }
    }
 </pre>
 *
 *  @see com.kabira.platform.annotation.Managed
 *  @see com.kabira.platform.Transaction
 */
@Managed
public class ManagedObject
{
    /**
     * Returns all shared memory instances of a Managed type.
     * <p>
     * The <code>klass</code> parameter must be a <code>Managed</code>
     * class, and is used to determine the extent to return.
     * A Managed class is either annotated <code>&#64;Managed</code>, or
     * extends a class that is so annotated.
     * <p>
     * Consider the following example.  It returns all instances of
     * <code>MyType</code> (including instances of its subtypes)
     * with no locks held on the objects:
    <pre>
    //
    // Iterate instances of MyType.class, returning all objects in the extent
    //
    for (MyType instance : ManagedObject.extent(MyType.class)) {
    assert ( Transaction.hasReadLock(instance) == false );
    assert ( Transaction.hasWriteLock(instance) == false );
    ...
    }</pre>
     * @param <T> Managed class.
     * @param klass extent class - instances of this type,
     * and any subtypes that extend from this type, will be returned in
     * the extent.
     * @exception ManagedClassError Thrown if <code>klass</code>
     *   is not Managed (or exactly ManagedObject).
     * @return <code>Iterable</code> that will traverse all instances 
     *   located in shared memory.
     * @see com.kabira.platform.annotation.Managed
     * @see com.kabira.platform.ManagedClassError
     */
    public static <T> java.lang.Iterable<T> extent(
        final java.lang.Class<T> klass)
        throws ManagedClassError
    {
        return ManagedObject.extent(klass, LockMode.NOLOCK);
    }

    /**
     * Returns all shared memory instances of a Managed type,
     * with an explicit transaction lock taken on each instance
     * as it is iterated.
     * <p>
     * The <code>klass</code> parameter must be a Managed class,
     * and is used to determine the extent to return.
     * <p>
     * The <code>objectLock</code> parameter is used to specify the
     * transaction lock to take on objects returned during extent 
     * iteration. The objects are locked as they are returned from the 
     * <code>java.util.Iterator</code>, not when this method
     * returns.
     * <p>
     * Consider the following example.  It returns all instances of
     * <code>MyType</code> (including instances of its subtypes)
     * with a READLOCK held on each instance:
     <pre>
    //
    //  Iterate the ManagedObjectSet taking read locks on the objects
    //
    for (MyType mt : ManagedObject.extent( MyType.class, LockMode.READLOCK)) {
    assert ( Transaction.hasReadLock(mt) == true );
    ...
    }</pre>
     * @param <T> Managed class.
     * @param klass extent class - instances of this type,
     *   and any subtypes that extend from this type, will be returned
     *   in the extent.
     * @param objectLock object lock - all object instances
     *   returned during extent iteration will have this transaction lock.
     * @exception ManagedClassError Thrown if <code>klass</code>
     *   is not marked Managed, or is exactly ManagedObject.
     * @return <code>Iterable</code> containing references to
     *   all instances located in shared memory.
     * @see com.kabira.platform.annotation.Managed
     */
    public static <T> java.lang.Iterable<T> extent(
        final java.lang.Class<T> klass,
        final LockMode objectLock)
        throws ManagedClassError
    {
        checkManagedClass(klass, "extent");

        if (klass.equals(ManagedObject.class))
        {
            throw new ManagedClassError(
                "extent class cannot be "
                + ManagedObject.class.getName() + ".");
        }

        return new Extent<T>(klass.getName(), objectLock);
    }

    /**
     * Returns all shared memory instances of a Managed type,
     * with an explicit transaction lock taken on each instance
     * as it is iterated.
     * <p>
     * The <code>klass</code> parameter must be a Managed class,
     * and is used to determine the extent to return.
     * <p>
     * The <code>queryScope</code> parameter determines the scope
     * of the search for object instances.
     * <p>
     * The <code>objectLock</code> parameter is used to specify the
     * transaction lock to take on objects returned during extent 
     * iteration. The objects are locked as they are returned from the 
     * <code>java.util.Iterator</code>, not when this method
     * returns.
     * @param <T> Managed class.
     * @param klass extent class - instances of this type,
     *   and any subtypes that extend from this type, will be returned
     *   in the extent.
     * @param queryScope scope of extent lookup.
     * @param objectLock object lock - all object instances
     *   returned during extent iteration will have this transaction lock.
     * @exception ManagedClassError Thrown if <code>klass</code>
     *   is not marked Managed, or is exactly ManagedObject.
     * @exception IllegalArgumentException
     *  The queryScope failed audit due to a bad node list.
     * @exception ResourceUnavailableException
     *  Access to distributed services failed.
     * @return <code>Iterable</code> containing references to
     *   all instances located in shared memory.
     * @see com.kabira.platform.annotation.Managed
     * @see com.kabira.platform.QueryScope
     */
    public static <T> java.lang.Iterable<T> extent(
        final java.lang.Class<T> klass,
        final QueryScope queryScope,
        final LockMode objectLock)
        throws ManagedClassError,
                IllegalArgumentException, 
                ResourceUnavailableException
    {
        checkManagedClass(klass, "extent");

        if (klass.equals(ManagedObject.class))
        {
            throw new ManagedClassError(
                "extent class cannot be "
                + ManagedObject.class.getName() + ".");
        }

        if (queryScope.getScope() != QueryScope.Scope.LOCAL)
        {
            initializeDistributedQuery();
            queryScope.audit();
            if (m_distributedQuery != null)
            {
                TypeDescriptor td = TypeDescriptor.getDescriptor(klass);
                m_distributedQuery.loadObjectExtent(
                        queryScope,
                        td.m_domainId,
                        td.m_typeId,
                        KeyQuery.mapObjectLock(objectLock));
            }
        }
        return new Extent<T>(klass.getName(), objectLock);
    }

    /** Returns a hash code based on the underlying shared memory object.
      * @param o Managed object to hash
      * @return calculated hash code.
      */
    public static int hashCode(Object o)
        throws ManagedClassError
    {
        return java.util.Arrays.hashCode(getObjectReference(o, "hashCode"));
    }

    /** Returns true if both references are proxies to the same
      * shared memory object.
      * @param o1 Managed object 
      * @param o2 Managed object
      * @return true if the two instances refer to the same Managed object.
      * @exception ManagedClassError if o1 or o2 is not Managed.
      */
    public static boolean equals(Object o1, Object o2)
        throws ManagedClassError
    {
        if (o1 == o2)
        {
            return true;
        }

        if ((o1 == null) || (o2 == null))
        {
            return false;
        }

        return java.util.Arrays.equals(
            getObjectReference(o1, "equals"),
            getObjectReference(o2, "equals"));
    }

    /** Determines if the given object is an instance of a Managed class.
      * Returns true only if the object, or a superclass, is marked
      * &#64;Managed.
      * @param o Object to check.
      * @return true if object is a Managed object.
      */
    public static boolean isManaged(Object o)
    {
        return o instanceof ManagedMarker;
    }

    /** Determines if the given class is Managed.
      * Returns true only if the class, or a superclass, is marked
      * &#64;Managed.
      * @param klass Class to check.
      * @return true if class is Managed.
      */
    public static boolean isManagedClass(Class<?> klass)
    {
        return ManagedMarker.class.isAssignableFrom(klass);
    }

    /** Determines if the given class is partitioned.
      * Returns true if the &#64;Managed class currently
      * has a PartitionMapper installed.
      * @param klass Class to check.
      * @return true if class is partitioned.
      * @exception ManagedClassError if klass not Managed.
      */
    public static boolean isPartitioned(Class<?> klass)
    {
        checkManagedClass(klass, "isPartitioned");

        return NativeRuntime.isPartitioned(klass.getName());
    }

    /** If the given object is not Managed, throw a new ManagedClassError.
      */
    static void checkManagedObject(Object o, String methodName)
        throws ManagedClassError
    {
        if (! isManaged(o))
        {
            throw new ManagedClassError("Class "
                + o.getClass().getName()
                + " is not Managed. Method "
                + methodName + "() can only be applied to "
                + "Managed classes.");
        }
    }

    /** If the given class is not Managed, throw a new ManagedClassError.
      */
    static void checkManagedClass(Class<?> klass, String methodName)
        throws ManagedClassError
    {
        if (! isManagedClass(klass))
        {
            throw new ManagedClassError("Class "
                + klass.getName()
                + " is not Managed. Method "
                + methodName + "() can only be applied to "
                + "Managed classes.");
        }
    }

    /** Return the object reference as a byte array. 
      * This may return a reference to the actual field, so the result
      * should be treated as read-only.
      * @param o Object to get reference from.
      * @return byte array containing reference.
      */
    public static byte[] getObjectReference(Object o)
    {
        return ((ManagedMarker)o)._getObjectReference();
    }

    /** with validation that the caller is a ManagedObject */
    static byte[] getObjectReference(Object o, final String caller)
        throws ManagedClassError
    {
        checkManagedObject(o, caller);

        final byte[] objRef = ((ManagedMarker)o)._getObjectReference();

        if (objRef == null)
        {
            throw new ManagedClassError("Method "
                + caller + "() called before the Managed object was "
                + "fully contstructed.");
        }

        return ((ManagedMarker)o)._getObjectReference();
    }

    /** Deletes a Managed object.
      * @param operand Object to delete.
      * @exception ManagedClassError if operand is not Managed.
      */
    public static void delete(Object operand)
        throws ManagedClassError
    {
        NativeRuntime.deleteSMObject(getObjectReference(operand, "delete"));
    }

    /**
      * Get a string version of an object reference
      * <p>
      * If the object is invalid, an empty string is returned to the caller.
      * @param operand  Object to get reference for
      * @return         Stringified object reference
      * @exception ManagedClassError if operand is not Managed.
      */
    public static String objectToReference(Object operand)
    {
        String refStr = "";

        if (operand != null)
        {
            refStr = NativeRuntime.objectToReference(
                getObjectReference(operand, "objectToReference"));
        }

        return refStr;
    }

    /**
      * Convert a stringified object reference to an Object
      * <p>
      * If the string reference is invalid an empty object
      * is returned to the caller.
      * @param refStr   Object reference string
      * @return     Managed object associated with refStr
      */
    public static Object referenceToObject(final String refStr)
    {
        return NativeRuntime.referenceToObject(refStr);
    }

    /** Returns the number of instances of the given class.
      *<br>
      * This count does not require transaction locks on the
      * extent or any of the individual objects in the extent.
      *<br>
      * This means the number returned by cardinality() may 
      * change even as observed within a single transaction.
      * @param klass extent class - instances of this type,
      * and any subtypes that extend from this type, will be counted.
      * @exception ManagedClassError Thrown if <code>klass</code>
      *   is not marked Managed.
      * @return Number of instances found.
      */
    public static int cardinality(Class<?> klass)
        throws ManagedClassError
    {
        checkManagedClass(klass, "cardinality");
        return NativeRuntime.cardinality(klass.getName());
    }

    /** Returns the number of instances of the given class.
      *<br>
      * This count does not require transaction locks on the
      * extent or any of the individual objects in the extent.
      *<br>
      * This means the number returned by cardinality() may 
      * change even as observed within a single transaction.
      *<p>
      * The <code>queryScope</code> parameter determines the scope
      * of the search for object instances.
      *<p>
      * @param klass extent class - instances of this type,
      * and any subtypes that extend from this type, will be counted.
      * @param queryScope scope of cardinality lookup.
      * @exception ManagedClassError Thrown if <code>klass</code>
      *   is not marked Managed.
      * @exception IllegalArgumentException
      *  The queryScope failed audit due to a bad node list.
      * @exception ResourceUnavailableException
      *  Access to distributed services failed.
      * @return Number of instances found.
      * @see com.kabira.platform.QueryScope
      */
    public static int cardinality(
        Class<?> klass,
        final QueryScope queryScope)
        throws ManagedClassError,
                IllegalArgumentException, 
                ResourceUnavailableException
    {
        checkManagedClass(klass, "cardinality");

        if (queryScope.getScope() != QueryScope.Scope.LOCAL)
        {
            initializeDistributedQuery();
            queryScope.audit();
            if (m_distributedQuery != null)
            {
                TypeDescriptor td = TypeDescriptor.getDescriptor(klass);
                m_distributedQuery.loadObjectExtent(
                        queryScope,
                        td.m_domainId,
                        td.m_typeId,
                        KeyQuery.mapObjectLock(LockMode.NOLOCK));
            }
        }

        return NativeRuntime.cardinality(klass.getName());
    }

    /** Determines if the backing shared memory object has been deleted.
      * @param operand Object to check.
      * @return true if the operand has been deleted, false otherwise. 
      * @exception ManagedClassError if the operand object is not of a Managed
      * class.
      */
    public static boolean isEmpty(Object operand)
        throws ManagedClassError
    {
        if (operand == null)
        {
            return true;
        }

        return NativeRuntime.isEmpty(getObjectReference(operand, "isEmpty"));
    }

    /** Internal method - do not use.  Will be removed
      * in a future release.
      * @param distributedQuery Distributed query
      */
    public static void setDistributedQuery(DistributedQuery distributedQuery)
    {
        m_distributedQuery = distributedQuery;
    }

    //
    // Package private routine to access a distributedQuery instance.
    //
    static DistributedQuery getDistributedQuery()
    {
        return m_distributedQuery;
    }

    //
    // Package private routine to use reflection to initialize a 
    // distributedQuery instance.
    //
    static synchronized void initializeDistributedQuery()
    {
        if (m_distributedQuery == null)
        {
            final String pmClass =
                "com.kabira.platform.highavailability.PartitionManager";

            try
            {
                Class<?> cls = Class.forName(pmClass);
                java.lang.reflect.Method im = cls.getMethod("initialize");
                im.setAccessible(true);
                im.invoke(null);
            }
            catch (java.lang.Exception ex)
            {
                //
                // ClassNotFoundException is ignored.
                //
                // Note that NoSuchMethodException, IllegalAccessException,
                // and InvocationTargetException are also ignored, but
                // probably shouldn't be.
                //
            }
        }
    }
    static DistributedQuery m_distributedQuery = null;

    /** 
     * Commit and abort triggers must be enabled in each transaction.
     * This method enables triggers for all methods in TransactionTriggers
     * (currently abort and commit).
     */
    static void enableTriggers(TransactionTriggers obj)
    {
        NativeRuntime.enableTriggers(getObjectReference(obj));
    }

    /**
     * Set the context class loader for this thread to this classes class
     * loader.
     * NOTE this assumes the context class loader is not set. This should
     * only be called when attaching a Thread via JNI AttachCurrentThread.
     */
    private static void setContextClassLoader()
    {
        //
        // FIX THIS: The IBM JVM asserts on this, commented out for now.
        //
        // assert(Thread.currentThread().getContextClassLoader() == null);
        //
        assert(ManagedObject.class.getClassLoader() != null);

        Thread.currentThread().setContextClassLoader(
                    ManagedObject.class.getClassLoader());
    }

    /** Package private class returned from extent() methods (needed to use the
      * for-each loop).
      */
    static class Extent<T> implements Iterable<T>
    {
        private String      m_typeName;
        private LockMode    m_objectLockMode;
        Extent(String typeName, LockMode objectLockMode)
        {
            m_typeName = typeName;
            m_objectLockMode = objectLockMode;
        }

        public Iterator<T> iterator()
        {
            return new ExtentIterator<T>(
                m_typeName,
                m_objectLockMode);
        }
    }

    /** Class wrapping readonly access to a Managed extent.
      */
    private static class ExtentIterator<T extends Object>
        implements java.util.Iterator<T>
    {
        private LockMode    m_objectLockMode;
        private long        m_cHandle;
        private T           m_next;

        ExtentIterator(String typeName, LockMode objectLock)
        {
            m_objectLockMode = objectLock;
            m_cHandle = _new(typeName, objectLock.ordinal());
            m_next = null;
        }

        public boolean hasNext()
        {
            if (m_next == null)
            {
                getNext();
            }
            return (m_next != null);
        }

        public T next()
        {
            if (m_next == null)
            {
                getNext();
            }
            if (m_next == null)
            {
                throw new java.util.NoSuchElementException();
            }

            T   t = m_next;
            m_next = null;

            if (m_objectLockMode == LockMode.READLOCK)
            {
                Transaction.readLockObject(t);
            }
            else if (m_objectLockMode == LockMode.WRITELOCK)
            {
                Transaction.writeLockObject(t);
            }
            else
            {
                assert ( m_objectLockMode == LockMode.NOLOCK );
            }

            return t;
        }

        public void remove()
        {
            throw new UnsupportedOperationException();
        }

        protected void finalize()
        {
            dispose();
        }

        private void dispose()
        {
            if (m_cHandle != 0)
            {
                _delete(m_cHandle);
            }
            m_cHandle = 0;
        }

        private void getNext()
        {
            assert ( m_next == null );

            if (m_cHandle != 0)
            {
                m_next = _next(m_cHandle);

                //
                // FIX THIS: Accessing the extent uses a CGObject that does a
                // detach when _next() returns, allowing the reference count
                // to go to zero (issue FLUENCY-3716. We use isEmpty() in an
                // attempt to work around this.
                // 
                while (m_next != null && isEmpty(m_next))
                {
                    m_next = _next(m_cHandle);
                }

                if (m_next == null)
                {
                    dispose();
                }
            }
        }

        native long _new(String typeName, int objectLock);
        native T _next(long cHandle);
        native void _delete(long cHandle);
    }
}

/**
 * Used by the classloader to mark Managed classes as being managed.
 */
interface ManagedMarker
{
    abstract byte[] _getObjectReference();
}