Smart Large Objects in a Client Application

On the client, your JDBC application can use ResultSet methods to access smart-large-object data, such as:

• getClob() and getAsciiStream() for CLOB data
• getBlob() and getBinaryStream() for BLOB data
• getString() for both CLOB and BLOB data

On the client side, the JDBC driver references the LO handle through an IfxLocator object. Your JDBC application obtains an instance of the IfxLocator class to contain the smart-large-object locator handle, as shown in Figure 4. Your application creates a smart large object independently and then inserts the smart large object into different columns, even in multiple tables. Using multiple threads, an application can write or read data from various portions of the smart large object in parallel, which is very efficient.

Figure 4. Locating a Smart Large Object In a Client Application

In IDS, support for Informix smart large object data types is available only with 9.x and later versions of the database server.

Steps for Creating Smart Large Objects

The Informix smart large object implementation is based on the following classes:

• IfxLobDescriptor stores attributes for the large object.
• IfxLocator contains the handle to the large object in the database server.
• IfxSmartBlob contains methods for working with the smart large object, such as positioning within the object, reading data from the object, and writing data to the object.
• IfxBblob and IfxCblob implement the java.sql.Blob and java.sql.Clob interfaces from the Sun Microsystems JDBC 3.0 specification.
• IfxLoStat stores status information about the large object.

Creating an IfxLobDescriptor Object

The IfxLobDescriptor class stores the internal storage characteristics for a smart large object. Before you can create a smart large object on the database server, you must create an IfxLobDescriptor object, as follows:

IfxLobDescriptor loDesc = new IfxLobDescriptor(conn);

The conn parameter is a java.sql.Connection object. The IfxLobDescriptor() constructor sets all the default values for the object.

For more information about the internal storage characteristics, see Working with Storage Characteristics.

Creating an IfxLocator Object

The IfxLocator object (usually known as the locator pointer or large object locator) identifies the location of the smart large object, as shown in Figure 4; the locator pointer is the communication link between the database server and the client for a particular large object. Before it creates a large object or opens a large object for reading or writing, an application must create an IfxLocator object:

IfxLocator loPtr = new IfxLocator();
IfxLocator loPtr = new IfxLocator(Connection conn);

Use the second of these constructors to display localized error messages if an exception is thrown. For more information, see Support for Localized Error Messages.

Creating an IfxSmartBlob Object

To create a smart large object and obtain access to the methods for performing operations on the object, call the IfxSmartBlob constructor, passing a reference to the JDBC connection:

IfxSmartBlob smb = new IfxSmartBlob(myConn)

Once you have written all the methods that perform operations you need in the smart large object, you can then use the IfxSmartBlob.IfxLoCreate() method to create the large object in the database server and open it for access within your application. The method signature is as follows:

public int  IfxLoCreate(IfxLobDescriptor loDesc, int flag, 
   IfxLocator loPtr) throws SQLException
public int  IfxLoCreate(IfxLobDescriptor loDesc, int flag, 
   IfxBblob blob)throws SQLException
public int  IfxLoCreate(IfxLobDescriptor loDesc, int flag, 
   IfxCblob clob throws SQLException

The return value is the locator handle, which you can use in subsequent read, write, seek, and close methods (you can pass it as the locator file descriptor (lofd) parameter to the methods that operate on open smart large objects; these methods are described beginning with Positioning Within a Smart Large Object).

The flag parameter is an integer value that specifies the access mode in which the new smart large object is opened in the server. The access mode determines which read and write operations are valid on the open smart large object. If you do not specify a value, the object is opened in read-only mode.

Use the access mode flag values in the following table with the IfxLoCreate() and IfxLoOpen() methods to open or create smart large objects with specific access modes.

The following example shows how to use a LO_RDWR flag value:

IfxSmartBlob smb = new IfxSmartBlob(myConn);
int loFd = smb.IfxLoCreate(loDesc, smb.LO_RDWR, loPtr);

The loDesc and loPtr objects are previously created IfxLobDescriptor and IfxLocator objects, respectively.

The database server uses the following system defaults when it opens a smart large object.

Open-Mode Information

Default Open Mode

Access mode

Read-only

Access method

Random

Buffering

Buffered access

Locking

Whole-object locks

For more information on locking, see Working with Locks.

The following table provides the full set of open-mode flags:

Open-Mode Flag

Description

LO_APPEND

Appends data you write to the end of the smart large object

By itself, it is equivalent to write-only mode followed by a seek to the end of the smart large object. Read operations fail.

When you open a smart large object in write/append mode only, the smart large object is opened in write-only mode. Seek operations move the seek position, but read operations to the smart large object fail, and the seek position remains unchanged from its position just before the write. Write operations occur at the seek position, and then the seek position is moved.

LO_WRONLY

Allows write operations only

LO_RDONLY

Allows read operations only

LO_RDWR

Allows read and write operations

LO_DIRTY_READ

For open only

Allows you to read uncommitted data pages for the smart large object

You cannot write to a smart large object after you set the mode to LO_DIRTY_READ. When you set this flag, you reset the current transaction isolation mode to Dirty Read for the smart large object.

Do not base updates on data that you obtain from a smart large object in Dirty Read mode.

LO_RANDOM

Overrides optimizer decision

Indicates that I/O is random and that the database server should not read ahead. Default open mode.

LO_SEQUENTIAL

Overrides optimizer decision

Indicates that reads are sequential in either forward or reverse direction.

LO_FORWARD

Used only for sequential access to indicate forward direction

LO_REVERSE

Used only for sequential access to indicate reverse direction

LO_BUFFER

Use standard database server buffer pool.

LO_NOBUFFER

Do not use the standard database server buffer pool. Use private buffers from the session pool of the database server.

LO_NODIRTY_READ

Do not allow dirty reads on smart large object. See LO_DIRTY_READ flag for more information.

LO_LOCKALL

Specifies that locking will occur on entire smart large object

LO_LOCKRANGE

Specifies that locking will occur for a range of bytes

You specify the range of bytes through the IfxSmartBlob.IfxLoLock() method when you place the lock.

Inserting a Smart Large Object into a Column

After creating a smart large object, you must insert it into a BLOB or CLOB column to save it in the database. To do this, you must convert the IfxLocator object to an IfxBblob or IfxCblob object, depending upon the column type.

Steps for Accessing Smart Large Objects

Follow these steps to use the Informix extensions to select a smart large object from a database column.

Standard JDBC ResultSet methods such as ResultSet.getBinaryStream(), getAsciiStream(), getString(), getBytes(), getBlob(), and getClob() can fetch BLOB or CLOB data from a table. The Informix extension classes can then access the data.