A Standard Commands

The JavaTest harness provides a number of standard commands that you can use to configure an environment to run a test suite on your test platform. These commands all extend the standard JavaTest Command class.

With these standard commands, you can configure the JavaTest harness for a wide variety of test platforms. If, however, you find that you cannot create an environment for your test platform using these commands, you may need to write your own: see Writing Custom Commands for more details.

The standard commands are as follows:

ActiveAgentCommand: A command to execute a subcommand on a JavaTest Agent running in active mode
ExecStdTestSameJVMCmd: A command to execute a simple API test in the same JVM in which the JavaTest harness or the JavaTest Agent is running
ExecStdTestOtherJVMCmd: A command to execute a simple API test in a JVM that is separate from the JVM in which the JavaTest harness or the JavaTest Agent is running
JavaCompileCommand: An example command that demonstrates how to invoke a Java application via a wrapper class
PassiveAgentCommand: A command to execute a subcommand on a JavaTest Agent running in passive mode
ProcessCommand: A command to execute a system command in a separate process
SerialAgentCommand: A command to execute a subcommand on a JavaTest Agent, communicating via a serial line

Note:
Examples in this appendix use Unix style commands and file separators.

ActiveAgentCommand

A command to execute a command in a separate JVM, typically on a remote machine, by delegating it to a JavaTest Agent which has been configured to run in active mode. This means it contacts the JavaTest harness to determine what it should do.

The JavaTest active agent pool must be started before you start running tests that use this command. The active agent pool holds the requests from the active agents until they are required. You can start the active agent pool from the JavaTest GUI or command line.

Usage

com.sun.javatest.agent.ActiveAgentCommand [options] command-class [command-arguments]

Arguments

-classpath path	This option allows you to specify a classpath on the system running the JavaTest harness from which to load the command class and any classes it invokes. The classes are automatically loaded into the agent as needed. If the class path is not specified, the classes are loaded from the agent's class path. See Chapter 4 for additional information about using the `-classpath` option.
–`mapArgs`	The command to be executed might contain values that are specific to the host running the JavaTest harness and that might not be appropriate for the host that actually runs the command. If this option is given, the agent uses a local mapping file to translate specified string values into replacement values. This is typically used to map filenames from the view on one host to the view on another. See the JavaTest online help for more information.
–`tag` tag	This option allows the user to specify a string that is used to identify the request on the agent. If not specified, the default value, command-class, is used. It is suggested that the URL of the test should be used as the value for this option. A configuration can use the symbolic name `$testURL`, which is substituted when the command is executed.
`command` class	The name of a command class to be executed by the agent. If the -classpath option is not used, the class should be on the classpath of the agent, and should be appropriate for the agent, depending on the security restrictions in effect. For example, an agent running as an application might be able to run a `ProcessCommand`, but an agent running as an applet might not. The class should implement the interface `com.sun.javatest.Command`.
`command arguments`	The arguments to be passed to the run method of an instance of the command class running on the agent. The arguments can be translated to agent-specific values if the `–mapArgs` option is given.

Description

ActiveAgentCommand is a facility to execute a command on a JavaTest Agent that has been configured to run in active mode. A JavaTest Agent provides the ability to run tests in a context that might not be able to support the JavaTest harness. This could be because the tests are to be run on a machine with limited resources (such as memory), or in a security-restricted environment (such as a browser), or on a newly developed platform on which it is not possible to run the JDK.

Commands often contain host-specific arguments, such as filenames or directories. Although the files and directories might be accessible from the agent host (and in general, should be), the paths might be different. For example, /usr/local on a Solaris platform might be mounted as a network drive like H: on a Windows platform. When an agent is initialized, it may be given information on how to translate strings from one domain to another. On a per-command basis, the agent can be instructed to translate a command according to the translation tables it is given.

The command to be executed on an agent can be identified with a tag for tracing and debugging purposes. If none is specified, a default identification is used.

