NOTE: This section assumes you have a working knowledge of JavaScript and writing, compiling and deploying Java classes.

The Custom Command Handler class extends the functionality of RTView by allowing you to write code that will get called when the custom commands you defined are executed. For the Display Builder, Display Viewer and Display Viewer Applet, you must write your custom commands in Java. With the Display Server, you may write your custom commands in Java or JavaScript. Java commands are executed by the Display Server on the application server and JavaScript commands are executed by the web browser on the client. For more information on how commands are executed, see the Object Commands section. See the Define System Commands section for information on defining a command property to execute a custom command.

Java Custom Command Handler
To implement your own Java Custom Command Handler, create a Java class named MyCommandHandler.java that extends GmsRtViewCustomCommandHandler.

In MyCommandHandler.java, define the following method:

public GmsRtViewCommandStatus invokeCommand (GmsRtViewCommand cmd)

Every time a custom command is executed in RTView this method will get called.

Add the gmsjrtview.jar file, located in the lib directory (found in your installation directory,) to your classpath when you compile your Custom Command Handler. The compiled Custom Command Handler class must be included in the RTView classpath by adding it to the definition for the RTV_USERPATH environment variable.

The following example is a Custom Command Handler that will print the command argument to the console when the custom command my_command is executed.

import com.sl.gmsjrtview.*;

/** This method is called each time a custom command is executed in RTView.
 *
 * @param cmd the command to be executed
 * @return a GmsRtViewCommandStatus object, indicating the status of
 * the custom command execution.
 */

public GmsRtViewCommandStatus invokeCommand (GmsRtViewCommand cmd)
{

GmsRtViewCommandStatus sts = new GmsRtViewCommandStatus();

if (cmd.commandString.equals("my_command")){

sts.status = GmsRtViewCommandStatus.OK;
System.out.println(cmd.commandArg);

 } else {

sts.status = GmsRtViewCommandStatus.ERROR;
sts.message = "unrecognized custom command: " + cmd.commandString;

}
return sts;

}

The GmsRtViewCommand object is passed as the argument to each custom command and is defined as follows:

public class GmsRtViewCommand
{

/**
 * The name of the custom command to be executed.
 */

public String commandString;

/**
 * The argument for the custom command.
 */

public Object commandArg;

}

The GmsRtViewCommandStatus object is returned from the custom command and is defined as follows. The custom command code must assign a value to the status field and, optionally, to the message field.

public class GmsRtViewCommandStatus implements java.io.Serializable
{

/**
 * Value for status field, indicating successful command completion.
 */

public final static int OK;

/**
 * Value for status field, indicating error during command execution.
 */

public final static int ERROR;

/**
 * Status (OK or ERROR) of command execution.
 * Default value is OK.
 */

public int status = OK;

/**
 * Message to be displayed in dialog from Viewer.
 * This can be an error message or an information message.
 * If null, no dialog is opened. Default is null.
 */

public String message = null;

}

JavaScript Custom Command Handler
To implement your own JavaScript Custom Command Handler, modify rtv_custom.js file, which is located in servlets\rtvdisplay.

The rtv_custom.js file contains two JavaScript functions, rtvGetInvokeCommandOnClient (commandString) and rtvInvokeCommand (commandString, valueString).

1. rtvGetInvokeCommandOnClient (commandString)

This function must return true if the commandString should be executed on the client by the web browser, using the rtvGetInvokeCommandOnClient function. All commandStrings for which this function returns true must be implemented in rtvInvokeCommand. It must return false if the specified commandString should be executed by the Display Server on the application server. The default returns false.

2. rtvInvokeCommand (commandString, valueString)

This function must implement each commandString where rtvGetInvokeCommandOnClient (commandString) returns true, as described above. The rtvInvokeCommand function is invoked in a hidden IFrame that is a child of the Frame containing the Display Server display, which can be referenced in JavaScript as "window.parent". The default implementation of rtvInvokeCommand does nothing.

To deploy JavaScript custom commands you must pack your rtv_custom.js into rtvdisplay.war and redeploy the servlet on your application server. Custom commands that are to be executed by the Display Server must be implemented in MyCommandHandler.java, and MyCommandHandler.class must be found in the Display Server's classpath.

The following example is a JavaScript Custom Command Handler that will execute the custom command client_echo on the client:

function rtvGetInvokeCommandOnClient (commandString)
     {
  switch (commandString) {

   case 'client_echo':
     // the custom "client_echo" command should
     // be run in the client browser, so
     // return true here
    return true;

   default:
     // all other custom commands should be
     // run on the server
    return false;
  }
     }

function rtvInvokeCommand (commandString, valueString)
     {
  switch (commandString) {

   case 'client_echo':
    alert("ECHO: " + valueString);
    break;
  }
     }