Previous Topic  Next Topic

User Data Source API

The User Data Source (UDS) API enables Designer to access data from an external data source, such as a Text file or Excel file which is not stored in a database, or when there is no JDBC driver available. This topic provides a brief introduction to the UDS API and the interface of the UDS API. It also presents some examples about how you can use the UDS API.

This topic contains the following sections:

• Introduction to the UDS API
• UDS API Interface
• JDBC API Used by UDS
• Examples of Using the UDS API

Introduction to the UDS API

The User Data Source API, a Java interface that provides a dataset to Report, is a part of the Report Data Access Model as shown in the following diagram. It has a PARAMETER string, which you can change when adding the UDS object to Designer, so the result set may differ according to the PARAMETER string.

• PARAMETER here is the parameter string given to the UDS interface. That is, the UDS API provides the getResultSet (String strParam) method, and PARAMETER is the string strParam in this method. As a reminder, PARAMETER here is different from the parameter object in the catalog. To distinguish between them, an uppercase PARAMETER is used to refer to the parameter string in the UDS, and a lowercase parameter for the parameter object in a catalog.
• To design a report, Report Engine requires a metadata (see java.sql.ResultSetMetaData) which corresponds to the ResultSet that the data source has returned; to view or run a report, Report Engine requires a ResultSet object. The user data source must provide both of these two parts for Report Engine.

Back to top

UDS API Interface

To use the UDS API, you must implement the jet.datasource.JRUserDataSource interface, and the class definition may be as follows. For more information, see the jet.datasource.JRUserDataSource class in the Report Java API Documentation.

import jet.datasource.*;
public class UserUDS 
    implements JRUserDataSource
{
    // Class body.
} 

This interface contains the following two methods:

• Public java.sql.ResultSet getResultSet(String strParam) throws JRUserDataSourceException
  You can use this method to get the result set for your data source, and return java.sql.ResultSet which is a row and column dataset that you can use in Report. The method throws JRUserDataSourceException, if a database access error occurs.

  This method has one parameter, strParam. It is a String value used to request and get different result sets. The format of the PARAMETER string is defined and parsed by your Java class. You can specify the PARAMETER string when you add the UDS to a catalog. If you want to use parameters predefined in the catalog, you can reference them as @ParameterName in the PARAMETER string.

  The following are the parsing rules for the PARAMETER string:

  • You can use any character defined on the keyboard in the parameter name, except for quotation marks.
  • You should introduce the parameter name with "@", and sometimes Designer can also recognize colon ":" as an introducer.
  • When the PARAMETER string contains characters such as: At sign (@), ':', double quotation mark ('"'), or other strings that Report does not need to parse, you can use a pair of double quotation marks to quote them. For example, your PARAMETER string may be:

    jdbc:oracle:thin:@204.177.148.30:1521:orcl

    Here, "@" is a character used by the URL. If you add this PARAMETER string for a UDS in a catalog, Report regards 204 as the name of a parameter in the catalog. The correct form is:

    "jdbc:oracle:thin:@204.177.148.30:1521:orcl"

  When you provide a java.sql.ResultSet instance, to reduce your work, you do not need to implement all methods of java.sql.ResultSet. You can just extend abstract class jet.datasource.JRResultSet. If you specify the column properties, for example, SQL data type and precision, you do not need to provide a ResultSetMetaData instance, and Report does not invoke the getMetaData() function of ResultSet. However, if you do not specify the properties, you need to implement the getMetaData() function and provide a ResultSetMetaData instance.

• Public void releaseResultSet() throws JRUserDataSourceException
  You can use this method to free the ResultSet object. The method throws JRUserDataSourceException, if there are some errors when freeing the resource.

Back to top

JDBC API Used by UDS

In order to get data from user-defined data source, Report needs to invoke the following JDBC API (for more information about the API, go to java.sun.com/javase/6/docs/api/).

java.sql.ResultSet

• boolean next() throws SQLException
• void close() throws SQLException
• boolean wasNull() throws SQLException
• String getString(int columnIndex) throws SQLException
• boolean getBoolean(int columnIndex) throws SQLException
• byte getByte(int columnIndex) throws SQLException
• short getShort(int columnIndex) throws SQLException
• int getInt(int columnIndex) throws SQLException
• long getLong(int columnIndex) throws SQLException
• float getFloat(int columnIndex) throws SQLException
• double getDouble(int columnIndex) throws SQLException
• byte[] getBytes(int columnIndex) throws SQLException
• java.sql.Date getDate(int columnIndex) throws SQLException
• java.sql.Time getTime(int columnIndex) throws SQLException
• java.sql.Timestamp getTimestamp(int columnIndex) throws SQLException
• java.io.InputStream getAsciiStream(int columnIndex) throws SQLException
• java.io.InputStream getBinaryStream(int columnIndex) throws SQLException
• ResultSetMetaData getMetaData() throws SQLException
• Object getObject(int columnIndex) throws SQLException
• int findColumn(String columnLabel) throws SQLException
• BigDecimal getBigDecimal(int columnIndex) throws SQLException
• Blob getBlob(int columnIndex) throws SQLException
• Clob getClob(int columnIndex) throws SQLException

java.sql.ResultSetMetaData

• int getColumnCount() throws SQLException
• boolean isCurrency(int column) throws SQLException
• int isNullable(int column) throws SQLException
• int getColumnDisplaySize(int column) throws SQLException
• String getColumnLabel(int column) throws SQLException
• String getColumnName(int column) throws SQLException
• String getSchemaName(int column) throws SQLException
• int getPrecision(int column) throws SQLException
• int getScale(int column) throws SQLException
• String getTableName(int column) throws SQLException
• int getColumnType(int column) throws SQLException

Report invokes the ResultSetMetaData getMetaData() throws SQLException method when you do not select the Specify Columns checkbox in the New User Defined Data Source dialog box.

Back to top

Examples of Using the UDS API

The UDS API is flexible and convenient. Before you implement it, you should first make an overall consideration of the architecture. Designer provides you with several scenarios which use the UDS API. You can refer to them for assistance.

• When there is no JDBC driver available for an external data source (for example, a comma-delimited text file), you can create a ResultSet object to return the data to the requesting report. See Example 1: Adding a Flat File UDS.
• You can return a ResultSet through the JDBC API. See Example 2: Adding an SQL Data Source UDS.
• Oracle Stored Procedure UDS.
• EnterpriseDB Stored Procedure UDS.

Back to top

Previous Topic  Next Topic