The built-in Execution and Verification Procedures have the ability to execute several common tasks. However, there may be times when a specific procedure is required. The TestManager application may be extended by creating custom procedures. These procedures are created by writing a Java class that implements a specific interface, then registering the new procedure with the TestManager application. Once registered, the procedure may be used within Testcases in the same way as for built-in procedures.

Execution Procedures
A custom Execution Procedure is created by implementing the following Java interface:

  package com.jj.testmgr.procedure;

  public interface Procedure
  {
    public void SetContext(Context context);

    public void Execute()
      throws java.lang.Exception;

    public boolean Cancel();

    public int GetProgress();

    public com.jj.testmgr.run.ExecutionState GetStatus();
  }

This interface class can be found in the TestManager.jar file in the root of the installation.

Test Manager will invoke the methods of this class in the following order

    public void SetContext(Context context);

This method is called first. A Context object is passed in. This object gives the procedure some information about its environment. The class definition is described below. It is a good idea to store a reference to this object in the implementation class.

    public void Execute()
        throws java.lang.Exception;

This method is called to perform the execution. The method should return when the execution has completed, or failed, or been cancelled. If the method throws an exception then the application will mark the Testcase as failed.

    public boolean Cancel();

If the user cancels the operation, the Cancel() method will be invoked. This should cause the Execute() method to terminate. A boolean value should be returned to indicate whether the execution was successfully cancelled. It is possible to provide an empty implementation of this method, in which case the Execution Procedure will not support the cancel operation. (The effect of this is that when the user cancels a run, the execution of this procedure will continue until completion, and then the run will halt.)

    public int GetProgress();

This method should return the progress of the execution, as a value between 0 and 100. Again, this method may be implemented in a simple manner by setting the progress as 0, until execution has completed, when the progress can be returned as 100.

    public com.jj.testmgr.run.ExecutionState GetStatus();

This method should return the status of the execution, as an object of the following type:

  package com.jj.testmgr.run;

  public class ExecutionState
  {
    public ExecutionState()
    public ExecutionState(int state)

    public void Set(int state)
    public int  Get()

    final static public int STATE_NOT_STARTED = 1;
    final static public int STATE_RUNNING     = 2;
    final static public int STATE_COMPLETED   = 3;
    final static public int STATE_FAILED      = 4;
    final static public int STATE_CANCELLED   = 5;
  }

The Set() method is used to set the status of the execution to one of the constant values defined in this class.

The Context object is defined below:

  package com.jj.testmgr.procedure;

  public class Context
  {
    public String GetProperty(String name)

    public File GetDataLocation()

    public PrintWriter GetWriter()
  }

The class provides context information for the Execution Procedure, as follows:

    public String GetProperty(String name)

This method will return the value of the property with the given name, or null if the property could not be found.

    public File GetDataLocation()

This method will return the directory where the execution is taking place (ie: the staging area directory of the Testcase).

    public PrintWriter GetWriter()

This method will return a PrintWriter object that can be used for writing messages to the execution log file.

Sample Execution Procedure
The following class definition shows an outline of an ExecutionProcedure implementation.

  package mypackage;

  import com.jj.testmgr.run.ExecutionState;
  import com.jj.testmgr.procedure.Context;

  public class MyProcedure implements com.jj.testmgr.procedure.Procedure
  {
    public MyProcedure()
    {
      SetStatus(ExecutionState.STATE_NOT_STARTED);
    }

    public void Execute()
        throws Exception
    {
      // Get properties from Context
      String property1 = GetContext().GetProperty("property1");
      // ...

      GetContext().GetWriter().println("  Executing MyProcedure");
      SetProgress(0);
      SetStatus(ExecutionState.STATE_RUNNING);

      try
      {
        // PERFORM PROCEDURE EXECUTION HERE

        SetProgress(100);
        SetStatus(ExecutionState.STATE_COMPLETED);
        GetContext().GetWriter().println("  MyProcedure has completed");
      }
      catch (Exception e)
      {
        GetContext().GetWriter().println("  MyProcedure has failed: " + e.getMessage());
        SetStatus(ExecutionState.STATE_FAILED);
      }
    }

    public boolean Cancel()
    {
      return false;
    }

    public  void           SetContext(Context context) { _context = context; }
    private Context        GetContext()                { return _context; }
    public  ExecutionState GetStatus()                 { return _status; }
    public  int            GetProgress()               { return _progress; }
    private void           SetStatus(int status)       { _status.Set(status); }
    private void           SetProgress(int progress)   { _progress = progress; }

    private int            _progress;
    private ExecutionState _status = new ExecutionState();
    private Context        _context;
  }

