//
// Name
//  $RCSfile: KeyQuery.java,v $
// 
// Copyright
//  Copyright 2009-2012 Cloud Software Group, Inc. ALL RIGHTS RESERVED. 
//  Cloud Software Group, Inc. Confidential Information
//
// History
//  $Revision: 1.1.2.17.2.4 $ $Date: 2012/11/01 05:07:21 $
//
package com.kabira.platform;

import java.util.ArrayList;
import java.util.Iterator;
import com.kabira.platform.KeyConstructor;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

//
// Common utility class that is package private so it can be shared.
//
class FieldEntry
{
    String              m_name;
    Object              m_value;
    KeyComparisonOperator       m_op;
}


/**
 * Class used to define a query and obtain results using keys. 
 * <p>
 * Instances of this class are created by KeyManager, so it has no
 * public constructors.
 * <p>
 * Once a query is defined, it may be executed multiple times.
 */
public final class KeyQuery<T>
{
    /**
     * Returns the results of a query.
     *
     * @param objectLock LockMode to apply to each instance returned.
     *
     * @return Iterable containing set.
     *
     * @exception KeyIncompleteError
     *  All the fields for the key have not been defined. 
     * <p>
     * Executes the previously defined query and returns the resulting set.
     * For ordered keys, the default orderBy of ASCENDING is used.
     */
    public Iterable<T> getResults(
            LockMode objectLock)
        throws KeyIncompleteError
    {
        validateExecution();
        if (objectLock == null)
        {
            throw new NullPointerException();
        }
        if (m_hasKeyCoverage)
        {
            return new KeyResultSet<T>(objectLock);
        }
        assert( m_descriptor.m_ordered == true );
        return getResults(KeyOrderedBy.ASCENDING, objectLock);
    }

    /**
     * Returns the results for a query using an ordered key.
     *
     * @param orderBy
     * @param objectLock
     *
     * @return Iterable containing set.
     *
     * @exception KeyIncompleteError
     *  All the fields for the key have not been defined. 
     *
     * @exception KeyIllegalKeyTypeError
     *  The key is not ordered.
     * <p>
     * Executes the previously defined query and returns the resulting set.
     */
    public Iterable<T> getResults(
            KeyOrderedBy orderBy,
            LockMode objectLock)
        throws KeyIncompleteError
    {
        validateExecution();
        validateOrdered();
        if (objectLock == null)
        {
            throw new NullPointerException();
        }
        return new KeyResultSet<T>(orderBy, objectLock);
    }

    /**
     * Returns the instance matching the given unique key.
     *
     * @param objectLock The object lock applied if an instance is found.
     *
     * @return Object containing result, or null if key not found.
     *
     * @exception KeyIncompleteError
     *  The fields for the key have not been defined. 
     *
     * @exception KeyIllegalKeyTypeError
     *  The key is not unique.
     * <p>
     * Executes the previously defined query and returns an instance.
     */
    public T getSingleResult(LockMode objectLock)
        throws KeyIncompleteError, KeyIllegalKeyTypeError
    {
        validateExecution();
        if ((m_descriptor.m_unique == false) ||
            (m_descriptor.m_ordered == true && m_hasKeyCoverage == false))
        {
            throw new KeyIllegalKeyTypeError(
                "Key is not unique");
        }
        return attachObject(objectLock, KeyOptNoPlaceholder);
    }

    /**
     * Returns the mininum value for the given ordered key.
     *
     * @param objectLock The object lock applied if an instance is found.
     *
     * @return Object containing result, or null if key not found.
     *
     * @exception KeyIllegalKeyTypeError
     *  The key is not ordered.
     *
     * @exception KeyMalformedQueryError
     *  An illegal operator was used when defining the query.
     * <p>
     * Executes the previously defined query (if any) and returns an
     * instance containing the minimum value. If no query was defined,
     * the instance containing the minimum key is returned. If a query was
     * defined, the instance containing the minimum key value that
     * matches the given fields is returned.
     */
    public T getMinimumResult(LockMode objectLock)
        throws KeyMalformedQueryError, KeyIllegalKeyTypeError
    {
        validateOrdered();
        if (m_query == null)
        {
            m_query = new CompiledQuery();
            m_query.m_keyInfo1 = new KeyInfo();
        }
        CompiledQuery query = m_query;
        if (m_query.m_filters != null)
        {
            query = compileOrderedQuery(CompileFilter.FILTER_NONE);
        }
        validateMinMaxQuery(query);
        return attachMinimum(query, objectLock);
    }

    /**
     * Returns the maximum value for the given ordered key.
     *
     * @param objectLock The object lock applied if an instance is found.
     *
     * @return Object containing result, or null if key not found.
     *
     * @exception KeyIllegalKeyTypeError
     *  The key is not ordered.
     *
     * @exception KeyMalformedQueryError
     *  An illegal operator was used when defining the query.
     * <p>
     * Executes the previously defined query (if any) and returns an
     * instance containing the maximum value. If no query was defined,
     * the instance containing the maximum key is returned. If a query was
     * defined, the instance containing the maximum key value that
     * matches the given fields is returned.
     */
    public T getMaximumResult(LockMode objectLock)
        throws KeyMalformedQueryError, KeyIllegalKeyTypeError
    {
        validateOrdered();
        if (m_query == null)
        {
            m_query = new CompiledQuery();
            m_query.m_keyInfo1 = new KeyInfo();
        }
        CompiledQuery query = m_query;
        if (m_query.m_filters != null)
        {
            query = compileOrderedQuery(CompileFilter.FILTER_NONE);
        }
        validateMinMaxQuery(query);
        return attachMaximum(query, objectLock);
    }

