## org.eclipse.datatools.sqltools.result
Class ResultsViewAPI

    java.lang.Object
      org.eclipse.datatools.sqltools.result.ResultsViewAPI

    public class ResultsViewAPI

extends java.lang.Object

The core API of SQL Results View.

To use `ResultsViewAPI` to display message or result set on SQL Results View, follow the steps below:

- Initiate an instance of `OperationCommand`
- Create a new result instance using createNewInstance(OperationCommand cmd, Runnable terminateHandler)
- Get the instance of `ResultsViewAPI` via ResultsViewAPI.getInstance()
- Invoke the methods in `ResultsViewAPI` to display result item, given the instance of `OperationCommand`

Three types of result item can be displayed on SQL Results View:

- Message(Include plain message, status message and update count message)
- Result set(JDBC result set, tabular data set and XML result set)
- Parameter

Usage example:

            OperationCommand cmd = new OperationCommand(OperationCommand.ACTION_EXECUTE, "select * from test_table", "SQL Editor", "ase_15", "pubs2");
            ResultsViewAPI resultsView = ResultsViewAPI.getInstance();
            resultsView.createNewInstance(cmd, null);
            resultsView.appendStatusMessage(cmd, "Start executing...");
            ResultSet rs = .....;//execution logic to get result set from database
            resultsView.appendResultSet(cmd, rs);
            String xmlString = ....;//execution logic to get XML result string from database
            resultsView.appendXMLResultSet(cmd, xmlString);
            resultsView.appendStatusMessage(cmd, "Operation Succeeded");
            resultsView.updateStatus(cmd, OperationCommand.STATUS_SUCCEEDED);

Notice that except that the user can display a JDBC result set on SQL Results View, he/she can also initiate an instance of `IResultSetObject` and then display it on SQL Results View. The following code is an usage example:

     OperationCommand cmd = new OperationCommand(OperationCommand.ACTION_EXECUTE, "select * from test_table", "SQL Editor",
             "ase_15", "pubs2");
     ResultsViewAPI resultsView = ResultsViewAPI.getInstance();
     resultsView.createNewInstance(cmd, null);
     resultsView.appendStatusMessage(cmd, "Start executing...");

     IResultSetRow row1 = new ResultSetRow(new String[]
     {
         "1", "21", "Jack"
     });
     IResultSetRow row2 = new ResultSetRow(new String[]
     {
         "2", "23", "Micheal"
     });
     ArrayList rows = new ArrayList();
     rows.add(row1);
     rows.add(row2);
     IResultSetObject rs = new ResultSetObject(rows, new String[]
     {
         "Id", "Age", "Name"
     }, new int[]
     {
         Types.CHAR, Types.CHAR, Types.CHAR
     }, new int[]
     {
         8, 8, 21
     });

     resultsView.appendResultSet(cmd, rs);
     resultsView.appendStatusMessage(cmd, "Operation Succeeded");
     resultsView.updateStatus(cmd, OperationCommand.STATUS_SUCCEEDED);

Author:
  Dafan Yang
See Also:
  `OperationCommand`, `ResultSetObject`, `Parameter`

