com.informix.jdbc
Class IfxCblob

java.lang.Object
  extended bycom.informix.jdbc.IfxLob
      extended bycom.informix.jdbc.IfxCblob
All Implemented Interfaces:
java.sql.Clob

public class IfxCblob
extends com.informix.jdbc.IfxLob
implements java.sql.Clob

By default, a CLOB is a transaction duration reference to a character large object.


Constructor Summary
IfxCblob()
          Creates an IfxCblob instance.
IfxCblob(java.sql.Connection c, byte[] buffer)
          Creates an IfxCblob instance with the given connection and a buffer containing data.
IfxCblob(java.sql.Connection conn, java.io.InputStream fin, int length)
          Creates an IfxCblob instance with a given connection, an inputStream and number of bytes to write.
IfxCblob(java.sql.Connection conn, java.io.InputStream fin, int length, IfxLobDescriptor loDesc)
          Creates an IfxCblob instance with a given connection, an inputStream, number of bytes to write and a specified lob descriptor.
IfxCblob(java.sql.Connection conn, java.io.InputStream fin, int length, java.lang.String sbspaceName)
          Creates an IfxCblob instance with a given connection, an inputStream and number of bytes to write to a specified smart blob space.
IfxCblob(java.sql.Connection conn, java.lang.String str)
          Creates an IfxCblob instance with a given connection and a string of data.
IfxCblob(java.sql.Connection conn, java.lang.String str, IfxLobDescriptor loDesc)
          Creates an IfxCblob instance with a given connection and a string of data and a specified lob descriptor.
IfxCblob(java.sql.Connection conn, java.lang.String str, java.lang.String sbspaceName)
          Creates an IfxCblob instance with a given connection and a string of data and a specified smart blob space.
IfxCblob(com.informix.jdbc.IfxConnection connection, IfxLocator locator)
          Creates an IfxCblob instance with a given connection and a locator.
IfxCblob(com.informix.jdbc.IfxConnection connection, IfxLocator locator, int mode)
          Creates an IfxCblob instance with a given connection and a locator.
IfxCblob(IfxLocator locator)
          Creates an IfxCblob instance with the given locator.
IfxCblob(java.io.InputStream fin)
          Creates an IfxCblob instance with the given input stream.
 
Method Summary
 void close()
          This method will release the resources used by the object.
 java.io.InputStream getAsciiStream()
          Gets the smart large object contents as an ASCII stream.
 java.io.Reader getCharacterStream()
          Gets the smart large object contents as a Unicode stream.
 IfxLocator getLocator()
          Gets the smart large object locator from the clob object.
 IfxLoStat getLoStat()
          This method returns an IfxLoStat object, which provides statistical information, such as the last access time, the last update status time, the last modification time, and the reference count of the smart large object.
 java.lang.String getSubString(long position, int length)
          Returns a copy of the substring of the smart large object at the requested position.
 long length()
          Gets the length of the character smart large object in characters.
 long position(java.sql.Clob searchstr, long start)
          Determines the character position at which the given substring occurs.
 long position(java.lang.String searchstr, long start)
          Determines the character position at which the given substring occurs.
 long seek(long offset, int whence)
          This method sets the position for the next read and write operation of the smart large object.
 java.io.OutputStream setAsciiStream(long pos)
          Retrieves a stream to be used to write Ascii characters to the CLOB value that this Clob object represents, starting at position pos.
 void setAsciiStream(long position, java.io.InputStream fin, int length)
          Writes ascii stream of data from an InputStream to an already existing smart large blob object.
 java.io.Writer setCharacterStream(long pos)
          Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this Clob object represents, at position pos.
 int setString(long pos, java.lang.String str)
          Writes the given Java String to the CLOB value that this Clob object designates at the position pos.
 int setString(long pos, java.lang.String str, int offset, int len)
          Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.
 void setSubString(long position, java.lang.String str, int length)
          Writes data from a string to an already existing smart large blob object.
 void truncate(long size)
          This method truncates the smart large object at the given position.
 long where()
          This method returns the current seek position within the large object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IfxCblob

