oracle.reports.plugin.datasource
Interface PluginDataSource

All Superinterfaces:

Plugin

All Known Implementing Classes:

PluginDataSourceTemplate

public interface PluginDataSource
extends Plugin

Reports Plugin Data Source Interface allows application developers to write their own Java components to provide data from arbitrary sources to be used in the reports. For example, one application developer can write Excel Plugin Data Source to provide data in Excel files for reporting. Plugin Data Source interface is based on JDBC API, in the sense that JDBC ResultSet and ResultSetMetaData are used for fetching data and describing meta information. Most JDBC v1 datatypes (as defined in java.sql.Types) are supported by the interface. Besides JDBC datatypes, the interface also support Oracle CHAR, DATE, and NUMBER. See PluginTypes for details of supported types.

Version:

1.01 May 1 2000

Field Summary

static int

ALL_ROWS Asking for all rows of the data source.

Method Summary

PluginResultSetMetaData	describe() Returns result set meta information of the data source.
java.sql.ResultSet	execute(java.lang.Object[] refedColVals, PluginCondition[] conds, int maxrows) Executes the Plugin Data Source and returns result set.
java.lang.String	getQueryDescription() Gets text description of the query, which usually contains the information of the source, columns, and bind variables.
java.lang.String[]	getReferencedColumns() Gets the names of the Reports columns whose values will be used in Plugin Data Source's execution.
void	setDataSource(DataSource datasource) Set the hosting Reports data source object of this Plugin Data Source.
void	setSignOnParameter(Parameter signOnParam) Sets sign on parameter of this Plugin Data Source.
boolean	supportCondition() Returns true or false, whether the Plugin Data Source supports condition.

Methods inherited from interface oracle.reports.plugin.Plugin

applyXML, dispose, getFactory, saveToXML, setFactory, startRuntime

Field Detail

ALL_ROWS

static final int ALL_ROWS

Asking for all rows of the data source. When Reports calls Plugin Data Source's execute method and passes in parametre 'maxrow' as ALL_ROWS, it means Reports asking for no limit of maximum number of rows the Plugin Data Source can return. Plugin Data Source should return all rows from the underlying data source.

See Also:

Constant Field Values

Method Detail

setSignOnParameter

void setSignOnParameter(Parameter signOnParam)
                        throws PluginException

Sets sign on parameter of this Plugin Data Source. Reports calls this method whenever Plugin Data Source's sign-on parameter is set ot changed. Reports also calls this method when a Plugin Data Source is re-created from a saved report to restore sign-on parameter information. That is, the bindings of Plugin Data Source and sign-on parameter are stored by Reports. Plugin Data source does not need to store the binding in its own XML definition (returned value of saveToXML method). The call sequence of restoring a Plugin Data Source from a saved report is as follows: 1. PluginDataSource() // default constructor 2. setSignOnParameter(signOnParam) // restore sign-on parameter binding 3. applyXML(definitionXml) // restore Plugin Data source's own definition

Parameters:

signOnParam - sign on parameter of this Plugin Data Source

Throws:

PluginException

getReferencedColumns

java.lang.String[] getReferencedColumns()
                                        throws PluginException

Gets the names of the Reports columns whose values will be used in Plugin Data Source's execution. For example, An XML Plugin Data Source may use the values of the columns in another query to determine the name or location of data source XML file. This is the method for Reports to know the dependencies of Plugin Data Source. A Plugin Data Source (as well as other types of Reports Data Source) can only reference columns in its master data sources, report level columns, and parameters. If a Plugin Data Source references a column in its child query or an unrelated query, Reports will raise error when users try to run this report. If getReferencedColumns returns a name of non-existing column, Reports will create a new user parameter of that name, and default its datatype as character. If Plugin Data Source's execution requires the values of Reports columns outside of itself (such as parameters, Report level columns, or columns of other data sources), the list of required columns needs to be returned by getReferencedColumns method. The value of referenced columns are then passed in as "refedColVals" parameter to execute method. Note getReferencedColumns is called before Reports starts to run. That is, Plugin Data Source's dependency needs to be determined before Reports starts to run. Reports needs to know such depedencies before runtime, so that it can detect if any circular dependency between different objects (say, two data sources depend on columns of each other), and determine the right sequence to process each object (say, master query needs to be processed before the child query).is called before Reports starts to run. That is, Plugin Data Source's dependency needs to be determined before Reports starts to run. Reports needs to know such depedencies before runtime, so that it can detect if any circular dependency between different objects (say, two data sources depend on columns of each other), and determine the right sequence to process each object (say, master query needs to be processed before the child query).