Method Summary
`boolean` `appendPlainMessage(OperationCommand cmd, java.lang.String message)` Appends a plain message to the result instance, when using multiple windows display mode, this kind of messages will be displayed on "Message" tab
`boolean` `appendResultSet(OperationCommand cmd, IResultSetObject rs)` Appends an instance of `IResultSetObject` to SQL Results View.
`boolean` `appendResultSet(OperationCommand cmd, java.sql.ResultSet rs)` Appends a JDBC result set to the result instance.
`boolean` `appendStatusMessage(OperationCommand cmd, java.lang.String message)` Appends a status message to the result instance, when using multiple windows display mode, this kind of messages will be displayed on "Status" tab
`boolean` `appendThrowable(OperationCommand cmd, java.lang.Throwable th)` Appends an exception to the result instance, this won't affect the UI.
`boolean` `appendUpdateCountMessage(OperationCommand cmd, int count)` Appends an update count message to the result instance.
`boolean` `appendXMLResultSet(OperationCommand cmd, java.lang.String xmlString)` Appends an XML result set to SQL Results View.
`int` `calculateStatus(OperationCommand command)` Calculates the status of the result instance based on its sub-results' status.
`boolean` `checkView()` Checks if the SQL Results View is active, if not, create it and bring it to the top.
`boolean` `createNewInstance(OperationCommand cmd, java.lang.Runnable terminateHandler)` Creates a new result instance given the `OperationCommand` instance
`boolean` `createSubInstance(OperationCommand parentCmd, OperationCommand cmd, java.lang.Runnable terminateHandler)` Creates a sub result instance for the given parent result instance.
`int` `getCurrentStatus(OperationCommand cmd)` Returns the current status of the given operation command
`java.lang.Throwable[]` `getFailThrowables(OperationCommand cmd)` Returns the exceptions thrown when generating the result instance
`java.lang.Throwable[]` `getFailThrowables(OperationCommand cmd, boolean includeSubThrowables)` Returns the exceptions thrown when generating the result instance
`static ResultsViewAPI` `getInstance()` Returns the instance of `ResultsViewAPI`
`int` `getMaxRowDisplayPreference()` Gets the maximum rows displayed preference
`int` `getMaxRowPreference()` Gets the max row preference
`IResultInstance` `getResultInstance(OperationCommand cmd)` Return the IResultInstance object correlative with the OperationCommand object.
`OperationCommand` `getSubOperationCommand(OperationCommand parentCmd, int subNum)` Returns the operation request of the sub-result
`void` `setCheckSRV(boolean checksrv)`
`boolean` `showParameters(OperationCommand cmd, java.util.List params)` Shows the parameters on SQL Results View.
`boolean` `updateStatus(OperationCommand cmd, int status)` Updates the status of the result instance.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### getInstance

    public static ResultsViewAPI getInstance()

  Returns the instance of `ResultsViewAPI`

  Returns:
    the instance of `ResultsViewAPI`

### getCurrentStatus

    public int getCurrentStatus(OperationCommand cmd)

  Returns the current status of the given operation command

  Parameters:
    `cmd` - the operation command
  Returns:
    the current status of corresponding result instance, returns -1 if the operation command is `null` or the corresponding result instance is not found
  See Also:
    `OperationCommand.STATUS_STARTED`, `OperationCommand.STATUS_RUNNING`, `OperationCommand.STATUS_SUCCEEDED`, `OperationCommand.STATUS_FAILED`, `OperationCommand.STATUS_TERMINATED`, `OperationCommand.STATUS_WARNING`, `OperationCommand.STATUS_CRITICAL_ERROR`

### getFailThrowables

    public java.lang.Throwable[] getFailThrowables(OperationCommand cmd,
                                                   boolean includeSubThrowables)

  Returns the exceptions thrown when generating the result instance

  Parameters:
    `cmd` - the operation request, should not be null
    `includeSubThrowables` - whether include all the sub results' throwables or not
  Returns:
    the exceptions thrown

### getFailThrowables

    public java.lang.Throwable[] getFailThrowables(OperationCommand cmd)

  Returns the exceptions thrown when generating the result instance

  Parameters:
    `cmd` - the operation request, should not be null
  Returns:
    the exceptions thrown

### appendThrowable

    public boolean appendThrowable(OperationCommand cmd,
                                   java.lang.Throwable th)

  Appends an exception to the result instance, this won't affect the UI. The consumer can store the exceptions here and use them later.

  Parameters:
    `th` - the exception thrown

### appendPlainMessage

    public boolean appendPlainMessage(OperationCommand cmd,
                                      java.lang.String message)

  Appends a plain message to the result instance, when using multiple windows display mode, this kind of messages will be displayed on "Message" tab

  Parameters:
    `cmd` - the operation request, should not be null
    `message` - the message string, should not be null
  Returns:
    `true` if operation succeeds; `false` otherwise

### appendResultSet

    public boolean appendResultSet(OperationCommand cmd,
                                   IResultSetObject rs)

  Appends an instance of `IResultSetObject` to SQL Results View.

  Parameters:
    `cmd` - the operation request, should not be null
    `rs` - the instance of `IResultSetObject`
  Returns:
    `true` if operation succeeds; `false` otherwise

### appendResultSet

    public boolean appendResultSet(OperationCommand cmd,
                                   java.sql.ResultSet rs)

  Appends a JDBC result set to the result instance.

  Parameters:
    `cmd` - the operation request, should not be null
    `rs` - the JDBC result set, should not be null
  Returns:
    `true` if operation succeeds; `false` otherwise

### appendStatusMessage

    public boolean appendStatusMessage(OperationCommand cmd,
                                       java.lang.String message)

  Appends a status message to the result instance, when using multiple windows display mode, this kind of messages will be displayed on "Status" tab

  Parameters:
    `cmd` - the operation request, should not be null
    `message` - the message string, should not be null
  Returns:
    `true` if operation succeeds; `false` otherwise