public IfxCblob()
Creates an IfxCblob instance. An IfxCblob object created using this constructor cannot be used for accessing the Clob.


IfxCblob

public IfxCblob(IfxLocator locator)
Creates an IfxCblob instance with the given locator. An IfxCblob object created using this constructor cannot be used for accessing the Clob.

Parameters:
locator - The locator that references the smart large object

IfxCblob

public IfxCblob(com.informix.jdbc.IfxConnection connection,
                IfxLocator locator,
                int mode)
         throws java.sql.SQLException
Creates an IfxCblob instance with a given connection and a locator. The object will be opened in the database using the given mode.

Parameters:
connection - The IfxConnection object
locator - The locator that references the smart large object

IfxCblob

public IfxCblob(com.informix.jdbc.IfxConnection connection,
                IfxLocator locator)
         throws java.sql.SQLException
Creates an IfxCblob instance with a given connection and a locator. The object will be opened in the database in RDWR mode.

Parameters:
connection - The IfxConnection object
locator - The locator that references the smart large object

IfxCblob

public IfxCblob(java.sql.Connection c,
                byte[] buffer)
         throws java.sql.SQLException
Creates an IfxCblob instance with the given connection and a buffer containing data.

Parameters:
buffer - the data buffer
Throws:
java.sql.SQLException - if object instance cannot be instantiated

IfxCblob

public IfxCblob(java.io.InputStream fin)
Creates an IfxCblob instance with the given input stream. An IfxCblob object created using this constructor cannot be used for accessing the Clob.

Parameters:
fin - The input stream for this smart large object

IfxCblob

public IfxCblob(java.sql.Connection conn,
                java.io.InputStream fin,
                int length)
         throws java.sql.SQLException
Creates an IfxCblob instance with a given connection, an inputStream and number of bytes to write.

Parameters:
conn - The IfxConnection object.
fin - The input stream from which the data will be written into the smart large object.
length - Number of bytes to be written.
Throws:
java.sql.SQLException - if object instance cannot be instantiated.

IfxCblob

public IfxCblob(java.sql.Connection conn,
                java.io.InputStream fin,
                int length,
                java.lang.String sbspaceName)
         throws java.sql.SQLException
Creates an IfxCblob instance with a given connection, an inputStream and number of bytes to write to a specified smart blob space.

Parameters:
conn - The IfxConnection object.
fin - The input stream from which the data will be written into the smart large object.
length - Number of bytes to be written.
sbspaceName - specified smart blob space name.
Throws:
java.sql.SQLException - if object instance cannot be instantiated.

IfxCblob

public IfxCblob(java.sql.Connection conn,
                java.io.InputStream fin,
                int length,
                IfxLobDescriptor loDesc)
         throws java.sql.SQLException
Creates an IfxCblob instance with a given connection, an inputStream, number of bytes to write and a specified lob descriptor.

Parameters:
conn - The IfxConnection object.
fin - The input stream from which the data will be written into the smart large object.
length - Number of bytes to be written.
loDesc - user created lob descriptor.
Throws:
java.sql.SQLException - if object instance cannot be instantiated.

IfxCblob

public IfxCblob(java.sql.Connection conn,
                java.lang.String str)
         throws java.sql.SQLException
Creates an IfxCblob instance with a given connection and a string of data.

Parameters:
conn - The IfxConnection object.
str - The String from which the data will be written to smart blob.
Throws:
java.sql.SQLException - if object instance cannot be instantiated.

IfxCblob

public IfxCblob(java.sql.Connection conn,
                java.lang.String str,
                java.lang.String sbspaceName)
         throws java.sql.SQLException
Creates an IfxCblob instance with a given connection and a string of data and a specified smart blob space.

Parameters:
conn - The IfxConnection object.
str - The String from which the data will be written to smart blob.
sbspaceName - specified smart blob space name.
Throws:
java.sql.SQLException - if object instance cannot be instantiated.

IfxCblob

public IfxCblob(java.sql.Connection conn,
                java.lang.String str,
                IfxLobDescriptor loDesc)
         throws java.sql.SQLException
