LONG and LONG RAW data types

When one or more LONG or LONG RAW columns are selected in a query, the JDBC driver transmits these columns to the client in streaming mode.

In streaming mode, the JDBC driver generally does not read data of the LONG or LONG RAW column from the network. Before the JDBC driver calls the getXXX method to read the column data, the column data is retained on the network communication channel. If an operation other than data reading is performed, the column data will be discarded from the channel. In streaming mode, the memory capacity is fully utilized, and the round-trip communication is minimized, but other database operations are affected.

To access data in the LONG column, you can treat this column as a Java InputStream object, and use the read method of the InputStream object to obtain the data. You can also treat the data as a String or byte array, and obtain the data through stream transmission.

You can obtain LONG and LONG RAW data by using all the three types of data streams. The JDBC driver converts the data streams based on the character sets of the database and the JDBC driver. Notice

Do not create tables with the LONG column. Instead, you can use the LOB, CLOB, NCLOB, or BLOB column. Use limits on the LOB column are far less than those of the LONG column. Therefore, we recommend that you convert the existing LONG columns into LOB columns.

Convert LONG RAW data

The getBinaryStream method returns RAW data. The getAsciiStream method converts RAW data into hexadecimal data and returns the corresponding ASCII values. The getUnicodeStream method converts RAW data into hexadecimal data and returns Unicode characters.

Convert LONG data

When you call the getAsciiStream method to obtain LONG data, the JDBC driver assumes that the US7ASCII or WE8ISO8859P1 character set is used for the underlying data in the database. If the assumption is true, the JDBC driver returns the bytes corresponding to the ASCII characters. If the database is not using the US7ASCII or WE8ISO8859P1 character set, the getAsciiStream returns meaningless information.

When the getUnicodeStream method is used to obtain LONG data, the method returns a UTF-16-encoded Unicode character stream.

When the getBinaryStream method is used to obtain LONG data, if the database is not using the US7ASCII or WE8ISO8859P1 character set, the method returns UTF-8-encoded data. If the server uses the US7ASCII or WE8ISO8859P1 character set, the method returns US7ASCII byte streams. Notice

When the LONG or LONG RAW column is received as a stream, observe the order of the columns retrieved from the database.

The following table describes the conversion of different types of LONG and LONG RAW data streams.

Examples

The getXXXStream method is able to return data in an incremental manner, while the getBytes method returns all data in one call. The following examples show how to obtain a binary data stream.

Example 1: Using the getBinaryStream method to obtain LONG RAW data

-- Create Table stream01 that stores the LONG RAW column related to the name SAMPLE.
CREATE TABLE stream01 (name VARCHAR2 (50), giftype LONG RAW);
INSERT INTO stream01 VALUES ('SAMPLE', '1234567890123');

-- Write the data in the LONG RAW column to the sample.gif file.
ResultSet rs = st.executeQuery 
                 ("select giftype from stream01 where NAME='SAMPLE'");

// Obtain the first row.
if (rs.next())
{
    // Obtain GIF data as a stream.
    InputStream gif_type = rs.getBinaryStream (1);
   try
   {
      FileOutputStream file = null;
      file = new FileOutputStream ("sample.gif");
      int chunk;
      while ((chunk = gif_type.read()) != -1)
         file.write(chunk);
   }
   catch (Exception e)
   {
      String err = e.toString();
      System.out.println(err);
   }
   finally
   {
      if file != null()
         file.close();
   }
} 

In this example, the InputStream object returned by the getBinaryStream method directly reads data from the database connection.

Example 2: Using the getBytes method to obtain LONG RAW data

In this example, the getBytes method is used to obtain content of the giftype column. The JDBC driver obtains all data in one call and stores it in a byte array.

ResultSet rs2 = st.executeQuery 
                  ("select giftype from streame01 where NAME='SAMPLE'"); 

// Obtain the first row.
if (rs2.next())
{
   // Obtain GIF data as a stream.
   byte[] bytes = rs2.getBytes(1);
   try
   {
      FileOutputStream file = null;
      file = new FileOutputStream ("sample2.gif");
      file.write(bytes);
   }
   catch (Exception e)
   {
      String err = e.toString();
      System.out.println(err);
   }
   finally
   {
      if file != null()
         file.close();
   }
}

The LONG RAW column can contain up to 2 GB of data. Therefore, compared with the getBinaryStream method, the getBytes method uses more memory capacity. If the maximum size of data in the LONG or LONG RAW column is unknown, use a stream. Note

• The JDBC driver can automatically transmit a LONG or LONG RAW column by using streams. However, in some cases, you may want to avoid stream transmission. For example, when the LONG column contains a small amount of data, you may expect the data to be returned in one call but not incrementally.

• To avoid stream transmission, use the defineColumnType method to redefine the type of the LONG column. For example, you can redefine the LONG or LONG RAW column into the VARCHAR or VARBINARY type, so the JDBC driver does not automatically transmit data by using streams.

• If you use the defineColumnType method to redefine the column type, you must specify the column type in the query statement. Otherwise, executeQuery will fail. In addition, you must convert the Statement object into oceanbase.jdbc.oceanbaseStatement.