    /**
     * Returns the instance for the given unique key.
     *
     * @param  objectLock The object lock applied if a pre-existing instance
     *      is found.
     * @param  additionalFields Additional field values to use if an
     *      instance in created. These values are ignored if
     *      the instance already exists.  null can be specified
     *      if no additional field values are needed.
     *
     * @return Object containing result.
     *
     * @exception KeyIncompleteError
     *  The fields for the key have not been defined. 
     *
     * @exception KeyIllegalKeyTypeError
     *  The key is not unique.
     *
     * @exception KeyIllegalFieldError
     *  A field in the additionalFields list is not valid.
     * <p>
     * Executes the previously defined query and returns an instance.
     * This method will atomically insure that an instance of
     * the type will be created when searching for a instance by key.
     * The additionalFields list passed in allows the programmer to
     * populate secondary key fields if the instance is created.
     * This should be used instead of doing:
     *<pre>
KeyedObject ko = kq.getSingleResult(lockMode);
if (ko == null)
{
    ko = new KeyedObject(keys);
}</pre>
     * <p>
     * The above new can throw an ObjectNotUniqueError exception
     * if another transaction creates the instance between the 
     * getSingleResult() and the new call. 
     */
    @SuppressWarnings("unchecked")
    public T getOrCreateSingleResult(
            LockMode objectLock,
            KeyFieldValueList additionalFields)
        throws KeyIncompleteError, KeyIllegalKeyTypeError,
            KeyIllegalFieldError
    {
        validateExecution();
        if (m_descriptor.m_unique == false)
        {
            throw new KeyIllegalKeyTypeError(
                "Key is not unique");
        }

        ArrayList<CreateBuffer> createValues = null;

        if (additionalFields != null)
        {
            createValues = new ArrayList<CreateBuffer>();
            for (FieldEntry fe : additionalFields.m_entries)
            {
                //
                // We need to audit that these fields are
                // not part of the key. Otherwise we'll
                // create the wrong instance in the "on
                // empty" case, since the key will
                // subsequently be updated.
                //
                if (findField(fe))
                {
                    throw new KeyIllegalFieldError(
                        "Field " + fe.m_name +
                        " in additionalFields list " +
                        "is part of the key.");
                }
                CreateBuffer cb = new CreateBuffer(fe);
                createValues.add(cb);
            }
        }
 
        T obj = null;
        boolean retry = true;
        int retryCount = 0;
        while (retry)
        {
            obj = attachObject(objectLock, KeyOptNoPlaceholder);
            if (obj != null)
            {
                retry = false;
            }
            else
            {
                try
                {
                    //
                    // Attempt to create the key'd object using the
                    // constructor. The placeholder created above will
                    // prevent another transaction from creating the
                    // instance from underneath us.
                    //
                    // Note: we cast and use the above SuppressWarnings
                    // annotation since KeyConstructor uses reflection so it
                    // cannot be a generic.
                    //
                    KeyConstructor  kc = new KeyConstructor();
                    for (FieldEntry fe : m_entries)
                    {
                        kc.addKeyValue(fe.m_name, fe.m_value);
                    }
                    if (additionalFields != null)
                    {
                        for (FieldEntry fe : additionalFields.m_entries)
                        {
                            kc.addKeyValue(fe.m_name, fe.m_value);
                        }
                    }
                    obj = (T)kc.invokeConstructor(m_descriptor.m_className);
                    if (obj == null)
                    {
                        //
                        // Cannot construct instance, create a shared
                        // memory image.
                        //
                        obj = createObject(createValues);
                    }
                    retry = false;
                }
                catch (ObjectNotUniqueError ex)
                {
                    if (retryCount++ > MaxSelectRetries)
                    {
                        throw ex;
                    }
                    //
                    // Just ignore this exception, we'll try and select again.
                    //
                }
            }
        }
        return obj;
    }

    /**
     * Returns the number of instances of the given key.
     *
     * @return Number of instances.
     *
     * @exception KeyIncompleteError
     *  All the fields for the key have not been defined. 
     * <p>
     * Executes the previously defined query and returns the number of
     * instances that would result.
     * <p>
     * No transaction locks are take when this method executes.
     * This means the number returned by cardinality() may
     * change even if called multiple times within a single
     * transaction.
     *
     */
    public int cardinality()
        throws KeyIncompleteError
    {
        validateExecution();

        KeyIterator<T> ki = new KeyIterator<T>(
                        KeyOrderedBy.ASCENDING,
                        LockMode.NOLOCK);

        return ki.size();
    }

    /**
     * Defines the fields that form a key query.
     *
     * @param  keyFields The fields to use.
     *
     * @exception KeyIncompleteError
     *  All the fields for the key have not been defined. 
     *
     * @exception KeyIllegalFieldError
     *  A given field is not  part of the key.
     *
     * @exception KeyMalformedQueryError
     *  The resulting key lookup cannot perform a range query
     *  on an ordered key, or duplicate fields exist 
     *  for a non-ordered key.
     * <p>
     * When executed, this defines the values used for a key lookup. 
     * Any previous query is overwritten.
     */
    public void defineQuery(
            KeyFieldValueList keyFields)
        throws KeyIllegalFieldError, KeyMalformedQueryError
    {
        processFields(keyFields.getEntries());

        if (!m_descriptor.m_ordered && !m_hasKeyCoverage)
        {
            //
            // Build missing list. Note that we ignore dups, since
            // KeyMalformedQueryError is thrown when this happens.
            //
            String missing = "";
            for (FieldDescriptor fd : m_descriptor.m_fields)
            {
                boolean found = false;
                for (FieldEntry fe : m_entries)
                {
                    if (fd.m_name.equals(fe.m_name))
                    {
                        found = true;
                        break;
                    }
                }
                if (found == false)
                {
                    missing += ", missing field '" + fd.m_name + "'";
                }
            }
            throw new KeyIncompleteError(
                "Not all required fields are present" + missing);
        }
        else if (!m_hasKeyCoverage)
        {
            validateOrderedKey();
        }

        m_query = compileQuery();
    }