### appendUpdateCountMessage

    public boolean appendUpdateCountMessage(OperationCommand cmd,
                                            int count)

  Appends an update count message to the result instance.

  Parameters:
    `cmd` - the operation request, should not be null
    `count` - the update count number, should greater than or equals to 0
  Returns:
    `true` if operation succeeds; `false` otherwise

### appendXMLResultSet

    public boolean appendXMLResultSet(OperationCommand cmd,
                                      java.lang.String xmlString)

  Appends an XML result set to SQL Results View.

  Parameters:
    `cmd` - the operation request, should not be null
    `xmlString` - the xml string
  Returns:
    `true` if operation succeeds; `false` otherwise

### checkView

    public boolean checkView()

  Checks if the SQL Results View is active, if not, create it and bring it to the top.

  Returns:
    `true` if operation succeeds; `false` otherwise

### createNewInstance

    public boolean createNewInstance(OperationCommand cmd,
                                     java.lang.Runnable terminateHandler)

  Creates a new result instance given the `OperationCommand` instance

  Parameters:
    `cmd` - the operation request, can not be null
    `terminateHandler` - handler used to teminate this item, can be null
  Returns:
    `true` if the creation succeeds; `false` otherwise

### getResultInstance

    public IResultInstance getResultInstance(OperationCommand cmd)

  Return the IResultInstance object correlative with the OperationCommand object.

  Parameters:
    `cmd` - the operation request, can not be null
  Returns:
    the correlative IResultInstance object

### showParameters

    public boolean showParameters(OperationCommand cmd,
                                  java.util.List params)

  Shows the parameters on SQL Results View. If there are already parameters displayed, the old parameters will be cleared.

  Parameters:
    `cmd` - he operation request, should not be null
    `params` - a list of `Parameter` instances
  Returns:
    `true` if operation succeeds; `false` otherwise
  See Also:
    `Parameter`

### updateStatus

    public boolean updateStatus(OperationCommand cmd,
                                int status)

  Updates the status of the result instance. Note that some simple logical check will be performed.

  Parameters:
    `cmd` - the operation request, should not be null
    `status` - the new status (There are 7 statuses defined in `OperationCommand`)
  Returns:
    `true` if operation succeeds; `false` otherwise
  See Also:
    `OperationCommand.STATUS_STARTED`, `OperationCommand.STATUS_RUNNING`, `OperationCommand.STATUS_SUCCEEDED`, `OperationCommand.STATUS_FAILED`, `OperationCommand.STATUS_TERMINATED`, `OperationCommand.STATUS_WARNING`, `OperationCommand.STATUS_CRITICAL_ERROR`

### createSubInstance

    public boolean createSubInstance(OperationCommand parentCmd,
                                     OperationCommand cmd,
                                     java.lang.Runnable terminateHandler)

  Creates a sub result instance for the given parent result instance.

  Parameters:
    `parentCmd` - the operation request instance of the parent result, can not be null
    `cmd` - the operation request instance, can not be null
    `terminateHandler` - the handler to terminate the new instance, can be null
  Returns:
    `true` if the creation succeeds; `false` otherwise

### getSubOperationCommand

    public OperationCommand getSubOperationCommand(OperationCommand parentCmd,
                                                   int subNum)

  Returns the operation request of the sub-result

  Parameters:
    `parentCmd` - the parent operation request, can not be null
    `subNum` - the number of the sub-instance, 0-based
  Returns:
    the operation request of the sub-result

### calculateStatus

    public int calculateStatus(OperationCommand command)

  Calculates the status of the result instance based on its sub-results' status. The consumer should update the status of the parent result by invoking this method to caculate its status

  Parameters:
    `command` - the operation command
  Returns:
    the status of the result instance

### getMaxRowPreference

    public int getMaxRowPreference()

  Gets the max row preference

  Returns:
    the maximum row count from the Results View preferences

### getMaxRowDisplayPreference

    public int getMaxRowDisplayPreference()

  Gets the maximum rows displayed preference

  Returns:
    the maximum number of rows being displayed from the Results View preferences

### setCheckSRV

    public void setCheckSRV(boolean checksrv)

Copyright © 2006 -- 2008 Actuate, IBM Corporation, Sybase, Inc. and others. All rights reserved.