Creates an IfxCblob instance with a given connection and a string of data and a specified lob descriptor.

Parameters:
conn - The IfxConnection object.
str - The string from which the data will be written to smart blob.
loDesc - user defined lob descriptor.
Throws:
java.sql.SQLException - if object instance cannot be instantiated.
Method Detail

getLocator

public IfxLocator getLocator()
                      throws java.sql.SQLException
Gets the smart large object locator from the clob object.

Returns:
The smart large object locator.
Throws:
java.sql.SQLException - if the object type is not a BLOB or CLOB.

length

public long length()
Gets the length of the character smart large object in characters.

Specified by:
length in interface java.sql.Clob
Returns:
The length of the smart large object in characters.

getSubString

public java.lang.String getSubString(long position,
                                     int length)
Returns a copy of the substring of the smart large object at the requested position. This method can be used to fetch data from a blob. If the IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)

Specified by:
getSubString in interface java.sql.Clob
Parameters:
position - The position at which to start searching.
length - The number of consecutive characters to be copied.
Returns:
A byte array containing a substring of the smart large object.

getCharacterStream

public java.io.Reader getCharacterStream()
                                  throws java.sql.SQLException
Gets the smart large object contents as a Unicode stream. Characters are converted from database encoding to unicode.

Specified by:
getCharacterStream in interface java.sql.Clob
Returns:
A Unicode stream containing the smart large object data.
Throws:
java.sql.SQLException

getAsciiStream

public java.io.InputStream getAsciiStream()
                                   throws java.sql.SQLException
Gets the smart large object contents as an ASCII stream. This method can be used to fetch data from a blob. If the IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)

Specified by:
getAsciiStream in interface java.sql.Clob
Returns:
An ASCII stream containing the smart large object data.
Throws:
java.sql.SQLException - if there is a problem getting the stream.

position

public long position(java.lang.String searchstr,
                     long start)
              throws java.sql.SQLException
Determines the character position at which the given substring occurs. This method can be used to find a match for a pattern within a clob. In case IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)

Specified by:
position in interface java.sql.Clob
Parameters:
searchstr - The substring for which you want to search.
start - The position at which searching begins.
Returns:
The position at which the substring appears, or -1 if the string does not appear in the smart large object.
Throws:
java.sql.SQLException - if the string cannot be read or the the index is out of bounds.

position

public long position(java.sql.Clob searchstr,
                     long start)
              throws java.sql.SQLException
Determines the character position at which the given substring occurs. This method can be used to find a match for a pattern within a clob. If the IfxCblob object is created with the following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)

Specified by:
position in interface java.sql.Clob
Parameters:
searchstr - The substring for which you want to search.
start - The position at which searching begins.
Returns:
The position at which the substring appears, or -1 if the string does not appear in the smart large object.
Throws:
java.sql.SQLException - if there is an error accessing the CLOB

setAsciiStream

public void setAsciiStream(long position,
                           java.io.InputStream fin,
                           int length)
                    throws java.sql.SQLException
Writes ascii stream of data from an InputStream to an already existing smart large blob object. Characters are written without any codeset conversion This method can be used to fetch data from a blob. If the IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)

Parameters:
fin - InputStream
length - Number of bytes to be written from the input stream.
Throws:
java.sql.SQLException - if the type is not a CLOB, the large object is invalid or the large object cannot be opened.

setSubString

public void setSubString(long position,
                         java.lang.String str,
                         int length)
                  throws java.sql.SQLException
Writes data from a string to an already existing smart large blob object. This method can be used to fetch data from a blob. If the IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. This method can be used when an IfxCblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxCblob(IfxConnection connection, IfxLocator locator) IfxCblob(IfxConnection conn, InputStream fin, int length) IfxCblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxCblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxCblob(IfxConnection conn, String str) IfxCblob(IfxConnection conn, String str, String sbspaceName) IfxCblob(IfxConnection conn, String str, IfxLobDescriptor loDesc)

