package com.kabira.platform.management;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Indicate that this class implements a Management Target.  This
 * annotation must be applied to any class registered with Target.register().
 */
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ManagementTarget
{
     /**
     * The public name of the target.  Required.
     */
    String name();

    /**
     * The description of the target. Used to generate command help message.
     */
    String description() default "";
}

//
//  Using the @ManagementTarget annotation
//
@ManagementTarget(name = "mytarget", description = "a management target")
public class MyTarget extends Target
{
}

package com.kabira.platform.management;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Indicate that this method should be exposed as an command.
 * Commands must return void, or TargetException will be thrown
 * when the target is registered.
 */
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Command
{    
    /**
     * The description of the command. Used to generate command help message.
     */
    String description() default "";
}

//
//  Using the @Command annotation
//
public class MyTarget extends Target
{
    @Command(description = "a management command")
    public void setstate() { ... }
}

package com.kabira.platform.management;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Defines default values for parameters.
 * see java.lang.String for descriptions of valid String formats for
 * the supported parameter types.
 */
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Default
{    
    /**
     * Must be set true if the default value is provided.
     */
    boolean provided() default true;

    /**
     * The default value to be used.
     */
    String value();
}

//
//  Using the @Default annotation
//
public class MyTarget extends Target
{
    public void setstate(
        @Parameter(name = "state", defaultValue = @Default(value = "true")) String state) { ... }
}

package com.kabira.platform.management;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * ManagementTarget Command parameter.
 * Must be present on all parameters of a method annotated as a @Command. Valid
 * parameter types are String, Enum, Boolean, Character, Integer, Byte, Short,
 * Long, Float, and Double.  Other types will cause TargetException to be
 * thrown when the target is registered.  Arrays are not supported.
 * see java.lang.String for descriptions of valid String formats for
 * the supported parameter types.
 */
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
public @interface Parameter
{
    /**
     * The parameter name as exposed to management clients
     */
    String name();

    /**
     * A description of the parameter. Used in the generated help for the
     * command.
     */
    String description() default "";

    /**
     * Indicates that this parameter must be set by the caller.
     * If the parameter is not set. the command will fail.
     * If false, and no default is provided, the value of the parameter will be
     * null
     */
    boolean required() default false;

    /**
     * The default value of the parameter.
     */
    Default defaultValue() default @Default(provided = false, value = "");
}

//
//  Using the @Parameter annotation
//
public class MyTarget extends Target
{
    public void setstate(
        @Parameter(name = "state", 
            description="state value",
            required=true, 
            defaultValue = @Default(value = "true")) String state) { ... }
}

All parameters of a method marked with the @Command annotation must be marked with the @Parameter annotation. The supported parameter types are:

//     $Revision: 1.1.2.1 $

package com.kabira.snippets.management;

/**
 * A simple enum for the example target
 */
public enum AnEnum
{
    /**
     * for the money
     */
    One,
    /**
     * for the show
     */
    Two,
    /**
     * to get ready
     */
    Three,
    /**
     * to go!
     */
    Four
};

//     $Revision: 1.1.2.2 $
package com.kabira.snippets.management;

import com.kabira.platform.annotation.Asynchronous;
import com.kabira.platform.management.Command;
import com.kabira.platform.management.Default;
import com.kabira.platform.management.ManagementTarget;
import com.kabira.platform.management.Parameter;
import com.kabira.platform.management.Target;
import com.kabira.platform.management.TargetError;

/**
 * An example of an management target
 */
@ManagementTarget(
    name = "exampletarget",
    description = "example management target")
public class ExampleTarget extends Target
{
    /**
     * example display command. return a simple table of data.
     *
     * @throws TargetError
     */
    @Command
    public void display() throws TargetError
    {

        String[] names =
        {
            "Who", "Where", "What"
        };
        setColumnNames(names);

        String[] row =
        {
            "Colonel Mustard", "Library", "Candlestick"
        };
        addRow(row);

        commandComplete();
    }

    /**
     * example of command which fails. Transactions are committed when
     * commandFailed is called.
     */
    @Command
    public void setstate()
    {
        commandFailed("setstate not supported");
    }

    /**
     *
     * example of command which throws an exception. If an exception is thrown,
     * the command fails, and the transaction is aborted.
     *
     * @throws Exception
     */
    @Command
    public void rollbackexample() throws Exception
    {
        throw new Exception("transaction will roll back");
    }

    /**
     * Example of Parameter annotations
     *
     * @param version required String parameter
     * @param count optional Integer parameter with default value
     * @param enum123 optional Enum parameter with default value
     * @param aBool optional Boolean parameter with default value
     * @param aFloat optional Float parameter with default value
     */
    @Command
    public void examplecommand(
        @Parameter(name = "version", description = "version number",
            required = true) 
        String version,
        @Parameter(name = "count", description = "number to display",
            defaultValue = @Default(value = "1")) 
        Integer count,
        @Parameter(name = "enum123", description = "Pick One Two or Three",
            defaultValue = @Default(value = "One"))
        AnEnum enum123,
        @Parameter(name = "abool", defaultValue = @Default(value = "true")) 
        Boolean aBool,
        @Parameter(name = "afloat", defaultValue = @Default(value = "123.456"))
        Float aFloat)
    {

        commandComplete();
    }

