com.kabira.platform.management

Class Target

java.lang.Object

com.kabira.platform.switchadmin.Command

com.kabira.platform.switchadmin.JavaCommand

com.kabira.platform.management.Target

public class Target
extends com.kabira.platform.switchadmin.JavaCommand

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.

Management target implementation

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:

  public class ExampleTarget extends Target {

    public ExampleTarget() {
        super("exampletarget");
    }

    @Command
    public void exampleCommand(
            @Parameter(name = "count", description = "number to display",
                defaultValue = @Default(value = "1"))
           int count) {
        String[] names = { "Who", "Where", "What" };
        setColumnNames(names);

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

Execution JVM

All commands associated with an administrative target execute in the JVM in which the target was registered using the register() method.

Synchronous Commands

Any command which calls commandComplete() or commandFailed() before returning is a synchronous command.

Asynchronous commands

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.

Transactions

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.

Security Configuration

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:

 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;
                    }
                };
            };
        };
    };
 };
 

Field Summary

Fields inherited from class com.kabira.platform.switchadmin.Command

commandName, resourceData, resourcesNeeded, targetName

Constructor Summary

Constructors

Constructor and Description
Target()

Method Summary

Methods

Modifier and Type	Method and Description
protected void	addRow(java.lang.String[] values) Add a row to the result set
protected void	commandComplete() Indicate that the command has completed successfully.
protected void	commandFailed(java.lang.String reason) Indicate that the command has failed.
protected void	execute(java.lang.String[] parameters) Execute a command.
protected java.lang.String	getActivePrincipalName() Retrieve the name of the currently active Principal.
static void	register(java.lang.Class targetClass) Register a Target.
protected void	setColumnNames(java.lang.String[] names) Set the names of the m_columns for the result set.
static void	unregister(java.lang.String targetName) Unregister a previously-registered target.

Methods inherited from class com.kabira.platform.switchadmin.JavaCommand

checkAccess, getCurrentPrincipalName, setAbortFlag

Methods inherited from class com.kabira.platform.switchadmin.Command

update

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Target

public Target()

Method Detail

register

public static void register(java.lang.Class targetClass)
                     throws TargetError

Register a Target.

All commands associated with the target being registered will execute in the JVM in which register was called.

Parameters:

targetClass - the class of the target, e.g. MyTarget.class

Throws:

TargetError - The target failed registration audit.

unregister

public static void unregister(java.lang.String targetName)

Unregister a previously-registered target.

Parameters:

targetName - the name of the target

commandComplete

protected final void commandComplete()

Indicate that the command has completed successfully.

commandFailed

protected final void commandFailed(java.lang.String reason)

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.

Parameters:

reason - The reason the command failed.

setColumnNames

protected final void setColumnNames(java.lang.String[] names)
                             throws TargetError

Set the names of the m_columns for the result set.

Parameters:

names - The names of the m_columns for the result set

Throws:

TargetError - The method was called more than once

addRow

protected final void addRow(java.lang.String[] values)
                     throws TargetError

Add a row to the result set

Parameters:

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.

execute

protected final void execute(java.lang.String[] parameters)

Execute a command. This is an internal method which should never be called.

Specified by:

execute in class com.kabira.platform.switchadmin.JavaCommand

Parameters:

parameters - the command parameters

getActivePrincipalName

protected final java.lang.String getActivePrincipalName()

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.