LONG and LONG RAW data types

When one or more LONG or LONG RAW columns are selected in a query, OceanBase Connector/J transmits these columns to the client in streaming mode.

In streaming mode, OceanBase Connector/J generally does not read data of a LONG or LONG RAW column from the network. Before OceanBase Connector/J 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 a 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. OceanBase Connector/J converts the data based on the character sets of the database and OceanBase Connector/J.

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, OceanBase Connector/J assumes that the US7ASCII or WE8ISO8859P1 character set is used for the underlying data in the database. If the assumption is true, OceanBase Connector/J returns the bytes corresponding to the ASCII characters. If the database is not using the US7ASCII or WE8ISO8859P1 character set, the getAsciiStream method 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 getBinaryStream method returns UTF-8-encoded data. If the server uses the US7ASCII or WE8ISO8859P1 character set, the method returns US7ASCII byte streams.

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: Use the getBinaryStream method to obtain LONG RAW data

1. 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');
   

2. Write the data in the LONG RAW column to the sample.gif file.

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

3. Use the getBinaryStream method to obtain LONG RAW data.

   // 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: Use the getBytes method to obtain LONG RAW data

In this example, the getBytes method is used to obtain content of the giftype column. OceanBase Connector/J obtains all data in one call and stores the data 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();
   }
}

A 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.