    /**
     * Defines the fields that form a range query.
     *
     * @param  keyFields The fields to use.
     *
     * @exception KeyIllegalFieldError
     *  A given field is not  part of the key.
     *
     * @exception KeyMalformedQueryError
     *  The resulting key lookup cannot perform a range query
     *  on an ordered key, duplicate fields are defined
     *  for a non-ordered key, or a range query was attempted
     *  on a non-ordered key.
     * <p>
     * When executed, this defines the values used for a range query
     * on an ordered key. Any previous query is overwritten.
     */
    public void defineQuery(
            KeyFieldValueRangeList keyFields)
        throws KeyIllegalFieldError, KeyMalformedQueryError
    {
        validateOrdered();

        processFields(keyFields.getEntries());

        if (!m_hasKeyCoverage)
        {
            validateOrderedKey();
        }

        m_query = compileQuery();
    }

    /**
     * Creates a human readable query string.
     *
     * @exception KeyIncompleteError
     *  All the fields for the key have not been defined. 
     * <p>
     * This method returns a string containing a "select" or "for"
     * statement. The string also contains any optimization warnings for
     * the defined query.
     * This information can be used to help diagnose queries.
     */
    public String toString()
        throws KeyIncompleteError
    {
        String res = new String();

        if (m_descriptor.m_unique && m_hasKeyCoverage)
        {
            res += "select obj from ";
        }
        else
        {
            res += "for obj in ";
        }
        res += m_descriptor.m_className;
        res += " using ";
        res += m_descriptor.m_keyName;
        res += " where (";

        boolean firstField = true;
        for (FieldEntry fe : m_entries)
        {
            if (!firstField)
            {
                res += " && ";
            }
            else
            {
                firstField = false;
            }
            res += fe.m_name;
            res += getComparisonOp(fe.m_op);
            res += fe.m_value;
        }
        res += ")";
        if (m_descriptor.m_unique && m_hasKeyCoverage)
        {
            res += ";";
        }
        else
        {
            res += " { }";
        }

        if (m_descriptor.m_unique && m_hasKeyCoverage)
        {
            KeyConstructor  kc = new KeyConstructor();
            for (FieldEntry fe : m_entries)
            {
                kc.addKeyValue(fe.m_name, fe.m_value);
            }
            res += " Java constructor: ";
            res += kc.displayConstructor(m_descriptor.m_className);
        }

        if (m_query != null && m_query.m_filters != null)
        {
            for (int i = 0; i < m_query.m_filters.size(); i++)
            {
                KeyInfo filter = m_query.m_filters.get(i);
                int keyDepth = 0;

                for (FieldDescriptor fd : m_descriptor.m_fields)
                {
                    if (keyDepth == filter.m_keyDepth)
                    {
                        res += " [ Warning: field '";
                        res += fd.m_name;
                        res += "' filtered ]";
                        break;
                    }
                    keyDepth++;
                }
            }
        }

        return res;
    }

    /////////////////////////////////////////////////////////////////
    //
    // Private fields, classes and utility routines
    //
    /////////////////////////////////////////////////////////////////

    //
    // Note: The following enumeration "know" about the actual values
    // in the C++ enum definitions. We use them instead of java enums
    // to avoid having to map things in JNI code.
    //

    // enumeration values for SWRBTree::RBDirection
    private static final int SWRBTreeAscending  = 1;
    private static final int SWRBTreeDescending = 2;

    // enumeration values for OSKeyOpt::Placeholder
    private static final int KeyOptCreatePlaceholder= 1;
    private static final int KeyOptNoPlaceholder    = 2;

    // enumeration values for OSKeyOpt::ObjectLock
    private static final int KeyOptReadLock     = 1;
    private static final int KeyOptWriteLock    = 2;
    private static final int KeyOptNoLock       = 3;

    // enumeration values for CGObject::MaxSelectRetries
    private static final int MaxSelectRetries   = 10;

    // enumeration values for ObjSrv::RangeOperator
    private static final int ObjSrv_EQ      = 1;
    private static final int ObjSrv_NEQ     = 2;
    private static final int ObjSrv_GTE     = 3;
    private static final int ObjSrv_GT      = 4;
    private static final int ObjSrv_LTE     = 5;
    private static final int ObjSrv_LT      = 6;

    // enumeration values for DSETypeCode
    private static final int tkInvalid      = 0;
    private static final int tkShort        = 1;
    private static final int tkLong         = 2;
    private static final int tkLongLong     = 3;
    private static final int tkUShort       = 4;
    private static final int tkULong        = 5;
    private static final int tkULongLong        = 6;
    private static final int tkFloat        = 7;
    private static final int tkDouble       = 8;
    private static final int tkBoolean      = 9;
    private static final int tkChar         = 10;
    private static final int tkOctet        = 11;
    private static final int tkObjectReference  = 12;
    private static final int tkStruct       = 13;
    private static final int tkEnum         = 14;
    private static final int tkString       = 15;
    private static final int tkSequence     = 16;
    private static final int tkArray        = 17;
    private static final int tkException        = 18;
    private static final int tkVoid         = 19;
    private static final int tkOffset       = 20;
    private static final int tkSize         = 21;
    private static final int tkWChar        = 22;
    private static final int tkAny          = 23;
    private static final int tkNative       = 24;
    private static final int tkType         = 25;
    private static final int tkUnion        = 26;
    private static final int tkDate         = 27;

    enum CompileFilter
    {
        FILTER_LTEGTE,
        FILTER_NONE
    }

    //
    // Return a string containing the Java type for the given typeCode
    //
    private static String getTCString(int tc)
    {
        String  ret = "<unknown>";
        switch (tc)
        {
            case tkShort:
            case tkUShort:
                ret = "short";
                break;
            case tkLong:
            case tkULong:
                ret = "int";
                break;
            case tkULongLong:
            case tkLongLong:
                ret = "long";
                break;
            case tkFloat:
                ret = "float";
                break;
            case tkDouble:
                ret = "double";
                break;
            case tkBoolean:
                ret = "boolean";
                break;
            case tkWChar:
                ret = "char";
                break;
            case tkChar:
            case tkOctet:
                ret = "byte";
                break;
            case tkObjectReference:
                ret = "Object";
                break;
            case tkString:
                ret = "String";
                break;
            case tkDate:
                ret = "java.util.Date";
                break;
            default:
                break;
        }
        return ret;
    }