Any output written by the command when it is executed by the agent appears as the output of the ActiveAgentCommand command itself. If the command is successfully executed by the agent (i.e. the Command object is successfully created and the run method invoked), the result of ActiveAgentCommand is the result of the command executed by the agent. Otherwise, an appropriate error status is returned.

Example:

Using ActiveAgentCommand to Execute a ProcessCommand on an Active Agent

This example is based on the following sample code demonstrating ProcessCommand:

com.sun.javatest.lib.ProcessCommand /usr/local/jdk1.6/solaris/bin/javac
     -classpath /home/juser/classes –d /home/juser/classes HelloTest.java

To make a command execute on another machine, prefix it with ActiveAgentCommand and any arguments that ActiveAgentCommand requires:

compile.java=com.sun.javatest.agent.ActiveAgentCommand com.sun.javatest.lib.ProcessCommand \
     /usr/local/jdk1.6/solaris/bin/javac \
     -classpath /home/juser/classes \
     –d /home/juser/classes HelloTest.java

See Also:

All the other standard commands in this appendix. Subject to security restrictions on the agent, they can all be executed remotely by means of ActiveAgentCommand.

ExecStdTestSameJVMCmd

A command that executes a standard test in the same JVM in which JavaTest Agent is running.

Usage

com.sun.javatest.lib.ExecStdTestSameJVMCmd [options] test_class [test_args]

Arguments

–loadDir directory	Creates a `ClassLoader` that loads any necessary classes from the specified directory. The `ClassLoader` is garbage collected once `ExecStdTestSameJVMCmd` has completed. If you do not specify `-loadDir`, the system class loader is used. Using a separate `ClassLoader` for each test reduces the chance that one test interferes with another. Also, using a separate `ClassLoader` allows the command to unload test classes after the test is executed, which could be critical in memory constrained environments. On some systems, the security manager restricts the ability to create a `ClassLoader`. If you use this option and cannot create a `ClassLoader`, the command throws a `SecurityException.`
test class	Specifies the name of the test class to execute. This class must be a subtype of `com.sun.javatest.Test`. To specify a class in the test description currently being processed by the JavaTest harness, use the `$executeClass` substitution variable.
test args	Specifies a list of arguments to be passed to the `run` method of the class being executed. To specify arguments in the test description currently being processed by the JavaTest harness, use the `$executeArgs` substitution variable

Description

ExecStdTestSameJVMCmd is a JavaTest command that executes a standard test in the same JVM in which the JavaTest Agent is running. The class must be a subtype of com.sun.javatest.Test.

ExecStdTestSameJVMCmd creates a new instance of the class, calls its run method, and passed the class args. If the class is successfully created and invoked, the result of ExecStdTestSameJVMCmd is equal to the result of the run method of the object.

Examples:

Simple use of ExecStdTestSameJVMCmd:

     command.execute=com.sun.javatest.lib.ExecStdTestSameJVMCmd \
          $testExecuteClass $testExecuteArgs

Using ExecStdTestSameJVMCmd Inside an Environment:

     com.sun.javatest.lib.ExecStdTestSameJVMCmd HelloTest

See Also:

ExecStdTestOtherJVMCmd

ExecStdTestOtherJVMCmd

A variant of ProcessCommand that executes a standard test using a subcommand in a separate process.

Usage

com.sun.javatest.lib.ExecStdTestOtherJVMCmd [options] [shell variables] subcommand [args]

Arguments

–v	Used for verbose mode. When ExecStdTestOtherJVMCmd is in verbose mode, additional output information is sent to the TestResult object.
shell variables	Specifies one or more shell environment values that are required by the sub-command. Shell environment variables are written as: name=value.
subcommands	Specifies the name of a program that is executed.
args	Specifies the arguments that are passed to the subcommand.

Description

ExecStdTestOtherJVMCmd is a JavaTest command that executes a test with a subcommand in a separate process (using a separate runtime). You would normally use this command to invoke a JVM to run the test class.Examples of subcommands are the compiler for the Java programming language (javac) and the JVM (java). Normally, a test exits by creating a Status object and then invoking its exit method. This command also returns a Status object, which is equal to the object returned by the test.

