/*
 * $RCSfile: Target.java,v $
 * $Revision: 1.1.2.17.2.2 $ $Date: 2012/08/28 23:48:09 $
 *
 * COPYRIGHT
 *      Copyright 2009-2012 Cloud Software Group, Inc. ALL RIGHTS RESERVED.
 *      Cloud Software Group, Inc. Confidential Information
 */
package com.kabira.platform.management;

import com.kabira.platform.KeyFieldValueList;
import com.kabira.platform.KeyManager;
import com.kabira.platform.KeyQuery;
import com.kabira.platform.LockMode;
import com.kabira.platform.ManagedObject;
import com.kabira.platform.ObjectNotUniqueError;
import com.kabira.platform.OutParameter;
import com.kabira.platform.switchadmin.AdminReport;
import com.kabira.platform.switchadmin.CommandStatus;
import com.kabira.platform.switchadmin.JavaCommand;
import com.kabira.ktvm.transaction.DeadlockError;
import java.io.PrintWriter;
import java.io.StringWriter;
import java.lang.annotation.Annotation;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.util.HashMap;
import java.util.logging.Logger;

/**
 * System management targets allow developers to extend the system
 * management framework.  System management targets are accessible from
 * via JMX, from the command line using the "administrator" command, and from
 * the adminstrative web interface.
 * System management targets are defined by extending Target.
 * Note that Target is a managed object, and is always called by the system 
 * management framework with an active transaction.
 * <h2>
 * Management target implementation
 * </h2>
 * Targets may return result sets, which consist of a list of column names and
 * any number of rows.  All rows must contain the same number of m_columns.
 * setColumnNames() must be called before addRow().  setColumnNames may be
 * called only once, or a TargetError
 * will be thrown.  After setColumnNames() is called, addRow() may be called
 * any number of times.  The number of m_columns in each row must match the
 * number of column names, or TargetError will be thrown.
 * Targets are registered by calling Target.register().  A new instance of the
 * Target is created for every command invocation.  Targets implementing
 * asynchronous commands may store command-context-specific data in private
 * members.
 *
 * Here's a simple example of an management target with a synchronous
 * command which returns a result set:
 * <p>
 * <pre>
 *  public class ExampleTarget extends Target {
 *
 *    public ExampleTarget() {
 *        super("exampletarget");
 *    }
 *
 *    &#64;Command
 *    public void exampleCommand(
 *            &#64;Parameter(name = "count", description = "number to display",
 *                defaultValue = &#64;Default(value = "1"))
 *           int count) {
 *        String[] names = { "Who", "Where", "What" };
 *        setColumnNames(names);
 *
 *        String[] row = { "Colonel Mustard", "Library", "Candlestick" };
 *        addRow(row);
 *        commandComplete();
 *    }
 *  }
 * </pre>
 *
 * <h2>Execution JVM</h2>
 *
 * All commands associated with an administrative target
 * execute in the JVM in which the target was registered
 * using the register() method.
 *
 * <h2>Synchronous Commands</h2>
 *
 * Any command which calls commandComplete() or commandFailed() before returning
 * is a synchronous command.
 *
 * <h2>Asynchronous commands</h2>
 *
 * Commands may return without completing.  In this case, the
 * command will be held open until commandComplete() or commandFailed() is
 * called.
 * Note that asynchronous commands which are abandoned
 * (e.g. the client never collects the results) will cause a leak in the
 * underlying framework.
 *
 * <h2>Transactions</h2>
 *
 * Command methods are always called with a valid transaction.
 * The transaction is committed after the method returns, unless an exception is
 * thrown, in which case the transaction is rolled back.  Asynchronous commands
 * must start a transaction to call back into the Target to complete the
 * command.
 *
 * <h2>Security Configuration</h2>
 *
 * Management targets use configuration to define access
 * control on the methods exposed as commands on the target.
 *
 * Here's an example of a security configuration file for ExampleTarget:
 * <pre>
 * configuration "ExampleTargetSecurity" version "1" type "security"
 * {
 *    configure security
 *    {
 *        configure AccessControl
 *        {
 *            Rule
 *            {
 *                name = "com.kabira.platform.management.ExampleTarget";
 *                lockAllElements = true;
 *                accessRules = { };
 *            }
 *            Rule
 *            {
 *                name = "com.kabira.platform.management.ExampleTarget.examplecommand";
 *
 *                accessRules =
 *                {
 *                    {
 *                        roleName = "switchmonitor";
 *                        permission = Execute;
 *                    }
 *                };
 *            };
 *        };
 *    };
 * };
 * </pre>
 */