    //
    // Return a string containing the operation
    //
    private static String getComparisonOp(KeyComparisonOperator op)
    {
        String ret = null;
        switch (op)
        {
            case EQ:
                ret = " == ";
                break;
            case NEQ:
                ret = " != ";
                break;
            case GTE:
                ret = " >= ";
                break;
            case GT:
                ret = " > ";
                break;
            case LTE:
                ret = " <= ";
                break;
            case LT:
                ret = " < ";
                break;
        }
        return ret;
    }

    //
    // Return the KTP typeCode for the given java object
    //
    private static int getTypeCode(Object obj)
    {
        int typeCode = tkInvalid;
        if (obj instanceof Integer)
        {
            typeCode = tkLong;
        }
        else if (obj instanceof Long)
        {
            typeCode = tkLongLong;
        }
        else if (obj instanceof String)
        {
            typeCode = tkString;
        }
        else if (obj instanceof Short)
        {
            typeCode = tkShort;
        }
        else if (obj instanceof Character)
        {
            typeCode = tkWChar;
        }
        else if (obj instanceof Float)
        {
            typeCode = tkFloat;
        }
        else if (obj instanceof Double)
        {
            typeCode = tkDouble;
        }
        else if (obj instanceof Enum)
        {
            typeCode = tkEnum;
        }
        else if (obj instanceof java.util.Date)
        {
            typeCode = tkDate;
        }
        else if (obj instanceof Boolean)
        {
            typeCode = tkBoolean;
        }
        else if (obj instanceof Byte)
        {
            typeCode = tkOctet;
        }
        else
        {
            typeCode = tkObjectReference;
        }
        assert( typeCode != tkInvalid );
        return typeCode;
    }
    //
    // Return the number of bytes a null key slot would contain for
    // the given typeCode. Used when building key filters.
    //
    private static int getKeyOffset(int tc)
    {
        int size = 0;
        switch (tc)
        {
            case tkShort:
            case tkUShort:
                size = 2;
                break;
            case tkLong:
            case tkULong:
            case tkFloat:
            case tkWChar:
            case tkEnum:
                size = 4;
                break;
            case tkULongLong:
            case tkLongLong:
            case tkDouble:
            case tkDate:
                size = 8;
                break;
            case tkBoolean:
            case tkChar:
            case tkOctet:
                size = 1;
                break;
            case tkObjectReference:
                size = 24;
                break;
            case tkString:
                size = 8;   // zero length string
                break;
        }
        assert( size != 0 );
        return size;
    }

    //
    // Descriptors used to manage key information
    //
    private static class FieldDescriptor
    {
        FieldDescriptor(String name, int typeCode)
        {
            m_name = name;
            m_typeCode = typeCode;
        }
        private final String        m_name;
        private final int       m_typeCode;

        //
        // Return runtime mapping as per the ERD.
        //
        int getTypeCode()
        {
            int typeCode = m_typeCode;
            switch (typeCode)
            {
                case tkChar:
                    typeCode = tkOctet;
                    break;
                case tkUShort:
                    typeCode = tkShort;
                    break;
                case tkULong:
                    typeCode = tkLong;
                    break;
                case tkULongLong:
                    typeCode = tkLongLong;
                    break;
                default:
                    break;
            }
            assert( typeCode != tkInvalid );
            return typeCode;
        }
    }

    private static Map<String, KeyDescriptor>   m_map =
        new ConcurrentHashMap<String, KeyDescriptor>();

    private static class KeyDescriptor
    {
        KeyDescriptor(String className, String keyName)
        {
            m_className = className;
            m_keyName = keyName;
            m_fields = new ArrayList<FieldDescriptor>();
            m_ordered = false;
            m_unique = false;
        }
        //
        // These are define by the KeyQuery() constructor
        //
        private final String        m_className;
        private final String        m_keyName;
        //
        // These are all populated by _getKeyDescriptor()
        // 
        private ArrayList<FieldDescriptor> m_fields;
        private boolean         m_ordered;
        private boolean         m_unique;
        private int         m_objDomainId;
        private int         m_objTypeId;
        private int         m_keyDomainId;
        private int         m_keyTypeId;
    }

    //
    // Low level buffer class that maps to the KTP runtime. 
    //
    // Types supported (from ERD)
    //
    //  o All basic Java types (boolean, byte, char, short,
    //    int, long, float, double)
    //
    //  o Wrapper classes for the basic Java types
    //    (Integer, Short, Character, etc.) 
    //
    //  o java.lang.String; 
    //
    //  o java.util.Date; 
    //
    //  o Enum types; 
    //
    //  o Managed Object types. 
    //
    private static class KeyBuffer extends AnyBuffer
    {
        void addData(Object obj)
        {
            boolean wasPut = putObject(obj);
            assert( wasPut );
        }
    }

    private static class KeyInfo extends KeyBuffer
    {
        KeyInfo()
        {
            m_rop = ObjSrv_EQ;
            m_keyDepth = 1;
        }
        KeyInfo(int rop)
        {
            m_rop = rop;
            m_keyDepth = 1;
        }
        void addKeyData(Object obj)
        {
            addData(obj);
        }
        int         m_rop;
        int         m_keyDepth;
    }

    private static class CreateBuffer extends KeyBuffer
    {
        CreateBuffer(FieldEntry fe) throws KeyIllegalFieldError
        {
            m_name = fe.m_name;
            m_typeCode = getTypeCode(fe.m_value);
            try
            {
                writeObject(fe.m_value);
            }
            catch (IllegalArgumentException iae)
            {
                throw new KeyIllegalFieldError(
                    "Field " + fe.m_name + " containing " +
                    fe.m_value.getClass() + " is not supported");
            }
        }
        String          m_name;
        int         m_typeCode;
    }

    //
    // Class containing a compiled query
    //
    private static class CompiledQuery
    {
        CompiledQuery()
        {
            m_keyInfo1 = null;
            m_keyInfo2 = null;
            m_filters = null;
            m_hasRange = false;
        }

        void addRange(KeyInfo keyInfo)
        {
            if (m_keyInfo1 == null)
            {
                m_keyInfo1 = keyInfo;
            }
            else
            {
                assert( m_keyInfo2 == null );
                m_keyInfo2 = keyInfo;
            }
            m_hasRange = true;
        }

