oracle.reports.plugin.datasource
Interface PluginDataSource

All Superinterfaces:

Plugin

All Known Implementing Classes:

PluginDataSourceTemplate

public interface PluginDataSource

extends Plugin

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

Version:

1.01 May 1 2000

Field Summary

static int

ALL_ROWS Requests all rows of the data source.

Method Summary

PluginResultSetMetaData	describe() Returns the 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 the result set.
java.lang.String	getQueryDescription() Returns the text description of the query, which usually contains the information of the source, columns, and bind variables.
java.lang.String[]	getReferencedColumns() Returns the names of the Reports columns whose values will be used in the Plugin Data Source's execution.
void	setDataSource(DataSource datasource) Sets the hosting Reports data source object of this Plugin Data Source.
void	setSignOnParameter(Parameter signOnParam) Sets the Sign-on Parameter of this Plugin Data Source.
boolean	supportCondition() Returns true or false, depending on whether the Plugin Data Source supports conditions.

Methods inherited from interface oracle.reports.plugin.Plugin

applyXML, dispose, getFactory, saveToXML, setFactory, startRuntime

Field Detail

ALL_ROWS

public static final int ALL_ROWS

Requests all rows of the data source. When Reports calls the Plugin Data Source's execute method and passes in parameter 'maxrow' as ALL_ROWS, this requests no limit on the maximum number of rows the Plugin Data Source can return. The Plugin Data Source should return all rows from the underlying data source.

Method Detail

setSignOnParameter

public void setSignOnParameter(Parameter signOnParam)
                        throws PluginException

Sets the Sign-on Parameter of this Plugin Data Source. Reports calls this method whenever the Plugin Data Source's Sign-on Parameter is set or 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 the Plugin Data Source and Sign-on Parameter are stored by Reports. The Plugin Data Source does not need to store the binding in its own XML definition (returned value of the 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 - The Sign-on Parameter of this Plugin Data Source.

getReferencedColumns

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

Returns the names of the Reports columns whose values will be used in the Plugin Data Source's execution. If the 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 the getReferencedColumns method. The value of referenced columns are then passed in via the "refedColVals" parameter to the execute method. For example, the "EMP" XML Plugin Data Source may use the value of the "DEPTNO" column in its master data source to determine the name of the XML data file of employees of each department. It should return { "DEPTNO" } from the getReferencedColumns method, and the value of the "DEPTNO" column will be then passed to its execute method.

Using getReferencedColumns enables the Plugin Data Source to access column values in its execute method, and enables Reports to know the dependencies of the Plugin Data Source. A Plugin Data Source (as well as other types of Reports Data Sources) 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 an error when users try to run this report.

Note the getReferencedColumns is called before Reports starts to run. That is, the 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 that depend on columns of each other), and determine the right sequence to process each object (say, a master query needs to be processed before the child query).

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.

getQueryDescription

public java.lang.String getQueryDescription()
                                     throws PluginException

Returns the text description of the query, which usually contains the information of the source, columns, and bind variables. The text description displays in a multi-line text box in the Reports Wizard Data page. Multiple text lines are seperated by '\n'. The text description is for informative use only.

setDataSource

public void setDataSource(DataSource datasource)
                   throws PluginException

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

Parameters:

datasource - The hosting data source object.

Returns:

void

describe

public PluginResultSetMetaData describe()
                                 throws PluginException

Returns the result set meta information of the data source. The meta information is used for Reports to determine the 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 necessary 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)

supportCondition

public boolean supportCondition()
                         throws PluginException

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

Returns:

true if the Plugin Data Source supports conditions, false if it does not.

execute

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

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