    /**
     * Asynchronous command example. asyncCommand() starts the command.
     *
     * @throws TargetError
     */
    @Command
    public void asynccommand() throws TargetError
    {
        m_asyncStartTime = System.currentTimeMillis();
        asyncCommandComplete();
    }

    /**
     * Complete the asynchronous command.
     */
    @Asynchronous
    private void asyncCommandComplete() throws TargetError
    {
        long elapsedTime = System.currentTimeMillis() - m_asyncStartTime;
        String[] names =
        {
            "Elapsed Time (Milli-seconds)"
        };
        setColumnNames(names);
        String[] row =
        {
            Long.toString(elapsedTime)
        };
        addRow(row);
        commandComplete();
    }
    private long m_asyncStartTime;
}

//     $Revision: 1.1.2.2 $
package com.kabira.snippets.management;

import com.kabira.test.management.Client;
import com.kabira.test.management.CommandFailed;
import java.util.HashMap;

/**
 * Execute example target 
 * <p> 
 * <h2> Target Nodes</h2> 
 * <ul> <li> <b>domainnode</b>= A </ul>
 */
public class ExampleMain
{
    /**
     * @param args None supported
     * @throws CommandFailed Command execution failed
     */
    public static void main(String[] args) throws CommandFailed
    {
        //
        //  Initialize target
        //
        ExampleTargetLifecycle.register();

        //
        //  Create test client
        //
        Client client = new Client("guest", "guest");

        //
        //  Execute help on the target
        //
        String[] results = client.runCommand("help", ExampleTargetLifecycle.Name, null);

        //
        //  Display results
        //
        for (String s : results)
        {
            System.out.println(s);
        }

        //
        //  Execute display
        //
        results = client.runCommand("display", ExampleTargetLifecycle.Name, null);

        //
        //  Display results
        //
        for (String s : results)
        {
            System.out.println(s);
        }

        //
        //  Execute the asynchronous command
        //
        results = client.runCommand("asynccommand", ExampleTargetLifecycle.Name, null);

        //
        //  Display results
        //
        for (String s : results)
        {
            System.out.println(s);
        }

        //
        //  Execute examplecommand
        //
        HashMap<String, String> parameters = new HashMap<String, String>();
        parameters.put("version", "1.0");
        parameters.put("count", "100");
        parameters.put("enum123", "Three");
        parameters.put("abool", "true");
        parameters.put("afloat", "3.75");
        client.runCommand("examplecommand", ExampleTargetLifecycle.Name, parameters);

        //
        //  Terminate target
        //
        ExampleTargetLifecycle.unregister();
    }
}

//     $Revision: 1.1.2.1 $

package com.kabira.snippets.management;

import com.kabira.platform.management.Target;
import com.kabira.platform.Transaction;

/**
 * Example target life-cycle implementation
 */
public class ExampleTargetLifecycle
{
    /**
     * Target name
     */
    public final static String Name = "exampletarget";

    /**
     * Register MyTarget management target
     */
    public static void register()
    {
        new Transaction("Register Target")
        {

            @Override
            protected void run() throws Rollback
            {
                Target.register(ExampleTarget.class);
            }
        }.execute();

    }

    /**
     * Un-register MyTarget management target
     */
    public static void unregister()
    {
        new Transaction("Un-register Target")
        {

            @Override
            protected void run() throws Rollback
            {
                Target.unregister(Name);
            }
        }.execute();
    }
}

//    $Revision: 1.1.2.1 $

configuration "exampletargetsecurity" version "1" type "security"
{
	configure security
	{
		configure AccessControl
		{
			//
			// this rule locks all elements in
			// ExampleTargetCommand to prevent unauthenticated
			// access, and then grants full access to all
			// elements in the command to the "switchadmin" role.
			//
			Rule
			{
				name = "com.kabira.platform.management.ExampleTarget";
				lockAllElements = true;
				accessRules = 
				{
					{
						roleName = "switchadmin";
						permission = AccessAllOperationsAndAttributes;
					}
				};
			};

			//
			// the remaining rules grant access to specific
			// operations to the "switchmonitor" role:
			//
			Rule
			{
				name = "com.kabira.platform.management.ExampleTarget.examplecommand";
				accessRules = 
				{
					{
						roleName = "switchmonitor";
						permission = Execute;
					}
				};
			};
		};
	};
};

#
#     Output from help command
#
[A]   valid commands and parameters for target "exampletarget":
[A] 
[A]   display exampletarget
[A] 
[A]   asynccommand exampletarget
[A] 
[A]   examplecommand exampletarget
[A]     version=<String>
[A]         version number
[A] 
[A]     [ count=<Integer, default = 1> ]
[A]         number to display
[A] 
[A]     [ enum123=<AnEnum, default = One> ]
[A]         Pick One Two or Three
[A] 
[A]     [ abool=<Boolean, default = true> ]
[A] 
[A]     [ afloat=<Float, default = 123.456> ]
[A] 
[A] 
[A]   setstate exampletarget
[A] 
[A]   rollbackexample exampletarget
[A] 
[A] 
[A] Description:
[A] 
[A] example management target

#
#     Output from display command
#
[A] Who    Where    What
[A] Colonel Mustard    Library    Candlestick

#
#     Output from asynccommand command
#
[A] Elapsed Time (Milli-seconds)
[A] 3