        void addKeyInfo(KeyInfo keyInfo)
        {
            assert( !m_hasRange );
            assert( m_keyInfo1 == null );
            m_keyInfo1 = keyInfo;
        }

        void addFilter(KeyInfo keyInfo)
        {
            assert( m_hasRange );
            if (m_filters == null)
            {
                m_filters = new ArrayList<KeyInfo>();
            }
            m_filters.add(keyInfo);
        }

        KeyInfo         m_keyInfo1;
        KeyInfo         m_keyInfo2;
        ArrayList<KeyInfo>  m_filters; 
        boolean         m_hasRange;
    }

    //
    // Private data members that use the above private classes
    //
    private KeyDescriptor       m_descriptor;
    private CompiledQuery       m_query; 
    private ArrayList<FieldEntry>   m_entries; 
    private boolean         m_hasKeyCoverage;

    //
    // Class that implements the Iterable returned from getResults()
    //
    private class KeyResultSet<T extends Object>
        implements Iterable<T>
    {
        KeyOrderedBy    m_orderBy;
        LockMode    m_objectLock;

        KeyResultSet(KeyOrderedBy orderBy, LockMode objectLock)
        {
            m_orderBy = orderBy;
            m_objectLock = objectLock;
        }
        KeyResultSet(LockMode objectLock)
        {
            m_orderBy = KeyOrderedBy.ASCENDING;
            m_objectLock = objectLock;
        }

        public Iterator<T> iterator()
        {
            return new KeyIterator<T>(m_orderBy, m_objectLock);
        }
    }

    //
    // Class that implements the Iterator returned from Iterable
    //
    private class KeyIterator<T extends Object>
        implements java.util.Iterator<T>
    {
        private long    m_cHandle;
        private T   m_next;

        KeyIterator(KeyOrderedBy orderBy, LockMode objectLock)
        {
            assert( m_query.m_keyInfo1 != null );
            if (m_query.m_hasRange == false)
            {
                m_cHandle = _initKey(
                    m_descriptor.m_objDomainId,
                    m_descriptor.m_objTypeId,
                    m_descriptor.m_keyDomainId,
                    m_descriptor.m_keyTypeId,
                    mapObjectLock(objectLock),
                    m_query.m_keyInfo1.array());
            }
            else if (m_query.m_keyInfo2 == null)
            {
                assert( m_query.m_hasRange == true );
                assert( m_query.m_keyInfo2 == null );
                Object [] filters = (m_query.m_filters == null)
                    ? null : m_query.m_filters.toArray();
                m_cHandle = _initRange1(
                    m_descriptor.m_objDomainId,
                    m_descriptor.m_objTypeId,
                    m_descriptor.m_keyDomainId,
                    m_descriptor.m_keyTypeId,
                    mapOrderBy(orderBy),
                    mapObjectLock(objectLock),
                    m_query.m_keyInfo1.m_keyDepth,
                    m_query.m_keyInfo1.m_rop,
                    m_query.m_keyInfo1.array(),
                    filters);
            }
            else
            {
                assert( m_query.m_hasRange == true );
                assert( m_query.m_keyInfo2 != null );
                Object [] filters = (m_query.m_filters == null)
                    ? null : m_query.m_filters.toArray();
                m_cHandle = _initRange2(
                    m_descriptor.m_objDomainId,
                    m_descriptor.m_objTypeId,
                    m_descriptor.m_keyDomainId,
                    m_descriptor.m_keyTypeId,
                    mapOrderBy(orderBy),
                    mapObjectLock(objectLock),
                    m_query.m_keyInfo1.m_keyDepth,
                    m_query.m_keyInfo1.m_rop,
                    m_query.m_keyInfo1.array(),
                    m_query.m_keyInfo2.m_keyDepth,
                    m_query.m_keyInfo2.m_rop,
                    m_query.m_keyInfo2.array(),
                    filters);
            }
            m_next = _next(m_cHandle);
        }

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

        public T next()
        {
            T t = m_next;

            m_next = _next(m_cHandle);

            return t;
        }

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

        protected void finalize()
        {
            if (m_cHandle != 0)
            {
                _delete(m_cHandle);
            }
            m_cHandle = 0;
        }

        int size()
        {
            return _size(m_cHandle);
        }

        native long _initKey(
                int objDomainId,
                int objTypeId,
                int keyDomainId,
                int keyTypeId,
                int objLock,
                byte [] keyData);
        native long _initRange1(
                int objDomainId,
                int objTypeId,
                int keyDomainId,
                int keyTypeId,
                int direction,
                int objLock,
                int keyDepth,
                int rop,
                byte [] keyData,
                Object [] filters);
        native long _initRange2(
                int objDomainId,
                int objTypeId,
                int keyDomainId,
                int keyTypeId,
                int direction,
                int objLock,
                int keyDepth1,
                int rop1,
                byte [] keyData1,
                int keyDepth2,
                int rop2,
                byte [] keyData2,
                Object [] filters);

        native int _size(long cHandle);
        native T _next(long cHandle);
        native void _delete(long cHandle);
    }

    //
    // Constructors are not exposed.
    //
    private KeyQuery() { }
    KeyQuery(
        final java.lang.Class<T> klass,
        final String keyName) throws KeyUnknownKeyNameError
    {
        String keyDescriptorKey = klass.getName() + "." + keyName;

        m_descriptor = m_map.get(keyDescriptorKey);

        if (m_descriptor == null)
        {
            m_descriptor = new KeyDescriptor(klass.getName(), keyName);

            if (!_getKeyDescriptor(m_descriptor))
            {
                throw new KeyUnknownKeyNameError(
                    "Unknown keyName " + keyName);
            }

            // No synchronization is needed here.  If two threads
            // get here at the same time, the second put will replace
            // the first, and the GC will clean up at some later time.
            m_map.put(keyDescriptorKey, m_descriptor);
        }
        m_hasKeyCoverage = false;
    }