Examples

Simple Use of ExecStdTestOtherJVMCmd

     com.sun.javatest.lib.ExecStdTestOtherJVMCmd \
          /usr/local/jdk1.6/solaris/bin/java \
          -classpath /home/juser/classes
          HelloTest

Using ExecStdTestOtherJVMCmd Inside an Environment

     command.execute=com.sun.javatest.lib.ExecStdTestOtherJVMCmd \
          /usr/local/jdk1.6/solaris/bin/java \
          -classpath /home/juser/classes
          $testExecuteClass $testExecuteArgs

See Also:

ExecStdTestSameJVMCmd, ProcessCommand

JavaCompileCommand

Invokes a compiler in the same JVM in which the JavaTest harness or the JavaTest Agent is running.

Usage

com.sun.javatest.lib.JavaCompileCommand [–compiler compiler-spec] [args]

Arguments

-compiler compiler-spec	If the –compiler option is given, compiler-spec specifies the class name for the compiler, optionally preceded by a name for the compiler followed by a ":". If no compiler name is given before the class name, the default name is "java" followed by a space and then the class name. If the –compiler option is not given, the default value for compiler-spec is javac:sun.tools.javac.Main.
args	Specifies the arguments to the compiler's compile method. If you use the default compiler, javac, the arguments are exactly the same as those you would use for javac. In this case, you should refer to documentation for the JDK for more details. Otherwise, refer to the documentation for the compiler you specify.

Description

This command is primarily an example that shows how any application written in the Java programming language can be interfaced to the JavaTest harness by writing a wrapper command. By default, the application in this example is the JDK compiler, javac, but any class implementing the same signature can be invoked. javac is normally run from the command line, per its specification, but it does have an undocumented interface API, that is sufficiently typical to be used as the basis for this example.

The compiler is assumed to have a constructor and compile method matching the following signature:

public class COMPILER {
     public COMPILER(java.io.OutputStream out, String name);
     boolean compile(String[] args);
}

When JavaCompileCommand is used, an instance of the compiler is created. The constructor is passed a stream to which to write any messages, and the name of the compiler to be used in those messages. Then, the compile method is called with any args passed to JavaCompileCommand. If the compile method returns true, the result is a status of "passed"; if it returns false, the result is "failed". If any problems arise, the result is "error".

The source code for this example is provided in the examples directory. It is the file JavaCompileCommand.java in the directory src/share/classes/com/sun/javatest/lib/ under the main JavaTest installation directory.

Examples:

Simple use of JavaCompileCommand

     com.sun.javatest.lib.JavaCompileCommand HelloWorld.java

Using JavaCompileCommand Inside an Environment

     command.compile.java=com.sun.javatest.lib.JavaCompileCommand \
         –d $testClassDir $testSource

Using JavaCompileCommand to Invoke the RMI compiler

     command.compile.java=com.sun.javatest.lib.JavaCompileCommand \
          –compiler rmic:sun.rmi.rmic.Main \
          –d $testClassDir $testSource

See Also:

ProcessCommand

PassiveAgentCommand

A command to execute a command on a remote machine by delegating it to a JavaTest Agent that is configured to run in passive mode.

Usage

com.sun.javatest.agent.PassiveAgentCommand [options] command -class [command-arguments]

Arguments

-classpath path	This option lets you to specify a classpath on the system running the JavaTest harness from which to load the command class and any classes it invokes. The classes are automatically loaded into the agent as needed. Otherwise, classes are loaded using the agent's class path. See Chapter 4 for additional information about using the -classpath option.
–host host-name	Specifies the host on which to run the command. A passive JavaTest Agent must be running on this host to execute the command. The option must be given; there is no default.
–mapArgs	The command to be executed might contain values that are specific to the host running the JavaTest harness and that might not be appropriate for the host that actually runs the command. If this option is given, the agent uses a local mapping file to translate specified string values into replacement values. This is typically used to map filenames from the view on one host to the view on another. See the JavaTest online help for more information.
–port port-number	This option specifies the port to which to connect when requesting an agent to run a command. The default value, 1908, is used if no value is explicitly given.
–tag tag	This option lets the user specify a string that identifies the request on the agent. If not specified, the default value, command-class, is used. It is suggested that the URL of the test be used as the value for this option. A configuration can use the symbolic name $testURL, which is substituted when the command is executed.
command class	The name of a command class to be executed by the agent. The class should be on the classpath of the agent and be appropriate for the agent, depending on the security restrictions imposed on the agent. For example, an agent running as an application might be able to run a ProcessCommand, but an agent running as an applet might not. The class should implement the standard interface com.sun.javatest.Command.
command args	The arguments to be passed to the run method of an instance of the command class running on the agent. The arguments might be translated to agent-specific values if the –mapArgs option is given.