Verification Procedures
A custom Verification Procedure is created by implementing the following Java interface:

  package com.jj.testmgr.procedure;

  public interface VerificationProcedure
  {
    public void SetContext(VerificationContext context);

    public void Verify()
        throws Exception;

    public com.jj.testmgr.run.VerificationState GetStatus();
  }

This interface is found in the TestManager.jar file in the root of the installation.

The system will invoke the methods of this class in the following order

    public void SetContext(Context context);

This method is called first. A VerificationContext object is passed in (a sublass of the Context class used in the Execution Procedure). This object gives the procedure some information about its environment. The class definition is described below. It is a good idea to store a reference to this object in the implementation class.

    public void Verify()
        throws java.lang.Exception;

This method is called to perform the verification. The method should return when the verification has completed, or failed. If the method throws an exception then Test Manager will mark the Testcase as failed.

    public com.jj.testmgr.run.VerificationState GetStatus();

This method should return the status of the verification, as an object of the following type:

  package com.jj.testmgr.run;

  public class VerificationState
  {
    public VerificationState()
    public VerificationState(int state)

    public void Set(int state)
    public int  Get()

    final static public int STATE_UNKNOWN      = 0;
    final static public int STATE_SUCCESSFUL   = 1;
    final static public int STATE_UNSUCCESSFUL = 2;
    final static public int STATE_NO_BENCHMARK = 3;
  }

The Set() method is used to set the status of the verification to one of the constant values defined in this class.

The VerificationContext object is defined below:

  package com.jj.testmgr.procedure;

  public class VerificationContext extends Context
  {
    public File GetBenchmarkLocation()
    public long GetStartTime()
    public long GetEndTime()
  }

The class provides context information for the Verification Procedure, as follows:

    public File GetBenchmarkLocation()

This method will return the directory where the benchmark results for this Testcase are stored (if the Testcase does not have any benchmark results, then this directory will not exist)

    public long GetStartTime()
    public long GetEndTime()

These methods return the start and end time of the Testcase execution, as the number of milliseconds since midnight, January 1, 1970.

Sample Verification Procedure
The following class definition shows an outline of a VerificationProcedure implementation.

  package mypackage;

  import com.jj.testmgr.run.VerificationState;
  import com.jj.testmgr.procedure.VerificationContext;

  public class MyVerificationProcedure implements com.jj.testmgr.procedure.VerificationProcedure
  {
    public MyVerificationProcedure()
    {
      _state = new VerificationState();
    }

    public void Verify()
        throws Exception
    {
      // Get properties from Context
      String property1 = GetContext().GetProperty("property1");
      // ...

      GetContext().GetWriter().println("  Performing Verification using MyVerificationProcedure");

      // PERFORM VERIFICATION HERE

      GetContext().GetWriter().println("  Verification has completed");

      // Set the verification status
      //if (successful)
      //  GetStatus().Set(VerificationState.STATE_SUCCESSFUL);
      //else if (no benchmark)
      //  GetStatus().Set(VerificationState.STATE_NO_BENCHMARK);
      //else
      //  GetStatus().Set(VerificationState.STATE_UNSUCCESSFUL);
    }

    public  void                SetContext(VerificationContext context) { _context = context; }
    public  VerificationState   GetStatus()                             { return _state; }
    private VerificationContext GetContext()                            { return _context; }

    private VerificationContext _context;
    private VerificationState   _state;

  }

Registering Procedures
Once a procedure (whether an Execution Procedure or a Verification Procedure) has been created and compiled, it then needs to be registered with Test Manager. There are two steps that must be performed.

Firstly, the application must be able to find the class file for the custom procedure. This can be placed in the classes directory in the root of the installation. Alternatively, the classpath used by the system may be extended to include extra directories or jar files.

Secondly, the new procedure should be registered with the application using the menu options, as shown below:

Pressing the Register button will cause the following dialog to be displayed:

The new procedure should be given a unique name, and the implementation class should be supplied. The checkbox indicates whether this is an Execution Procedure or a Verification Procedure.

Finally, a set of properties can be added to the procedure when it is registered. This is not really necessary, but it can be helpful to add any properties that the custom procedure requires. When the procedure is instantiated in a Testcase, the list of properties will be shown to remind the user that these properties need to be set.