//
// Name
//  $RCSfile: QueryScope.java,v $
// 
// Copyright
//  Copyright 2012 Cloud Software Group, Inc. ALL RIGHTS RESERVED. 
//  Cloud Software Group, Inc. Confidential Information
//
// History
//  $Revision: 1.1.2.2 $ $Date: 2012/08/03 19:59:24 $
//
package com.kabira.platform;

import java.util.HashSet;
import java.util.Collections;

/**
 * Class used to define a set of remote nodes used for distributed queries. 
 * <p>
 * This class allows applications to define queries that are done on
 * a subset of nodes in the cluster. 
 * <p>
 * When a query is executed using a user defined query scope, the current
 * audit mode is used to verify the scope. If the default {@link
 * com.kabira.platform.QueryScope.AuditMode#AUDIT_NODE_LIST} audit mode
 * is enabled, distributed queries are skipped if distribution is not
 * active when the query is executed. If distribution is active, only
 * those nodes that are active in the node list are used in the query,
 * all other nodes are ignored. Otherwise, the auditing documented in the
 * {@link com.kabira.platform.QueryScope.AuditMode} enumeration is
 * performed, and a ResourceUnavailableException exception is thrown
 * if the audit fails.
 * <p>
 * When {@link QueryScope#setAuditMode(AuditMode)} is called, no audits
 * are done at that time. Only when a query is executed is auditing done.
 * This insures that auditing is performed before each execution of the query.
 * <p>
 * To support cluster wide queries, the {@link QueryScope#QUERY_CLUSTER}
 * predefined instance of QueryScope can be used.
 * <p>
 * To disable node or cluster scoped queries, the {@link QueryScope#QUERY_LOCAL}
 * predefined instance of QueryScope can be used.
 *
 * @see KeyQuery#setQueryScope(QueryScope)
 * @see ManagedObject#extent(Class, QueryScope, LockMode)
 * @see ManagedObject#cardinality(Class, QueryScope)
 */
public final class QueryScope
{
    /**
     * The query will be done only on the local node. This is the default scope.
     */
    public final static QueryScope QUERY_LOCAL = new QueryScope(Scope.LOCAL);

    /**
     * The query will be done on all active nodes in the cluster.
     */
    public final static QueryScope QUERY_CLUSTER = new QueryScope(Scope.CLUSTER);

    /**
     *  Possible audits that can be applied to the query.
     */
    public enum AuditMode
    {
        /**
         * Default audit mode, distributed audits are disable. The node
         * list is validated to insure one or more nodes are defined and
         * that no node in the list is empty.
         */
        AUDIT_NODE_LIST,
        /**
         * Validate that the node list is valid and that distribution
         * is active. Inactive nodes are skipped when the query is executed.
         */
        AUDIT_DISTRIBUTION,
        /**
         * Validate that the node list is valid, distribution is active,
         * and that all nodes are active.
         */
        AUDIT_NODES_ACTIVE
    }

        /**
         * Create a QueryScope instance with no nodes.
         */
    public QueryScope()
        {
                m_remoteNodes = new HashSet<String>();
        m_scope = Scope.USER;
        m_auditMode = AuditMode.AUDIT_NODE_LIST;
        }

        /**
         * Create a QueryScope instance
     *
     * @param remoteNodes Array of remote nodes.
         */
        public QueryScope(String [] remoteNodes)
        {
                m_remoteNodes = new HashSet<String>();
        Collections.addAll(m_remoteNodes, remoteNodes);
        m_scope = Scope.USER;
        m_auditMode = AuditMode.AUDIT_NODE_LIST;
        }

        /**
     * Adds the specified node if not already present.
     * @param nodeName Node to add.
     * @exception UnsupportedOperationException
     *  The operation was called on QUERY_LOCAL or QUERY_CLUSTER.
         */
    public void addNode(String nodeName)
        throws UnsupportedOperationException
    {
        checkUser();
        m_remoteNodes.add(nodeName);
    }

        /**
     * Removed the specified node. If not present, the remove is ignored.
     * @param nodeName Node to remove.
     * @exception UnsupportedOperationException
     *  The operation was called on QUERY_LOCAL or QUERY_CLUSTER.
         */
    public void removeNode(String nodeName)
        throws UnsupportedOperationException
    {
        checkUser();
        m_remoteNodes.remove(nodeName);
    }

        /**
     * Get the nodes defined for this query scope.
     * <p>
     * If this method is called on QUERY_LOCAL or QUERY_CLUSTER
     * instances, a zero length array is returned.
     * @return Array of node names.
         */
    public String [] getNodes()
    {
        return m_remoteNodes.toArray(new String[0]);
    }

        /**
     * Set audit mode when queries are executed.
     * @param auditMode Audit mode to use.
     * @exception UnsupportedOperationException
     *  The operation was called on QUERY_LOCAL or QUERY_CLUSTER.
         */
    public void setAuditMode(AuditMode auditMode)
        throws UnsupportedOperationException
    {
        checkUser();
        m_auditMode = auditMode;
    }

        /**
     * Return the current audit mode.
     * @return Current audit mode.
     * @exception UnsupportedOperationException
     *  The operation was called on QUERY_LOCAL or QUERY_CLUSTER.
         */
    public AuditMode getAuditMode()
        throws UnsupportedOperationException
    {
        checkUser();
        return m_auditMode;
    }

    //
    // Package private definitions.
    //
    enum Scope
    {
        LOCAL,
        CLUSTER,
        USER
    }

    Scope getScope()
    {
        return m_scope;
    }

    void checkUser() throws UnsupportedOperationException
    {
        if (m_scope != Scope.USER)
        {
            throw new UnsupportedOperationException();
        }
    }

    void audit()
    {
        if (m_scope != Scope.USER)
        {
            assert( m_remoteNodes.isEmpty() );
            return;
        }

        if (m_remoteNodes.isEmpty())
        {
            throw new IllegalArgumentException(
                "The node array must have at least one entry");   
        }
        for (String node : m_remoteNodes)
        {  
            if (node.isEmpty())
            {
                throw new IllegalArgumentException("Empty node in list");
            }
        }

        if (m_auditMode == AuditMode.AUDIT_DISTRIBUTION ||
            m_auditMode == AuditMode.AUDIT_NODES_ACTIVE)
        {
            if (ManagedObject.m_distributedQuery == null)
            {
                throw new ResourceUnavailableException(
                    "Distributed query processing not available on this node");
            }
            if (m_auditMode == AuditMode.AUDIT_NODES_ACTIVE)
            {
                ManagedObject.m_distributedQuery.validateNodesActive(this);
            }
        }
    }

    //
    // Private constructor used for predefined scopes.
    //
    private QueryScope(Scope scope)
    {
                m_remoteNodes = new HashSet<String>();
        m_scope = scope;
        m_auditMode = AuditMode.AUDIT_NODE_LIST;
    }

    private HashSet<String>     m_remoteNodes;
    private AuditMode           m_auditMode;
    private Scope               m_scope;
}