JBoss.orgCommunity Documentation
This chapter examines how to use facilities provided by the Teiid Connector API to use large objects such as blobs, clobs, and xml in your connector.
Teiid supports three large object runtime data types: blob, clob, and xml. A blob is a “binary large object”, a clob is a “character large object”, and “xml” is a “xml document”. Columns modeled as a blob, clob, or xml are treated similarly by the connector framework to support memory-safe streaming.
Teiid allows a Connector to return a large object through the Teiid Connector API by just returning a reference to the actual large object. Access to that LOB will be streamed as appropriate rather than retrieved all at once. This is useful for several reasons:
Reduces memory usage when returning the result set to the user.
Improves performance by passing less data in the result set.
Allows access to large objects when needed rather than assuming that users will always use the large object data.
Allows the passing of arbitrarily large data values.
However, these benefits can only truly be gained if the Connector itself does not materialize an entire large object all at once. For example, the Java JDBC API supports a streaming interface for blob and clob data.
The Connector API automatically handles large objects (Blob/Clob/SQLXML) through the creation of special purpose wrapper objects when it retrieves results.
Once the wrapped object is returned, the streaming of LOB is automatically supported. These LOB objects then can for example appear in client results, in user defined functions, or sent to other connectors.
A connector execution is usually closed and the underlying connection is either closed/released as soon as all rows for that execution have been retrieved. However, LOB objects may need to be read after their initial retrieval of results. When LOBs are detected the default closing behavior is prevented by setting a flag on the ExecutionContext.
Now the connector execution only when the user Statement object is closed. Note that connectors may at their discretion have executions delayed in their closure by directly setting the keep alive on the ExecutionContext
executionContext.keepExecutionAlive(true);
An important limitation of using the LOB type objects is that streaming is not supported from remote connectors. This is an issue in clustered environments if connectors intended to return LOBs are deployed on only a subset of the hosts or in failover situations. The most appropriate workaround to this limitation is to deploy connectors intended to return LOBs on each host in the cluster.