Description

PassiveAgentCommand is a facility to execute a command on a JavaTest Agent that has been configured to run in passive mode. A JavaTest Agent provides the ability to run tests in a context that might not be able to support the entire JavaTest harness. Factors that require use of the JavaTest Agent include limited resources (such as memory), or in a security-restricted environment (such as a browser), or on a newly developed platform on which is not possible to run the JDK.The host and port options identify an agent to be used to execute the command. The JavaTest harness attempts to contact an agent on that system that is running and waiting for requests.

Commands often contain host-specific arguments, such as filenames or directories. Although the files and directories might be accessible from the agent host (and in general, should be), the paths might be different. For example, /usr/local on a Solaris platform can be mounted as a network drive like H: on a Windows NT platform. When an agent is initialized, it may be given information on how to translate strings from one domain to another. On a per-command basis, the agent can be instructed to translate a command according to the translation tables it is given.

The command to be executed on an agent can be identified with a tag for tracing and debugging purposes. If none is specified, a default identification is used.

Any output written by the command when it is executed by the agent appears as the output of the PassiveAgentCommand command itself. If the command is successfully executed by the agent (i.e. the Command object is successfully created and the run method invoked) then the result of PassiveAgentCommand is the result of the command executed by the agent. Otherwise, an appropriate error status is returned.

Examples

Using ActiveAgentCommand to Execute a ProcessCommand on an Active Agent:

    compile.java=\
      com.sun.javatest.agent.PassiveAgentCommand –host calloway \
      com.sun.javatest.lib.ProcessCommand \
      /usr/local/jdk1.6/solaris/bin/javac \
      -classpath /home/juser/classes \
      –d /home/juser/classes HelloTest.java

See Also:

All the other standard commands in this appendix. Subject to security restrictions on the agent, they can all be executed remotely by means of PassiveAgentCommand.

ProcessCommand

Usage

com.sun.javatest.lib.ProcessCommand [options] [envvariables]command [command-arguments]

Arguments

–v	Verbose mode: tracing information is output to the log.
env variables	This is a list of named values to be passed as environment variables to the command to be executed. Each named value should be written as name=value.
command	This is the name of the command to be executed in a separate process.
command arguments	This is a list of arguments to be passed to the command to be executed.

Description

ProcessCommand executes a system command in a separate process with the specified set of environment variables and arguments.

The result of the command is a Status object based upon the exit code of the process. An exit code of zero is interpreted as Status.PASSED; all other exit codes are interpreted as Status.FAILED. There are variants of ProcessCommand that provide different interpretations of the exit code. These variants can be used in more specialized circumstances, such as running tests that use exit codes like 95, 96, and 97.

ProcessCommand copies the standard output stream of the process to the out2 command stream, and the standard error stream of the process to the out1 command stream.

Examples

Simple use of ProcessCommand

     com.sun.javatest.lib.ProcessCommand      
     /usr/local/jdk1.6/solaris/bin/javac 
     -classpath /home/juser/classes –d /home/juser/classes HelloTest.java

Using ProcessCommand in an Environment

     compile.java=com.sun.javatest.lib.ProcessCommand \
           /usr/local/jdk1.6/solaris/bin/javac \
           -classpath /home/juser/classes \
           –d /home/juser/classes $testSource

See Also:

ExecStdTestOtherJVMCmd

SerialAgentCommand

A command to execute a command on a remote machine, by delegating it to a JavaTest Agent that has been configured to communicate via a serial RS232 line.

Usage

com.sun.javatest.agent.SerialAgentCommand [options] command-class [command-arguments]

Arguments

-classpath path	This option lets you specify a classpath on the system running the JavaTest harness from which to load the command class and any classes it invokes. The classes are automatically loaded into the agent as needed. See Chapter 4 for additional information about using the -classpath option.
–mapArgs	The command to be executed might contain values that are specific to the host running the JavaTest harness and that might not be appropriate for the host that actually runs the command. If this option is given, the agent uses a local mapping file to translate specified string values into replacement values. This is typically used to map filenames from the view on one host to the view on another. See the JavaTest online help for more information.
–port port-name	This option specifies the name of the serial port on the system running the JavaTest harness to be used to communicate with a JavaTest Agent that has also been configured to communicate via a serial line. The set of possible names is determined dynamically, and is dependent on the underlying implementation of the javax.comm API. On Solaris, the names are typically ttya, ttyb; on a PC, the names are typically COM1, COM2, COM3 and COM4.
–tag tag	This option lets the user specify a string to be used to identify the request on the agent. If not specified, the default value, command-class, is used. It is suggested that the URL of the test be used as the value for this option. In an environment file, this is available as the symbolic name "$testURL".
command class	The name of a command class to be executed by the agent. The class should be on the class path of the agent, and should be appropriate for the agent, depending on the security restrictions imposed on the agent. For example, an agent running as an application might be able to run a ProcessCommand, but an agent running as an applet might not.
command arguments	The arguments to be passed to the run method of an instance of the command class running on the agent. The arguments can be translated to agent-specific values if the –mapArgs option is given.

Description

SerialAgentCommand is a facility to execute a command on a JavaTest Agent that has been configured to communicate via a serial line. A JavaTest Agent lets you run tests in a context that might not be able to support all of the JavaTest harness. This might be because the tests are to be run on a machine with limited resources (such as memory), or in a security-restricted environment (such as a browser), or on a newly developed platform on which is not possible to run the JDK.

The port option identifies a serial port on the system running the JavaTest harness, which should be connected to a serial port on the system running the JavaTest Agent. The serial line is accessed via the javax.comm optional package. This is not part of the standard JDK, and must be added to your class path when you start the JavaTest harness.

Commands often contain host-specific arguments, such as filenames or directories. Although the files and directories might be accessible from the agent host (and in general, should be), the paths might be different. For example, /usr/local on a Solaris platform could be mounted as a network drive like H: on a Windows NT platform. When an agent is initialized, it may be given information on how to translate strings from one domain to another. On a per-command basis, the agent can be instructed to translate a command according to the translation tables it is given.

The command to be executed on an agent can be identified with a tag for tracing and debugging purposes. If none is specified, a default identification is used.

Any output written by the command when it is executed by the agent appears as the output of the SerialAgentCommand command itself. If the command is successfully executed by the agent (i.e. the Command object is successfully created and the run method invoked), then the result of SerialAgentCommand is the result of the command executed by the agent. Otherwise, an appropriate error status is returned.

Examples

This example is based on the following sample code demonstrating ProcessCommand:

  com.sun.javatest.lib.ProcessCommand
     /usr/local/jdk1.6/solaris/bin/javac 
     -classpath /home/juser/classes –d /home/juser/classes HelloTest.java

A command can be made to execute on another machine simply by prefixing it with SerialAgentCommand and any arguments that SerialAgentCommand requires.

    compile.java=\
       com.sun.javatest.agent.SerialAgentCommand –port ttya \
       com.sun.javatest.lib.ProcessCommand \
       /usr/local/jdk1.6/solaris/bin/javac -classpath /home/juser/classes
       –d /home/juser/classes HelloTest.java

See Also:

All the other standard commands in this appendix. Subject to security restrictions on the agent, they can all be executed remotely by means of SerialAgentCommand.