oracle.dss.util
Interface AsyncDataSource

public interface AsyncDataSource

Field Summary

static int	QUERY_CANCELED Status in which the query execution was canceled.
static int	QUERY_EXECUTING Status in which the query is currently being run.
static int	QUERY_FAILED Status in which the query failed to complete its execution.
static int	QUERY_NEEDS_CONFIRMATION Status in which the query has been paused for user input.
static int	QUERY_NEEDS_EXECUTING Status in which data is not yet available because the query has not yet been run.
static int	QUERY_NEEDS_PARAMETERS Status in which the query's parameters have no values or invalid values.
static int	QUERY_NOT_DEFINED Status in which the specified query does not exist
static int	QUERY_RESULTS_READY Status in which the query has successfully completed.
static int	QUERY_SCHEDULED Status in which the query has been placed on the queue in preparation for being executed.
static int	QUERY_VALIDATING Status in which the parameters of the query are being validated.
static long	UNKNOWN_TIME Constant representing an unknown duration of time.

Method Summary

void	cancelQueryExecution() Attempts to cancel the execution of this data source's query.
void	continueQueryExecution() Continues execution of the query after confirmation was requested.
void	fetchEstimate() Causes the estimated query running time to be synchronously computed.
int	getEstimatedRunningTime() Returns the estimated length of time in milliseconds for the QUERY_EXECUTING state.
int	getEstimatedTimeToDataAvailability() Returns the number of milliseconds until this AsyncDataSource's query and all DataSources prior to it have completed executing.
BIException[]	getExecutionErrors() Returns errors associated with the most recent query execution attempt.
int	getStatus() Returns the status of this AsyncDataSource's query.
boolean	isLinkedTo(AsyncDataSource targetDataSource) Determines if this DataSource and the targetDataSource are linked to the same query.
boolean	linkTo(AsyncDataSource targetDataSource) Makes this AsyncDataSource link to the targetDataSource.
void	notifyListenersIfDataAvailable() Prepares this AsyncDataSource for proper rendering.
void	scheduleQueryExecution(boolean autoConfirm) Places the query on the queue for execution

Field Detail

UNKNOWN_TIME

static final long UNKNOWN_TIME

Constant representing an unknown duration of time. This is one of the values that can be returned by getEstimatedTimeToDataAvailablity or getEstimatedRunTime()

See Also:

Constant Field Values

QUERY_NOT_DEFINED

static final int QUERY_NOT_DEFINED

Status in which the specified query does not exist

See Also:

Constant Field Values

QUERY_NEEDS_PARAMETERS

static final int QUERY_NEEDS_PARAMETERS

Status in which the query's parameters have no values or invalid values.

See Also:

Constant Field Values

QUERY_NEEDS_EXECUTING

static final int QUERY_NEEDS_EXECUTING

Status in which data is not yet available because the query has not yet been run.

See Also:

Constant Field Values

QUERY_SCHEDULED

static final int QUERY_SCHEDULED

Status in which the query has been placed on the queue in preparation for being executed.

See Also:

Constant Field Values

QUERY_NEEDS_CONFIRMATION

static final int QUERY_NEEDS_CONFIRMATION

Status in which the query has been paused for user input. The query may be paused if the predicted execution time exceeds the query limit. The user should be asked whether query execution should continue or be canceled. Detection of this status should be followed by a call to either continueQueryExecution or cancelQueryExecution.

See Also:

Constant Field Values

QUERY_EXECUTING

static final int QUERY_EXECUTING

Status in which the query is currently being run.

See Also:

Constant Field Values

QUERY_RESULTS_READY

static final int QUERY_RESULTS_READY

Status in which the query has successfully completed.

See Also:

Constant Field Values

QUERY_FAILED

static final int QUERY_FAILED

Status in which the query failed to complete its execution.

See Also:

Constant Field Values

QUERY_CANCELED

static final int QUERY_CANCELED

Status in which the query execution was canceled. A cancellation may be triggered by a user action or due to some system settings.

See Also:

Constant Field Values

QUERY_VALIDATING

static final int QUERY_VALIDATING

Status in which the parameters of the query are being validated.

See Also:

Constant Field Values

Method Detail

scheduleQueryExecution

void scheduleQueryExecution(boolean autoConfirm)
                            throws DataException

Places the query on the queue for execution

Parameters:

autoConfirm - true to automatically confirm the continuation of query execution; false to allow the user or client to continue or cancel query execution. If false, the status may move to QUERY_NEEDS_CONFIRMATION. In general, true should be used only for batch processing, such as printing and exporting.

Throws:

DataException

continueQueryExecution

void continueQueryExecution()
                            throws DataException

Continues execution of the query after confirmation was requested. This should be called when the status is at QUERY_NEEDS_CONFIRMATION and the user approves the execution of a long-running query.

Throws:

DataException

See Also:

QUERY_NEEDS_CONFIRMATION

cancelQueryExecution

void cancelQueryExecution()

Attempts to cancel the execution of this data source's query.

getStatus

int getStatus()

Returns the status of this AsyncDataSource's query.

Returns:

One of this class's constants beginning with QUERY_

fetchEstimate

void fetchEstimate()
                   throws DataException

Causes the estimated query running time to be synchronously computed.

Throws:

DataException

getEstimatedTimeToDataAvailability

int getEstimatedTimeToDataAvailability()
                                       throws DataException

Returns the number of milliseconds until this AsyncDataSource's query and all DataSources prior to it have completed executing. If this AsyncDataSource is not scheduled for execution, this will return the estimated time until all scheduled AsyncDataSources will be processed. Returns UNKNOWN_TIME if the estimated time for a scheduled AsyncDataSource has not yet been fetched.

Throws:

DataException

getEstimatedRunningTime

int getEstimatedRunningTime()
                            throws DataException

Returns the estimated length of time in milliseconds for the QUERY_EXECUTING state. Returns UNKNOWN_TIME if the estimated time for this AsyncDataSource has not yet been fetched.

Throws:

DataException

notifyListenersIfDataAvailable

void notifyListenersIfDataAvailable()
                                    throws DataException

Prepares this AsyncDataSource for proper rendering. This method should be called prior to accessing this AsyncDataSource's DataDirector and DataAccess; otherwise, data may not appear.

If the query has not changed since this method was last called, then this does nothing. Otherwise, this method updates the DataDirector and DataAccess with the latest query results and fires DataChangedEvents to registered DataDirectorListeners.

Throws:

DataException

isLinkedTo

boolean isLinkedTo(AsyncDataSource targetDataSource)

Determines if this DataSource and the targetDataSource are linked to the same query.

Returns:

true if two DataSources are linked

linkTo

boolean linkTo(AsyncDataSource targetDataSource)
               throws DataException

Makes this AsyncDataSource link to the targetDataSource.

Returns:

true if the linking is successful, false if they are already linked

Throws:

DataException - The targetDataSource and this data source can not be linked for some reason

getExecutionErrors

BIException[] getExecutionErrors()

Returns errors associated with the most recent query execution attempt. If the current status is QUERY_FAILED or QUERY_NEEDS_PARAMETERS, these errors explain why the query was unable to return results.

Returns:

errors associated with the most recent query execution attempt