Parameters:
str - The string which the data will be written.
length - Number of bytes to be written into smart large object.
Throws:
java.sql.SQLException - if the type is not a CLOB, the large object is invalid or the large object cannot be opened.

close

public void close()
           throws java.sql.SQLException
This method will release the resources used by the object.

Throws:
java.sql.SQLException - if there was an error closing the large object.

seek

public long seek(long offset,
                 int whence)
          throws java.sql.SQLException
This method sets the position for the next read and write operation of the smart large object. In case IfxClob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.

Parameters:
offset - Number of bytes from the location specified in the whence parameter.
whence - defines the offset value more specifically; LO_SEEK_SET, from begining; LO_SEEK_CUR, relative from current position; LO_SEEK_END, from the end.
Throws:
java.sql.SQLException - if the object is not a smart large object.

where

public long where()
           throws java.sql.SQLException
This method returns the current seek position within the large object. In case IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.

Returns:
The current position within the smart large object.
Throws:
java.sql.SQLException - if the object is not a smart large object.

getLoStat

public IfxLoStat getLoStat()
                    throws java.sql.SQLException
This method returns an IfxLoStat object, which provides statistical information, such as the last access time, the last update status time, the last modification time, and the reference count of the smart large object. In case IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.

Returns:
IfxLoStat Object containing information about the smart large object.
Throws:
java.sql.SQLException - if the object is not a smart large object.

truncate

public void truncate(long size)
              throws java.sql.SQLException
This method truncates the smart large object at the given position. If the position given is beyond the length of the smart large object it ignores the request. In case IfxCblob object is created with following constructors; IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.

Specified by:
truncate in interface java.sql.Clob
Parameters:
size - Position at which the truncation will occur.
Throws:
java.sql.SQLException - if the object is not a smart large object.

setString

public int setString(long pos,
                     java.lang.String str)
              throws java.sql.SQLException
Writes the given Java String to the CLOB value that this Clob object designates at the position pos. The Unicode string is always conveted to database codeset before writing to clob.

Specified by:
setString in interface java.sql.Clob
Parameters:
str - the string to be written to the CLOB value that this Clob designates
Returns:
the number of characters written
Throws:
java.sql.SQLException - if there is an error accessing the CLOB value

setString

public int setString(long pos,
                     java.lang.String str,
                     int offset,
                     int len)
              throws java.sql.SQLException
Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents. The characters are always conveted to database locale codeset before writing to clob. In case IfxClob object is created with following constructors, IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used. The Unicode characters are always conveted to database codeset before writing to clob.

Specified by:
setString in interface java.sql.Clob
Parameters:
pos - the position at which to start writing to this CLOB object
str - the string to be written to the CLOB value that this Clob object represents
offset - the offset into str to start reading the characters to be written
len - the number of characters to be written
Returns:
the number of characters written
Throws:
java.sql.SQLException

setAsciiStream

public java.io.OutputStream setAsciiStream(long pos)
                                    throws java.sql.SQLException
Retrieves a stream to be used to write Ascii characters to the CLOB value that this Clob object represents, starting at position pos. Characters are written without any codeset conversion In case IfxClob object is created with following constructors, IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.

Specified by:
setAsciiStream in interface java.sql.Clob
Parameters:
pos - the position at which to start writing to this CLOB object
Returns:
the stream to which ASCII encoded characters can be written
Throws:
java.sql.SQLException - if there is an error accessing the CLOB value

setCharacterStream

public java.io.Writer setCharacterStream(long pos)
                                  throws java.sql.SQLException
Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this Clob object represents, at position pos. The Unicode characters are always conveted to database codeset before writing to clob. In case IfxClob object is created with following constructors, IfxCblob() or IfxCblob(IfxLocaor locator) or IfxCblob(InputStream fin) this method cannot be used.

Specified by:
setCharacterStream in interface java.sql.Clob
Parameters:
pos - the position at which to start writing to the CLOB value
Returns:
a stream to which Unicode encoded characters can be written
Throws:
java.sql.SQLException - if there is an error accessing the CLOB value