    private void processFields(ArrayList<FieldEntry> entries)
        throws KeyIllegalFieldError, KeyMalformedQueryError
    {
        //
        // Clear out previous query to insure validateExecution()
        // fails if the new query encounters an error.
        //
        m_query = null;

        //
        // entries contains a copy of the FieldEntry array defined by
        // the user. We keep a copy around mostly for so that
        // toString() can access it, otherwise we could just pass
        // it around for processing and compilation.
        //
        m_entries = entries;

        //
        // Validate the fields we just stored.
        //
        validateFields();

        //
        // Determine if the fields cover the key.
        //
        checkForKeyCoverage();
    }

    private void validateFields()
        throws KeyIllegalFieldError, KeyMalformedQueryError
    {
        //
        // Validate each field
        //
        int count = 0;
        for (FieldEntry fe : m_entries)
        {
            validateField(fe);
            count += 1;
        }
        if (count == 0)
        {
            throw new KeyMalformedQueryError("No fields defined");
        }

        //
        // Check for dups
        //
        if ((!m_descriptor.m_ordered) && (count > 1))
        {
            validateNoDups();
        }
    }

    private void validateField(FieldEntry fe)
        throws KeyIllegalFieldError, KeyMalformedQueryError
    {
        boolean found = false;

        for (FieldDescriptor fd : m_descriptor.m_fields)
        {
            if (fe.m_name.equals(fd.m_name))
            {
                validateValue(fd, fe.m_value);
                found = true;
            }
        }
        if (!found)
        {
            throw new KeyIllegalFieldError(
                "Field " + fe.m_name +
                " is not part of the key");
        }
    }

    private boolean findField(FieldEntry fe)
    {
        boolean found = false;

        for (FieldDescriptor fd : m_descriptor.m_fields)
        {
            if (fe.m_name.equals(fd.m_name))
            {
                return true;
            }
        }
        return false;
    }

    private void validateNoDups()
        throws KeyMalformedQueryError
    {
        assert( !m_descriptor.m_ordered );

        for (FieldDescriptor fd : m_descriptor.m_fields)
        {
            int count = 0;
            for (FieldEntry fe : m_entries)
            {
                if (fd.m_name.equals(fe.m_name))
                {
                    count += 1;
                }
            }
            if (count > 1)
            {
                throw new KeyMalformedQueryError(
                    "Field " + fd.m_name +
                    " exists more than once in " +
                    "the KeyFieldValueList list");
            }
        }
    }

    private void validateValue(FieldDescriptor fd, Object value)
        throws KeyIllegalFieldError
    {
        assert( value != null );

        int typeCode = getTypeCode(value);

        if (typeCode != fd.getTypeCode())
        {
            throw new KeyIllegalFieldError(
                "Illegal type " + getTCString(typeCode) +
                " for field " + fd.m_name + ", expected " +
                getTCString(fd.getTypeCode()));
        }
    }

    private void checkForKeyCoverage() 
    {
        //
        // If any of the field entries are not ==, we don't have
        // key coverage.
        //
        for (FieldEntry fe : m_entries)
        {
            if (fe.m_op != KeyComparisonOperator.EQ)
            {
                m_hasKeyCoverage = false;
                return;
            }
        }

        //
        // If all fields are defined once and only one we have
        // a complete key.
        //
        int count = 0;
        int [] fieldCnt = new int[m_descriptor.m_fields.size()];
        for (FieldDescriptor fd : m_descriptor.m_fields)
        {
            fieldCnt[count] = 0;
            for (FieldEntry fe : m_entries)
            {
                if (fd.m_name.equals(fe.m_name))
                {
                    fieldCnt[count] += 1;
                }
            }
            count += 1;
        }
        m_hasKeyCoverage = true;
        for (int i = 0; i < count; i++)
        {
            if (fieldCnt[i] != 1)
            {
                m_hasKeyCoverage = false;
                break;
            }
        }
    }

    //
    // If key coverage doesn't exist, make sure ordered query
    // isn't malformed.
    //
    private void validateOrderedKey()
        throws KeyMalformedQueryError
    {
        assert( !m_hasKeyCoverage );

        String      firstField;
        int         numKeys = 0;

        firstField = m_descriptor.m_fields.get(0).m_name;

        for (FieldEntry fe : m_entries)
        {
            if (!fe.m_name.equals(firstField) && numKeys == 0)
            {
                throw new KeyMalformedQueryError(
                    "Range queries must use the '" +
                    firstField +
                    "' field as the first entry");
            }
            if (fe.m_op == KeyComparisonOperator.NEQ &&
                numKeys == 0)
            {
                throw new KeyMalformedQueryError(
                    "Illegal operator != in range query");
            }
            numKeys += 1;
        }
    }

    private void validateMinMaxQuery(CompiledQuery query)
        throws KeyMalformedQueryError
    {
        if (m_entries != null)
        {
            for (FieldEntry fe : m_entries)
            {
                if (fe.m_op != KeyComparisonOperator.EQ &&
                    fe.m_op != KeyComparisonOperator.GTE &&
                    fe.m_op != KeyComparisonOperator.LTE)
                {
                    throw new KeyMalformedQueryError(
                        "Illegal operator" + getComparisonOp(fe.m_op) +
                        "used in query \"" + this + "\""); 
                }
            }
        }
        if (query.m_filters != null)
        {
            throw new KeyMalformedQueryError(
                        "filter present on query \"" + this + "\"");
        }
    }

    private void validateExecution()
        throws KeyIncompleteError
    {
        if (m_query == null)
        {
            throw new KeyIncompleteError("No query has been defined");
        }
        if (m_entries == null)
        {
            throw new KeyIncompleteError("No fields have been defined");
        }

        // We should have passed all audits here
        assert( m_hasKeyCoverage || m_descriptor.m_ordered );
    }

    private void validateOrdered()
        throws KeyIllegalKeyTypeError
    {
        if (m_descriptor.m_ordered == false)
        {
            throw new KeyIllegalKeyTypeError(
                "Key is not ordered");
        }
    }

