2. Where to start

This section tells you about classes and how they can be implemented to create your own data source. It uses the Text Pluggable Data Source (Text PDS) as an example. To see the complete list of classes, see the section Text PDS overview.

To create your data source you need to implement

1. a PluginDataSourceFactory class
2. a PluginResultSetMetaData class
3. a ResultSet class
4. a PluginDataSource class
5. a User Interface class

Note: Java API for all the above classes is available in the Javadocs zip file.

2.1 Implementing the PluginDatasourceFactory class

Factory class:

Every PDS needs a factory class to launch itself. This class is loaded when the Reports is being launched. Use this class to set some important static properties of your PDS with Reports.

To write your PluginDatasourceFactory, create a Factory class which can either
(i)  implement oracle.reports.plugin.datasource.PluginDataSourceFactory,
or
(ii) extend the template class, oracle.reports.plugin.datasource.PluginDataSourceFactoryTemplate

The data source factory contains the following information:

• name: The name of the data source that appears in the list of available data sources in the Report Wizard and Data Wizard. This name also displays as the tooltip of your Data Source button in the Data Model view. To set the value, use the setName() method.
• icon name: The name of the icon you wish to represent your new data source. This icon displays in the list of available data sources and in the toolbar of the Data Model view. For more details, see the section "How to Add Icons for Your PDS". To set the value, use the setIconName() method.
• hint text: The text that appears in the Data Model view status bar, when the user's mouse rolls over the Data Source icon. To set the value, use the setHint() method.
• data source class: The name (string) of the data source; which implements the PluginDataSource interface. To set the value, use the setPluginClass() method.
• user interface class: The name (string) of the data source; which implements PluginEditor interface. To set the value, use the setEditorClass() method.
• major version: The primary version number of the data source (e.g., "9" in "9.1"). To set the value use the setMajorVersion() method.
• minor version: The secondary version number of the data source (e.g., "1" in "9.1"). To set the value, use the setMinorVersion() method.
• help set id: Refer to the section "How to Configure Help for PDS". To set the value, use the setHelpSetId() method.

To set these values in the data source factory, simply call the above methods in the constructor.

The most important methods in the PluginDataSourceFactory interface are :

1. dispose()

Dispose the Plugin Factory and clean up related resources.

2. You can also write a Plugin Data Source that supports the Sign On parameter. Note that this parameter is not used with the text pluggable data source.

2A. needSignOnParameter()

Indicates whether your PDS supports the usage of sign-on parameters. Sign On parameters (same as User parameters) can be associated with your PDS at design time, and their values can be passed at runtime.

2B. getDefaultSignOnParameter()

Returns the name of the default sign-on parameter used by your PDS. This method is used by Oracle9i Reports to automatically create a parameter that is associated with your query.

2C. raiseConnectDialog(Parameter signOnParam)

Sets the Sign On parameter during design time. At runtime, you use a command line parameter to send the sign-on information. You need to write a Java frame and modify the signOnParam value in this frame. This method is called from the Data Model view, when the user right-clicks the query name and chooses Edit Connection from the pop-up menu.

2.2 Implementing a PluginResultSetMetaData

To describe the data of your data source, report needs a java.sql.ResulSetMetaData instance.

To write your own ResultSetMetaData class, create a class which
(i)  implements oracle.reports.plugin.PluginResultSetMetaData
or
(ii) extends the template class oracle.reports.plugin.PluginResultSetMetaDataTemplate

The PluginResultSetMetaData extends the java.sql.ResulSetMetaData to add some Reports specific value to manage the sorf. All record information comes from the XML (throught the Java Bean) that is described the data source, like number of columns, name and type of each columns.

The most important methods that you need to implement :

Returns the name of a specific column, based on the index. It is the name of the column that is used by Oracle9i Reports to describe the column in the Data Model view and the field in the Paper Layout view.

2.3 Implementing a ResultSet

Reports uses a ResultSet to read the records of a query. You need to implement a java.sql.ResultSet in your data source to loop on each record and get the value of each columns.

The methods that Oracle9i Reports uses are :

1. next()

Moves the cursor down one row from its current position, and return false when the curson reach the last row.

In the Text PDS example, we use the next method to call the readLine() method.

2. getObject(int columnIndex)

Called by Oracle9i Reports for each row and each column of the query, and return an Object. Oracle9i Reports uses the ResultSetMetaData class to get the information of the column. This method should return an object of the class that the meta data expects.