public class Target extends JavaCommand
{
    AdminReport adminReport = null;
    private CommandStatus m_commandStatus = CommandStatus.CommandInProgress;
    private long m_columns = 0;

    /**
     * Register a Target.
     * <p>
     * All commands associated with the target being registered will
     * execute in the JVM in which register was called.
     * @param targetClass the class of the target, e.g. MyTarget.class
     * @throws TargetError The target failed registration audit.
     *
     */
    public static void register(Class targetClass)
            throws TargetError
    {
        String targetName = getTargetName(targetClass);
        
        Target.audit(targetClass, targetName);

        //
        // Always unregister the target name before registering it, since
        // a Factory created in a previous instance of the engine will not
        // be accessible.
        //
        unregister(targetName);

        try
        {
            Factory factory = new Factory(targetClass, targetName);
        }
        catch (ObjectNotUniqueError ex)
        {
            // two callers got here at once. swallow this
            // error. the other caller won.
        }
    }

    /**
     * Unregister a previously-registered target.
     * @param targetName the name of the target
     */
    public static void unregister(String targetName)
    {
        KeyManager<Factory> keyManager = new KeyManager<Factory>();
        KeyQuery<Factory> keyQuery = keyManager.createKeyQuery(
                Factory.class, "ByName");
        KeyFieldValueList keyFieldValueList = new KeyFieldValueList();

        //
        // Define the query to find the Factory
        //
        keyFieldValueList.add("name", targetName);
        keyQuery.defineQuery(keyFieldValueList);

        Factory factory = keyQuery.getSingleResult(LockMode.WRITELOCK);

        if (factory != null)
        {
            ManagedObject.delete(factory);
        }
    }

    /**
     * Indicate that the command has completed successfully.
     */
    protected final void commandComplete()
    {
        String results = "";

        m_commandStatus = CommandStatus.CommandCompleted;

        if (adminReport != null)
        {
                OutParameter<String> out = new OutParameter<String>();
                adminReport.getReport(out);
                results = out.getValue();

                ManagedObject.delete(adminReport);
                adminReport = null;

        }
        update(m_commandStatus, results, "");
    }

    /**
     * Indicate that the command has failed.
     * The Transaction will be
     * committed.  To roll back the transaction, throw an exception from the
     * method implementing the command.
     * @param reason The reason the command failed.
     */
    protected final void commandFailed(String reason)
    {
        m_commandStatus = CommandStatus.CommandFailed;
        update(m_commandStatus, "", reason);
    }

    /**
     * Set the names of the m_columns for the result set.
     * @param names The names of the m_columns for the result set
     * @throws TargetError The method was called more than once
     */
    protected final void setColumnNames(String[] names)
            throws TargetError
    {
        if (adminReport != null)
        {
            throw new TargetError("setColumnNames called twice");
        }
        if (names.length == 0)
        {
            throw new TargetError("zero column names provided");
        }

        adminReport = new AdminReport();

        adminReport.setHeader(names);

        m_columns = names.length;
    }

    /**
     * Add a row to the result set
     * @param values The list of values for this row
     * @throws TargetError The number of values does not match
     * the number of column names, or setColumnNames() has not been called yet.
     */
    protected final void addRow(String[] values)
            throws TargetError
    {
        if (adminReport == null)
        {
            throw new TargetError(
                    "addRow called without calling setColumnNames");
        }

        if (values.length != m_columns)
        {

            throw new TargetError(
                    "addRow: number of values (" + values.length +
                    ") does not match number of columns (" + m_columns +
                    ")");
        }

        adminReport.addRecord(values);
    }