    private CompiledQuery compileSimpleQuery()
    {
        assert( m_hasKeyCoverage == true );

        CompiledQuery query = new CompiledQuery();

        KeyInfo keyInfo = new KeyInfo();

        //
        // build key data based on field order
        //
        for (FieldDescriptor fd : m_descriptor.m_fields)
        {
            for (FieldEntry fe : m_entries)
            {
                if (fd.m_name.equals(fe.m_name))
                {
                    keyInfo.addKeyData(fe.m_value);
                    break;
                }
            }
        }

        query.addKeyInfo(keyInfo);

        return query;
    }

    private CompiledQuery compileOrderedQuery(CompileFilter filter)
    {
        assert( m_descriptor.m_ordered == true );

        CompiledQuery query = new CompiledQuery();

        //
        // Build first range. This is either a multi-part key
        // defined using == clauses, or a one field key using
        // another comparison operator.
        //
        String firstField = m_descriptor.m_fields.get(0).m_name;
        Iterator<FieldEntry>    iter = m_entries.iterator();

        assert( iter.hasNext() );
        FieldEntry fe = iter.next();

        assert( firstField.equals(fe.m_name) );
        assert( fe.m_op != KeyComparisonOperator.NEQ );
        KeyComparisonOperator firstOp = fe.m_op;

        KeyInfo keyInfo = new KeyInfo(mapComparisonOp(fe.m_op));

        if (fe.m_op == KeyComparisonOperator.EQ)
        {
            //
            // Build the key based on the number of == operators.
            //
            createEqualsKey(keyInfo, filter);

            //
            // Move the iterator to the next field based on
            // the key depth of the built key.
            //
            assert( keyInfo.m_keyDepth > 0 );
            int keyDepth = keyInfo.m_keyDepth;

            while (keyDepth > 0)
            {
                fe = iter.hasNext() ? iter.next() : null;
                keyDepth--;
            }
        }
        else
        {
            keyInfo.addKeyData(fe.m_value);
            fe = iter.hasNext() ? iter.next() : null;
        }
        query.addRange(keyInfo);

        // 
        // The field entry is now positioned to the next field.
        // Determine if we have a range.
        //
        if (fe != null && firstField.equals(fe.m_name) &&
            isRange(firstOp, fe.m_op))
        {
            keyInfo = new KeyInfo(mapComparisonOp(fe.m_op));
            keyInfo.addKeyData(fe.m_value);
            query.addRange(keyInfo);
            fe = iter.hasNext() ? iter.next() : null;
        }

        //
        // The rest are filters
        //
        while (fe != null)
        {
            query.addFilter(createFilterKey(fe));
            fe = iter.hasNext() ? iter.next() : null;
        }

        return query;
    }

    private CompiledQuery compileQuery()
    {
        if (m_hasKeyCoverage)
        {
            return compileSimpleQuery();
        }
        return compileOrderedQuery(CompileFilter.FILTER_LTEGTE);
    }

    private void createEqualsKey(KeyInfo keyInfo, CompileFilter filter)
    {
        //
        // Normally, a range query is of only one depth; that is, a
        // query that does:
        //
        //  part1 > value
        //
        // will position the start iterator using the first field
        // of a key. When multiple fields use ==, we can optimize
        // the position by specifying all the fields instead of
        // setting the first one, and filtering on the rest. As
        // an example:
        //  
        //  part1 == v1 && part2 == v2
        //
        // can be optimized by defining both part1 and part2 in
        // the key, and adjusting the depth so the runtime knows
        // to look at both of them when positioning the iterator.
        //
        // The code below iterates over both the FieldDescriptor
        // and FieldEntry, and it continues to build a temp list
        // of field entries until the field names don't match, or
        // an == is not seen.
        //
        // The runtime supports positioning of >= and <=, so we also
        // allow one of these. But once one is ecountered, the processing
        // of the fields terminates, any subsequent expressions are filtered.
        //
        Iterator<FieldDescriptor> fdIter =
                    m_descriptor.m_fields.iterator();
        Iterator<FieldEntry>    feIter = m_entries.iterator();
        ArrayList<FieldEntry>   entries = new ArrayList<FieldEntry>(); 

        int lastOp = keyInfo.m_rop;

        while (feIter.hasNext() && fdIter.hasNext())
        {
            FieldDescriptor fd = fdIter.next();
            FieldEntry  fe = feIter.next();

            if (filter == CompileFilter.FILTER_LTEGTE)
            {
                if (fd.m_name.equals(fe.m_name) &&
                    fe.m_op == KeyComparisonOperator.EQ)
                {
                    entries.add(fe);
                }
                else
                {
                    break;
                }
            }
            else
            {
                assert( filter == CompileFilter.FILTER_NONE );
                if (fd.m_name.equals(fe.m_name) &&
                    (fe.m_op == KeyComparisonOperator.EQ ||
                        fe.m_op == KeyComparisonOperator.GTE ||
                        fe.m_op == KeyComparisonOperator.LTE))
                {
                    entries.add(fe);
                    lastOp = mapComparisonOp(fe.m_op);

                    if (fe.m_op == KeyComparisonOperator.GTE ||
                        fe.m_op == KeyComparisonOperator.LTE)
                    {
                        break;
                    }
                }
                else
                {
                    break;
                }
            }
        }

        //
        // Save the last op, which the runtime uses to position the key.
        //
        keyInfo.m_rop = lastOp;

        //
        // Using the temp list, build the actual key
        //
        keyInfo.m_keyDepth = 0;
        for (FieldEntry fe : entries)
        {
            keyInfo.addKeyData(fe.m_value);
            keyInfo.m_keyDepth += 1;
        }
        assert( keyInfo.m_keyDepth > 0 );
    }

    private boolean isRange(
        KeyComparisonOperator rop1,
        KeyComparisonOperator rop2)
    {
        //
        // See if the operators form a "range" of values.
        //
        if (rop1 == KeyComparisonOperator.GTE ||
            rop1 == KeyComparisonOperator.GT)
        {
            if (rop2 == KeyComparisonOperator.LTE ||
                rop2 == KeyComparisonOperator.LT)
            {
                return true;
            }
        }
        if (rop2 == KeyComparisonOperator.GTE ||
            rop2 == KeyComparisonOperator.GT)
        {
            if (rop1 == KeyComparisonOperator.LTE ||
                rop1 == KeyComparisonOperator.LT)
            {
                return true;
            }
        }
        return false;
    }

