Implement the Custom Step Adapter Class

What do you want your custom step to accomplish? This is important to know before you begin to write the Java code necessary to implement your custom step.

There are two ways that you could approach this problem:

You could create a custom step to navigate through any and all vehicle screens with a single execution.
-or-
You could create a custom step to handle a single vehicle screen of any type and let the navigation engine repeatedly call the step as needed.

For the purposes of this How-To, we are using the second approach. This will allow you to leverage the ability of the navigation engine to recognize when you have returned to the SSN screen, and have no more vehicles to process; also, the performance is more reliable. (The performance suffers in the first option — having the custom step implementation navigate through all the vehicle screens — because the sendKeys method is used to facilitate navigation, which introduces the use of settle time.)

To create the sample task

Implement the first method, isRecognized(), in the custom step adapter.

isRecognized() must return a Boolean value. The navigation engine uses the return value from this method to determine whether it should execute the custom step.

For this example, the isRecognized method of the custom step adapter must return a value of true if the host is on a vehicle screen, and false if it is not.

 /**
     * Decides if the current screen is an acceptable match
     *   for this custom step
     * Overrides this method to decide if the custom step can 
     *   start execution on this screen
     * @return true if the step should be run, else return false
     * @throws CustomStepException
     * @throws NavException
     */
    public boolean isRecognized() throws CustomStepException, NavException
    {
        boolean screenMatched = false;
        //get the text in the first host field on the screen using the IQASCreen interface
        String str = qaScreen.getField(1).getText();
        //determine if the text contains the string "CAR", "BOAT", "TRUCK", or "MOTORCYCLE"
        if (str.indexOf(S_CAR) != -1 || str.indexOf(S_BOAT) != -1 || str.indexOf(S_TRUCK) != -1 || str.indexOf(S_CYCLE) != -1)
        {
            screenMatched = true;
        }
        //return true or false
        return screenMatched;
     }

To do this successfully, you must understand your host application and implement the following logic: if the contents of the first host field on the screen contains the word, "CAR," "TRUCK," "MOTORCYCLE," or "BOAT," then we are on a vehicle screen; otherwise, we are not.

Use the IQAScreen interface to retrieve the contents of the host fields, and Java to implement the logic.

Implement the second method, processData(), which gathers the desired host data from the current host screen and adds it to the task variable map.

Since the number of vehicle screens that will be encountered in a given task execution is unknown, you need to use the ITaskData interface support to populate table data. This will return a collection of data from the custom step. From each vehicle screen we want to return the vehicle type, model, and year, so we will define three columns in our table data output to represent the three pieces of information we want from each vehicle screen.

/**
     * Called to collect the data from the host screen(s)
     *
     * @throws CustomStepException
     * @throws NavException
     */
    public void processData() throws CustomStepException, NavException
     {
        ITable table = taskData.getTable(S_TABLE);
        if (table == null)
         {
            //We need to define the table because this step has not been visited yet in this task execution
            String[] columnNames = {S_TYPE, S_MODEL, S_YEAR};
            table = taskData.createTable(columnNames);
         }
        //Host field at index 12 contains the vehicle type
        String type = qaScreen.getField(12).getText().trim();
        //Host field at index 16 contains the vehicle model
        String model = qaScreen.getField(16).getText().trim();
        //Host fields at index 20 contain the vehicle year
        String year = qaScreen.getField(20).getText().trim();
        //create the row of table data with the values scraped from the host screen
        String[] row = {type, model, year};
        //add the row to the table
        table.addRow(row);
        //add the table back into the task variable map
        taskData.putTable(S_TABLE, table);
     }

The processData() implementation in our custom step implementation defines the table, if it is the first time the step has been executed, or adds data to the existing table in the task variable map.

You can examine the field layout to determine which host fields contain the desired data in the designer.

Implement the third and last method, getTransitionAction().

This method tells the navigation engine which AID key to send to the host to navigate to the next step in the task.

In this example, to navigate from any vehicle host screen we must send ENTER to the host, so that the getTransitionAction() method will return the String "@E," which is the HLLAPI equivalent of the ENTER AID key.

 /**
     * Called when the step transitions to the next step
     * This method needs to contain the actions that are to be  
     *   performed before the next step can be run
     *
     * @return a String containing the final navigation command, e.g., @E, @1, etc.
     * @throws CustomStepException
     * @throws NavException
     */
    public String getTransitionAction() throws CustomStepException, NavException
    {
        return "@E";
    }