    /**
     * Execute a command.  This is an internal method which should never
     * be called.
     * @param parameters the command parameters
     */
    //
    // unchecked conversion warnings are suppressed for Enum.valueOf(),
    // which cannot be fixed because generics are not covariant.
    //
    @SuppressWarnings("unchecked")
    @Override
    protected final void execute(final String[] parameters)
    {
        if (commandName.equals("help"))
        {
            help();
            return;
        }

        //
        // Check to see if the current user has permission to execute
        // this command
        //
        Boolean ok = false;
        ok = checkAccess(this.getClass().getName() + "." + commandName);
                if (!ok)
                {
                        String msg = "An access violation occurred while " +
                                "attempting to execute command [" + commandName +
                                "] on target [" + targetName + 
                                "]. The calling principal " +
                                "does not have execute privileges for this command.";
                        throw new SecurityException(msg);
                }

        Method method = null;

        for (Method m : this.getClass().getDeclaredMethods())
        {
            if ((m.getAnnotation(Command.class) != null) &&
                    (m.getName().equals(commandName)))
            {
                method = m;
                break;
            }
        }

        if (method == null)
        {
            commandFailed("command '" + commandName +
                    "' not found in target '" + targetName + "'");
            return;
        }

        Annotation[][] all = method.getParameterAnnotations();
        Class pt[] = method.getParameterTypes();
        Object[] args = new Object[pt.length];

        HashMap<String, String> paramap = new HashMap<String, String>();

        for (int pi = 0; pi < parameters.length;)
        {
            paramap.put(parameters[pi++], parameters[pi++]);
        }

        //
        // for each of the method's parameters, find the supplied parameter
        // or use the default (if it isn't required)
        //
        for (int i = 0; i < pt.length; i++)
        {
            Parameter pp = null;
            Default defaultValue = null;

            //
            // find the Parameter annotation for this parameter
            //
            for (Annotation a : all[i])
            {
                if (a.annotationType() == Parameter.class)
                {
                    pp = (Parameter) a;
                }
            }

            String name = pp.name();
            String value = paramap.get(name);

            if (value != null)
            {
                paramap.remove(name);
            }
            else
            {
                if (pp.defaultValue().provided())
                {
                    value = pp.defaultValue().value();
                }
                else if (pp.required() == true)
                {
                    commandFailed("required parameter " +
                            pp.name() + " missing");
                    return;
                }
            }

            Class type = pt[i];

            try
            {
                if (value == null)
                {
                    args[i] = null;
                }
                else if (type == String.class)
                {
                    args[i] = value;
                }
                else if (type.isEnum())
                {
                    //
                    // unchecked warnings if not suppressed
                    //
                    args[i] = Enum.valueOf(type, value);
                }
                else if (type == Boolean.class)
                {
                    args[i] = Boolean.valueOf(value);
                }
                else if (type == Character.class)
                {
                    args[i] = Character.valueOf(value.charAt(0));
                }
                else if (type == Integer.class)
                {
                    args[i] = Integer.parseInt(value);
                }
                else if (type == Byte.class)
                {
                    args[i] = Byte.parseByte(value);
                }
                else if (type == Short.class)
                {
                    args[i] = Short.parseShort(value);
                }
                else if (type == Long.class)
                {
                    args[i] = Long.parseLong(value);
                }
                else if (type == Float.class)
                {
                    args[i] = Float.parseFloat(value);
                }
                else
                {
                    assert (type == Double.class);
                    args[i] = Double.parseDouble(value);
                }
            }
            catch (NumberFormatException ex)
            {
                commandFailed("Invalid numeric format '" + value +
                    "' for parameter '" + name + ": " +
                    ex.getMessage());
                return;
            }
            catch (IllegalArgumentException ex)
            {
                commandFailed("Illegal argument '" + value +
                    "' for parameter '" + name + ": " +
                    ex.getMessage());
                return;
            }
        }

        if (!paramap.isEmpty())
        {
            commandFailed("invalid parameter(s): " + paramap.toString());
            return;
        }

        try
        {
            method.setAccessible(true);
            method.invoke(this, args);
        }
        catch (InvocationTargetException ex)
        {
            String reason = "InvocationTargetException: ";

            Throwable cause = ex.getCause();

            if (cause != null)
            {
                if (cause instanceof DeadlockError)
                {
                    throw (java.lang.Error)cause;
                }

                reason = cause.getMessage();
                
                StringWriter stringWriter = new StringWriter();
                PrintWriter printWriter = new PrintWriter(stringWriter);
                cause.printStackTrace(printWriter);

                reason += stringWriter.toString();
            }
            else
            {
                reason += ex.getMessage();
            }
        
            setAbortFlag();
            commandFailed(reason);
        }
        catch (Exception ex)
        {
            ex.printStackTrace();
            setAbortFlag();
            commandFailed(ex.getMessage());
        }
    }