    private KeyInfo createFilterKey(FieldEntry fe)
    {
        //
        // Key filters require a complete key with empty field
        // values up to the filtered key field. The runtime uses
        // keyDepth to determine which field slot to look at.
        //
        int keyDepth = 0;
        int pos = 0;
        for (FieldDescriptor fd : m_descriptor.m_fields)
        {
            if (fd.m_name.equals(fe.m_name))
            {
                break;
            }
            pos += getKeyOffset(fd.getTypeCode());
            keyDepth++;
        }
        //
        // The filter operator is the opposite of the field
        // operator (i.e. to find all the EQ keys, we filter on
        // all those that are NEQ). 
        //
        KeyComparisonOperator filterOp = getFilterOp(fe.m_op);
        KeyInfo keyInfo = new KeyInfo(mapComparisonOp(filterOp));

        //
        // Allocate all the data and position it to the field we
        // need to set. We add a null byte in a loop instead of
        // the position() call to insure that the contents of the
        // preceding key data is zero.
        //
        while (pos > 0)
        {
            keyInfo.addKeyData((byte)0);
            pos--;
        }
        keyInfo.addKeyData(fe.m_value);
        keyInfo.m_keyDepth = keyDepth;

        return keyInfo;
    }

    private KeyComparisonOperator getFilterOp(KeyComparisonOperator op)
    {
        KeyComparisonOperator filterOp;

        if (op == KeyComparisonOperator.GTE)
        {
            filterOp = KeyComparisonOperator.LT;
        }
        else if (op == KeyComparisonOperator.GT)
        {
            filterOp = KeyComparisonOperator.LTE;
        }
        else if (op == KeyComparisonOperator.LTE)
        {
            filterOp = KeyComparisonOperator.GT;
        }
        else if (op == KeyComparisonOperator.LT)
        {
            filterOp = KeyComparisonOperator.GTE;
        }
        else if (op == KeyComparisonOperator.NEQ)
        {
            filterOp = KeyComparisonOperator.EQ;
        }
        else
        {
            assert( op == KeyComparisonOperator.EQ );
            filterOp = KeyComparisonOperator.NEQ;
        }
        return filterOp;
    }

    private int mapOrderBy(KeyOrderedBy orderBy)
    {
        return (orderBy == KeyOrderedBy.ASCENDING)
            ? SWRBTreeAscending : SWRBTreeDescending;
    }

    private int mapObjectLock(LockMode objectLock)
    {
        switch (objectLock)
        {
            case NOLOCK:
                return KeyOptNoLock;
            case READLOCK:
                return KeyOptReadLock;
        }
        assert( objectLock == LockMode.WRITELOCK );

        return KeyOptWriteLock;
    }

    private int mapComparisonOp(KeyComparisonOperator op)
    {
        switch (op)
        {
            case NEQ:
                return ObjSrv_NEQ;
            case GTE:
                return ObjSrv_GTE;
            case GT:
                return ObjSrv_GT;
            case LTE:
                return ObjSrv_LTE;
            case LT:
                return ObjSrv_LT;
        }
        assert( op == KeyComparisonOperator.EQ );

        return ObjSrv_EQ;
    }

    private T attachObject(LockMode objectLock, int placeHolder)
    {
        return _attachObject(
                m_descriptor.m_objDomainId,
                m_descriptor.m_objTypeId,
                m_descriptor.m_keyDomainId,
                m_descriptor.m_keyTypeId,
                m_query.m_keyInfo1.array(),
                placeHolder,
                mapObjectLock(objectLock));
    }

    private T attachMinimum(CompiledQuery query, LockMode objectLock)
    {
        return _attachMinimum(
                m_descriptor.m_objDomainId,
                m_descriptor.m_objTypeId,
                m_descriptor.m_keyDomainId,
                m_descriptor.m_keyTypeId,
                query.m_keyInfo1.m_keyDepth,
                query.m_keyInfo1.m_rop,
                query.m_keyInfo1.array(),
                mapObjectLock(objectLock));
    }

    private T attachMaximum(CompiledQuery query, LockMode objectLock)
    {
        return _attachMaximum(
                m_descriptor.m_objDomainId,
                m_descriptor.m_objTypeId,
                m_descriptor.m_keyDomainId,
                m_descriptor.m_keyTypeId,
                query.m_keyInfo1.m_keyDepth,
                query.m_keyInfo1.m_rop,
                query.m_keyInfo1.array(),
                mapObjectLock(objectLock));
    }

    private T createObject(ArrayList<CreateBuffer> createValues)
    {
        Object [] cvArray = (createValues == null)
                ? null : createValues.toArray();
        return _createObject(
                m_descriptor.m_objDomainId,
                m_descriptor.m_objTypeId,
                m_descriptor.m_keyDomainId,
                m_descriptor.m_keyTypeId,
                m_query.m_keyInfo1.array(),
                cvArray);
    }

    private native boolean _getKeyDescriptor(KeyDescriptor descriptor);
    private native T _attachObject(
                int objDomainId,
                int objTypeId,
                int keyDomainId,
                int keyTypeId,
                byte [] keyData,
                int placeHolder,
                int objLock);
    private native T _attachMinimum(
                int objDomainId,
                int objTypeId,
                int keyDomainId,
                int keyTypeId,
                int keyDepth,
                int rop,
                byte [] keyData,
                int objLock);
    private native T _attachMaximum(
                int objDomainId,
                int objTypeId,
                int keyDomainId,
                int keyTypeId,
                int keyDepth,
                int rop,
                byte [] keyData,
                int objLock);
    private native T _createObject(
                int objDomainId,
                int objTypeId,
                int keyDomainId,
                int keyTypeId,
                byte [] keyData,
                Object [] createValues);
}