Returns:

names of referenced Reports columns

Throws:

PluginException

getQueryDescription

java.lang.String getQueryDescription()
                                     throws PluginException

Gets text description of the query, which usually contains the information of the source, columns, and bind variables. The text description is used to display in a multi-line text box in Reports Wizard Data tab. Multiple text lines are seperated by '\n'. The tex description is informative use only.

Returns:

query description text

Throws:

PluginException

setDataSource

void setDataSource(DataSource datasource)
                   throws PluginException

Set the hosting Reports data source object of this Plugin Data Source. Reports calls this method right after a Plugin Data Source object is created. Plugin data source can calls DataSource.getReport() to get the report object, which contains Reports context information such as NLS settings, or command line parameters. Report object is also the root object to navigate the objects in the report, such as data sources, groups, or columns.

Parameters:

datasource - the hosting data source object

Throws:

PluginException

describe

PluginResultSetMetaData describe()
                                 throws PluginException

Returns result set meta information of the data source. The meta information is used for Reports to know what data items in the data source, so that Reports can create Reports columns for each data item accordingly. The following methods of JDBC ResultSetMedata or IPluginResultSetMetaData are called by Reports for necessay meta information:

  getColumnCount
  getColumnDisplaySize(int columnIndex)
  getColumnLabel(int columnIndex)
  getColumnName(int columnIndex)
  getColumnType(int columnIndex)
  getPrecision(int columnIndex)
  getScale(int columnIndex)
  getSortOrder(int columnIndex)
  sortColumnOf(int columnIndex)
 

Returns:

result set meta data

Throws:

PluginException

supportCondition

boolean supportCondition()
                         throws PluginException

Returns true or false, whether the Plugin Data Source supports condition. Condition, like WHERE clause in SQL, imposes the restriction the data item values returned in the result set. Conditions are specified by column links in Reports Builder. See oracle.reports.plugin.PluginCondition for definition of condition object. If a Plugin Data Source supports condition, Reports will pass the conditions required by column links on the data source when calling execute method. The Plugin Data Source must return the result set which meets the conditions. Note, for Plugin Data Sources which do not support condition, Reports will not pass in conditions when calling execute method, and Reports will do the filtering on the data returned in the result set to meet the conditions required by the column links. If the application developers who write the Plugin Data Source think this type Plugin Data Source can do data filtering in more effective way than Reports does, they should let the Plugin Data Source support. A typical example of this is JDBC Plugin Data Source. JDBC Plugin Data Source can translate the condition into "WHERE" clause, and insert it to the SQL statement passed to Database server for server side data filtering, which is usually fast and reduce the amount of data passed through network.

Returns:

true if the plugin datasource supports condition, flase otherwise.

Throws:

PluginException

execute

java.sql.ResultSet execute(java.lang.Object[] refedColVals,
                           PluginCondition[] conds,
                           int maxrows)
                           throws PluginException

Executes the Plugin Data Source and returns result set. Reports uses the returned result set to fetch data from Plugin Data Source. Reports only fetches rows sequencially from result set, that is Reports only calls next method and get value methods of supported datatypes. Reports will call result set's close method after it fetcthes all rows from the result set. Note execute method could be called more than one time for one Plugin Data Source during one report execution. For example, if Plugin Data Source "EMP" (employee data) is used as child data source of "DEPT" data source. For each record of master data source "DEPT", "EMP" data source's execute method is called. When Reports is done with the returned Result Set, ResultSet.close method is called.

Parameters:

refedColVals - values of the referenced Reports columns as given by getReferencedColumns method. See getReferencedColumns for details.

conds - conditions imposed on the result set required by column links. See supportCondition method for details.

maxrows - maximum number of rows the result set should return. ALL_ROWS means no limit.

Returns:

Result Set, please check PluginResultSetTemplate for example

Throws:

PluginException