2.4 Implementing the PluginDataSource class

The PluginDataSource class is used to execute the following important operations in a data source query:

• store and retrieve the query definition in the report
• describe the query
• execute the query and fetch the records

To write your PluginDataSource, create a DataSource class which can either:
(i)  implement oracle.reports.plugin.datasource.PluginDataSource,
or
(ii) extend the template class, oracle.reports.plugin.datasource.PluginDataSourceTemplate

Note:

When a user creates a report, he starts by defining a query for a specific data source. This query is stored in the report definition as an XML structure. When the report is re-opened or executed, the XML query definition is parsed and used by the data source. You need to write these two operations in the Data Source class in the saveToXML() method to store the definition in the report, and applyXML() to retrieve it.

If you want to see the XML description of a query, just open a report saved as JSP or XML in a text editor.

In the following Text PDS example, the saveToXML methods return a String that contains file names and the descriptions of each column.

 <![CDATA[<textFilePDS 

DTDVersion="1.0"> <DataSource>file:///D:/Oracle/Apache/logs/access_log</DataSource> 
<DataDefinition>Apache Log File</DataDefinition> <select>    
<element name = "Remote Host" type = "string"/>    <element 
name = "Remote Log Name" type = "string"/>    <element name = 
"Remote User" type = "string"/>    <element name = "time" type 
= "date" cellWrapper = "\[]" pattern = "dd/MMM/yyyy:hh:mm:ss zzz"/>    
<element name = "Request" type = "string" cellWrapper = "&quot;"/>    
<element name = "status" type = "number"/>    <element name 
= "bytes" type = "number"/> </select> <ReferenceParameter></ReferenceParameter> 
</textFilePDS> 

The most important methods of the PluginDataSource interface are:

1. saveToXML()

Called by Oracle9i Reports when it saves the query description in the report definition. You need to override this method to build an XML string that describe your query.

The easy way to do that, is to create a simple Java bean that contains the query description and write a method to save all information as an XML string. In the Text PDS example, the Java bean that is used to manage the query definition and the XML is: TextSerializedXml

2. applyXML(String xml)

Called when a report is opened by Reports Builder or at runtime to retrieve the query description. You override this method to parse the query definition and get all information, and store those information in a Java Bean. In the Text PDS example, the bean that is used to manage the query definition and the XML is: TextSerializedXml

3. getQueryDescription()

Called by Oracle9i Reports to show the text description of the query in the Data Wizard. (see Figure 3.1)

The description generally contains the information of the source (name, version) the columns and reference parameters.

Figure 3.1: The string returned by the getQueryDescription() method for the Text PDS

4. getReferencedColumns():

Returns the list of the parameters supported by the query. You can use this method to parse the url to get the user parameters. At run-time the plugin, ensures that the runtime values for these referenced columns will be provided in execute() method.
    public ResultSet execute(Object[] referenceColumnValues, PluginCondition[] RCondition, int maxrows) throws PluginException
 
 

5. describe()

Creates and returns an instance of the ResultSetMetaData of your data source.

The describe method is used by Oracle9i Reports to create the groups in the Data Model and to show the list of the columns with type and size.

6. execute(java.lang.Object[] refedColVals,PluginCondition[] conds,int maxrows)

Creates and returns a ResultSet object to Oracle9i Reports. This method is called by Oracle9i Reports during the execution.

2.4 Implementing the PDS User Interface

The Plugin Editor is used to provide a graphical interface to edit the data source. For example, in the Text PDS example, the UI is used to specify the format and the name of the files.

To write your Plugin Editor, create a user interface which can either :
(i)  implement oracle.reports.plugin.PluginEditor
or
(ii) extend the template class oracle.reports.plugin.PluginEditorTemplate

The most important method is:

1. edit (Plugin plugin)

Called when the user clicks on the Data Source icon in the Data Model view, or clicks on the Query Description in the Data Wizard or Report Wizard.The Plugin instance is made available to this method as a paramete and is the current instance of the PluginDataSource.

This method is used to populate the information needed to create the data source. If you created a Java Bean, you can set all properties here.

The edit() method returns a boolean value, true if the user validates the data. The XML description will be saved by Oracle9i Reports. If the method returns false, nothing happens.

2.6. Phases of PDS and method call sequence

The following is the order in which the PDS methods are called by Oracle9i Reports. PDS execution can be divided into these three conceptual phases:

1. Initialization (startup of the server or the builder)
2. Design time
3. Runtime