    /**
     * Retrieve the name of the currently active Principal. This operation
     * may be called during command execution to get the name of the Principal
     * that invoked the command.
     */
    protected final String getActivePrincipalName()
    {
                String result = getCurrentPrincipalName();

                if ((result == null) || (result.length() == 0))
                {
                        return null;
                }

                return result;
        }
                
    private static String getTargetName(Class<?> targetClass)
    {
        ManagementTarget adminTarget = 
            targetClass.getAnnotation(ManagementTarget.class);

        if (adminTarget == null)
        {
            throw new TargetError("Missing ManagementTarget annotation on type "
                + targetClass.getName() + ". ");
        }
        return adminTarget.name();
    }

    private static void audit(Class targetClass, String targetName)
            throws TargetError
    {
        String error = new String();
   
        for (Method m : targetClass.getMethods())
        {
            if (m.getAnnotation(Command.class) == null)
            {
                continue;
            }

            Annotation[][] all = m.getParameterAnnotations();
            Class pt[] = m.getParameterTypes();

            for (int i = 0; i < pt.length; i++)
            {
                Parameter pp = null;
                Default defaultValue = null;

                Class type = pt[i];

                if ((type != String.class) &&
                        (!type.isEnum()) &&
                        (type != Boolean.class) &&
                        (type != Character.class) &&
                        (type != Integer.class) &&
                        (type != Byte.class) &&
                        (type != Short.class) &&
                        (type != Long.class) &&
                        (type != Float.class) &&
                        (type != Double.class))
                {
                    error += "Unsupported parameter type " +
                            type.getName() + " in method " + m.getName() + ". ";
                }

                //
                // find the Parameter annotation for this parameter
                //
                for (Annotation a : all[i])
                {
                    if (a.annotationType() == Parameter.class)
                    {
                        pp = (Parameter) a;
                    }
                }
                if (pp == null)
                {
                    error += "Missing @Parameter annotation on parameter " +
                            "of type " + type.getName() + " in method " +
                            m.getName() + ". ";
                }
            }
        }

        if (!error.isEmpty())
        {
            throw new TargetError("Admin target " + targetName +
                    " failed audit: " + error);
        }
    }

    private void help()
    {
        String help = new String();
        
        help += "  valid commands and parameters for target \"";
        help += targetName;
        help += "\":\n\n";

        for (Method m : this.getClass().getDeclaredMethods())
        {
            if (m.getName().charAt(0) == '$')
            {
                continue;
            }
            
            Command command = m.getAnnotation(Command.class);

            if (command == null)
            {
                continue;
            }

            help += "  " + m.getName() + " " + targetName + "\n";

            Annotation[][] all = m.getParameterAnnotations();
            Class pt[] = m.getParameterTypes();

            for (int i = 0; i < pt.length; i++)
            {
                Parameter pp = null;
                Class type = pt[i];

                //
                // find the Parameter annotation for this parameter
                //
                for (Annotation a : all[i])
                {
                    if (a.annotationType() == Parameter.class)
                    {
                        pp = (Parameter) a;
                    }
                }

                String ps = pp.name() + "=<" +
                        type.getName().replace('.', ' ').replaceAll(".* ", "");

                if (pp.defaultValue().provided())
                {
                    ps += ", default = " + pp.defaultValue().value();
                }
                ps += ">";

                if (!pp.required())
                {
                    ps = "[ " + ps + " ]";
                }

                help += "\t" + ps + "\n";
                if (!pp.description().equals(""))
                {
                    help += "\t\t" + pp.description() + "\n";
                }
                help += "\n";
            }

            if (!command.description().equals(""))
            {
                help += "\t" + command.description() + "\n";
            }
            help += "\n";
        }

        ManagementTarget adminTarget =
                    this.getClass().getAnnotation(ManagementTarget.class);

        if (adminTarget != null)
        {
            help += "\nDescription:\n\n" + adminTarget.description() + "\n";
        }

        update(CommandStatus.CommandCompleted, help, "");
    }
}