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 boolean invokeCommand (String commandString, Object value)

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 cause the command value to print to the console whenever the custom command my_command is executed.

import com.sl.gmsjrtview.*;

public class MyCommandHandler extends GmsRtViewCustomCommandHandler
{

/** This method is called each time a custom command is executed in RTView.
 *  If this method does not process the specified command, return false so it
 *  will be processed in RTView.
 *  <P>
 *  @param commandString the command string
 *  @param value the command value
 *  <P>
 */

public boolean invokeCommand (String commandString, Object value)
{
        if (commandString.equals("my_command")) {
                System.out.println(value);
                return true;
        }

       return false;
}

}

/** Executes an RTView System or data source command and returns the
* resulting command status.
* @param command the command string. This must use the correct syntax
* for the system or data source command.
* @param dataServer the name of the dataServer connection to execute the
* command on. If this is null or empty string, the command will be executed
* in the local process.
*
*/
public GmsRtViewCommandStatus executeRtvCommand (String command, String dataServer)

/** Utility method to create a properly formatted sql command string. This will
* return null if either the sqlStatement or the dbName is null or empty string.
* @param sqlStatement The sql statement to execute.
* @param dbName The name of the database connection to execute this command
* on.
* @return A string in correct format to pass into executeRtvCommand().
*/
public String makeSqlCommandStr (String sqlStatement, String dbName)

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