
IE4/MSHTML supports a very simple, easily implemented API for exposing data to HTML pages. The API supports access to string and variant data types and is built using array-like structures to expose rows and columns. Third parties can use the OLE-DB Simple Provider API to implement their custom data source objects.
OLE-DB Simple Provider Listener
OLE-DB Simple Provider (OSP) is a JavaBeans interface specification that hosts may implement to expose their tabular data to HTML elements in IE4/MSHTML. OSP specifies only simple, minimal functionality that requires only minimal effort on the part of applet authors to expose their data. OSP specifies methods for adding, deleting, and setting the value of columns, searching through the set of data, and receiving notifications on data events.
OSP exposes a set of tabular data (data set) in an array-like structure. Elements of the data set are referenced by their row and column indices.
Data References
Indices begin with value 1 and increase. There are two
special index values:
OSP defines two distinct interfaces: OLEDBSimpleProvider and OLEDBSimpleProviderListener. As you would expect, OLEDBSimpleProvider implements the methods used for data access and OLEDBSimpleProviderListener specifies the methods to be implemented by the host for receiving notification of data changes.
Schema functions
Three functions are provided for obtaining the schema for
the underlying rows or columns.
OSPRW is an interface that defines the following return values:
public interface OSPRW
{
public static final int OSPRW_DEFAULT = 1;
public static final int OSPRW_READONLY = 0;
public static final int OSPRW_READWRITE = 1;
public static final int OSPRW_MIXED = 2;
}
| OSPRW_READONLY | cell, row, column, or data set is read-only |
| OSPRW_READWRITE OSPRW_DEFAULT |
cell, row, column, or data set can be modified |
| OSPRW_MIXED | cell, row, column, or data set read-write status unknown OR row, column or data set mixed status |
Variant-Oriented Functions
Two functions are provided to allow retrieval and setting
of variant values in the data set.
OSPFORMAT is an interface that defines the following values:
public interface OSPFORMAT
{
public static final int OSPFORMAT_RAW = 0;
public static final int OSPFORMAT_DEFAULT = 0;
public static final int OSPFORMAT_FORMATTED = 1;
public static final int OSPFORMAT_HTML = 2;
}
Definitions for the values are:
| OSPFORMAT_RAW OSPFORMAT_DEFAULT |
the underlying type of the column should be used to either set the value or get the value |
| OSPFORMAT_FORMATTED | the underlying type of the column should be converted to a string and the string returned as a BSTR within the variant |
| OSPFORMAT_HTML | the underlying type of the column should be converted to an HTML string. |
Deletion and Insertion:
Functions are provided to insert and delete rows. For all
functions, the row numbers provide the position within
the data set to which the row will be inserted. That is,
the row inserted will have the index specified.
Searching
A function is provided which supports some basic
searching capability on the data set. The goal of this
function is to be fairly easy for the provider to
implement while providing the client with a meaningful
set of functionality to perform complex searching.
The OSPFIND interface defines the values for the findFlags as follows:
public interface OSPFIND
{
public static final int OSPFIND_DEFAULT = 0;
public static final int OSPFIND_UP = 1;
public static final int OSPFIND_CASESENSITIVE = 2;
}
Definitions for the values are:
| OSPFIND_UP | Specifies scan should be decreasing in row number. |
| OSPFIND_CASESENSITIVE | Specifies that search should be case sensitive. |
Similarly, the OSPCOMP interface defines the values for compType:
public interface OSPCOMP
{
public static final int OSPCOMP_EQ = 1;
public static final int OSPCOMP_DEFAULT = 1;
public static final int OSPCOMP_LT = 2;
public static final int OSPCOMP_LE = 3;
public static final int OSPCOMP_GE = 4;
public static final int OSPCOMP_GT = 5;
public static final int OSPCOMP_NE = 6;
}
| OSPCOMP_LT | Specifies we are searching for the first value less than objVal |
| OSPCOMP_LE | Specifies we are searching for the first value less than or equal to objVal |
| OSPCOMP_GT | Specifies we are searching for the first value greater than objVal |
| OSPCOMP_GE | Specifies we are searching for the first value greater than or equal to objVal |
| OSPCOMP_EQ
OSPCOMP_DEFAULT |
Specifies we are searching for the first value equal to objVal |
| OSPCOMP_NE | Specifies we are searching for the first value not equal to objVal |
Asynchronous Data
Population
The main function of an OSP is to provide data to an HTML
page. In many cases, the data will need to be transported
over high-latency, low bandwidth networks, in most cases
using a 28.8K modem. The OSP design accounts for making
data available as expediently as possible while
maintaining an architecture and interface specification
that is easy to author.
All OSP authors are encouraged to implement support for populating (or retrieving) the data they expose asynchronously. This allows the host to continue processing during data transmission instead of blocking on a call to the OSP until the entire data set has been transmitted to the client.
The majority of the work required to support asynchronous data delivery does not involve the OSP interface specifically - it is a requirement on the mechanisms to retrieve data from their underlying storages. Accordingly, three methods are required in the OSP interface: one to indicate whether the provider supports asynchronous population; one to return the progress of the asynchronous population; and a third to stop the asynchronous transmission of data.
Two additional events are added to the OSP event notifications. One event indicates when additional data has become available for access through the interface while the other signals that the asynchronous data population has completed. Both events are specified below in the OLE-DB Simple Provider Listener section.
Internationalization
Implementers may have to consider cases where the
consumer is running in a different locale from the source
of the data. The provider is responsible for ensuring
that data conversions are done in an appropriate fashion.
In particular be careful in cases where the string
representation of many data types differs according to
locale. For example, the float or double number 3.14
would be "3.14" in the US, and "3,14"
in Germany. Date representations differ even more. For
example, number (especially float, date) to string
conversions done by GetVariant or SetVariant with the OSP_FORMATTED option
specified should usually be done in the locale of the
browser.
The Find method has more complicated issues to deal with to implement its ordered comparisons correctly across locale boundaries. These comparisons should, where possible, also be done in the locale of the browser, although this issue is not as clear cut. (For example, if the data consists of strings containing European accented characters, it is not clear that a browser in the en-us locale has any preferred sorting order for these strings. The sorting order of the provider locale might be more useful.)
It is anticipated that there will be cases where the consumer will need to know the locale of the data in order to perform proper operations on that data. A method is provided for the provider to return this information.
Sinking Events
Methods are provided to attach and detach a unicast event
handler for all events.
OSP implementers fire notifications of changes to the underlying data through a single event handler. There are pre- and post- notifications for each event.
The event handler, registered through addOLEDBSimpleProviderListener(), should implement the following methods:
The OSPXFER interface defines values for the doneReason as follows:
public interface OSPXFER
{
public static final int OSPXFER_COMPLETE = 0;
public static final int OSPXFER_ABORT = 1;
public static final int OSPXFER_ERROR = 2;
}
| OSPXFER_COMPLETE | Indicates that the data transmission is completed successfully. |
| OSPXFER_ABORT | Indicates that the data transmission is completed due to a call to the Stop method. |
| OSPXFER_ERROR | Indicates that the data transmission completed in an error state. |
Notes for all events functions:
All interfaces are part of the com.ms.osp package. The interfaces are as follows:
public interface OLEDBSimpleProvider
{
public int getRowCount( ) throws OSPException;
public int getColumnCount( ) throws OSPException;
public int getRWStatus(int iRow, int iColumn) throws OSPException;
public Object getVariant(int iRow, int iColumn, int fFormatted) throws OSPException;
public void setVariant(int iRow, int iColumn, int fFormatted, Object obj) throws OSPException;
public int deleteRows(int iRow, int cRows) throws OSPException;
public int insertRows(int iRow, int cRows) throws OSPException;
public int find(int iRowStart, int iColumn, Object objVal, int findFlags, int compType) throws OSPException;
public boolean isAsync( ) throws OSPException;
public int getEstimatedRows( ) throws OSPException;
public void stopTransfer( ) throws OSPException;
public String getLocale( ) throws OSPException;
public void addOLEDBSimpleProviderListener(OLEDBSimpleProviderListener objOSPL) throws OSPException,
java.util.TooManyListenersException;
public void removeOLEDBSimpleProviderListener(OLEDBSimpleProviderListener objOSPL) throws OSPException;
}
abstract interface OLEDBSimpleProviderListener
{
public void aboutToChangeCell(int iRow, int iColumn) throws Exception;
public void cellChanged(int iRow, int iColumn) throws Exception;
public void aboutToDeleteRows(int iRow, int cRows) throws Exception;
public void deletedRows(int iRow, int cRows) throws Exception;
public void aboutToInsertRows(int iRow, int cRows) throws Exception;
public void insertedRows(int iRow, int cRows) throws Exception;
public void rowsAvailable(int iRow, int cRows) throws Exception;
public void transferComplete(int doneReason) throws Exception;
}
public interface OSPRW
{
public static final int OSPRW_DEFAULT = 1;
public static final int OSPRW_READONLY = 0;
public static final int OSPRW_READWRITE = 1;
public static final int OSPRW_MIXED = 2;
}
public interface OSPFORMAT
{
public static final int OSPFORMAT_RAW = 0;
public static final int OSPFORMAT_DEFAULT = 0;
public static final int OSPFORMAT_FORMATTED = 1;
public static final int OSPFORMAT_HTML = 2;
}
public interface OSPFIND
{
public static final int OSPFIND_DEFAULT = 0;
public static final int OSPFIND_UP = 1;
public static final int OSPFIND_CASESENSITIVE = 2;
}
public interface OSPCOMP
{
public static final int OSPCOMP_EQ = 1;
public static final int OSPCOMP_DEFAULT = 1;
public static final int OSPCOMP_LT = 2;
public static final int OSPCOMP_LE = 3;
public static final int OSPCOMP_GE = 4;
public static final int OSPCOMP_GT = 5;
public static final int OSPCOMP_NE = 6;
}
public interface OSPXFER
{
public static final int OSPXFER_COMPLETE = 0;
public static final int OSPXFER_ABORT = 1;
public static final int OSPXFER_ERROR = 2;
}
OSP supports a number of exceptions. They are defined as follows:
AccessDeniedException: An inability to read/write the data has occurred.
ConversionException: An error occurred attempting to coerce data types.
IllegalArgumentException: A method was passed an invalid or inappropriate argument of invoked on an inappropriate object.
NotImplementedException: The functionality of a called method is not implemented.
OSPException: A failure has occurred calling an OSP method. This is used in all cases not covered by the previous exceptions.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.