Skip navigation links

Oracle® Database XStream Java API Reference
11g Release 2 (11.2)

E16674-02


oracle.streams
Class XStreamOut

java.lang.Object
  extended by oracle.streams.XStreamOut


public class XStreamOut
extends java.lang.Object

The XStreamOut class provides APIs for using Oracle XStream Out. This is the main Java API for Oracle XStream Out. It contains several main API methods as shown in the list.

Here is an example of using the callback API:

   Connection conn;
   XStreamOut xsOut;
   ...

   // assume myLCRHandler implements XStreamLCRCallbackHandler and 
   XStreamLCRCallbackHandler hdlr = new MyLCRHandler(); 

   try
   {
     DriverManager.registerDriver(new oracle.jdbc.OracleDriver());
     conn = DriverManager.getConnection("jdbc:oracle:oci:@hostname:port:sid",
                                        "strmadm", "strmadm");
     xsOut = XStreamOut.attach(conn, new String("APPLY1"),
                               lastPosition, XStreamOut.DEFAULT_MODE);
     while(true) 
     {
       xsOut.receiveLCRCallback(hdlr, XStreamOut.DEFAULT_MODE);
       maintainWatermark();
       ... 
       if (user_terminate_condition)
       {
         break; 
       }
     }
     xsOut.detach(XStreamOut.DEFAULT_MODE);
     } 
   }
   catch(StreamsException e)
   {
      System.out.println("Streams exception: " + e.getMessage()); 
   }
   catch(Exception e)
   {
   }
 

Please see processLCR() and processChunk() in XStreamLCRCallbackHandler for examples of implementing the callback methods.

Here is an example of using the non-callback API:

   Connection conn;
   XStreamOut xsOut;
   ...

   try
   {
     DriverManager.registerDriver(new oracle.jdbc.OracleDriver());
     conn = DriverManager.getConnection("jdbc:oracle:oci:@hostname:port:sid",
                                        "strmadm", "strmadm");
     xsOut = XStreamOut.attach(conn, new String("APPLY1"),
                               lastPosition, XStreamOut.DEFAULT_MODE);
     while(true) 
     {
       LCR alcr = xsOut.receiveLCR(XStreamOut.DEFAULT_MODE);
       if (xsOut.getBatchStatus == EXECUTING) // system is active
       {
         maintainWatermark();
         // ... process LCR header
         if (alcr instanceof RowLCR)
         {
           // ... process scalar columns
           // process chunk data using receiveChunk() API
           if (((RowLCR)alcr).hasChunkData())
           {
             do
             {
               ChunkColumnValue chunk = xsOut.receiveChunk(DEFAULT_MODE);
               // process the Chunk
             } while (!chunk.isEndOfRow())
           }  
         } 
       }
       else // system is idle
       {
         maintainWatermark();
         if (user_terminate_condition)
         {
           break; 
         }
       }
     }
     xsOut.detach(XStreamOut.DEFAULT_MODE);
     } 
   }
   catch(StreamsException e)
   {
      System.out.println("Streams exception: " + e.getMessage()); 
   }
   catch(Exception e)
   {
   }
   
 



Field Summary
static int DEFAULT_BATCH_INTERVAL
          XStreamOut default acknowledge interval value for batch processing
static int DEFAULT_IDLE_TIMEOUT
          XStreamOut default timeout value for idle processing
static int DEFAULT_MODE
          XStreamOut default mode
static int EXECUTING
          XStreamOut batch processing status EXECUTING, which indicates the the batch is in progress
static int FINISHED
          XStreamOut batch processing status FINISHED, which is the default status
static int NEW_COLUMN_ONLY_MODE
          This column list mode allows users to receive LCRs with only new columns in the new value list.

 

Method Summary
static XStreamOut attach(oracle.jdbc.OracleConnection oconn, java.lang.String serverName, byte[] lastPosition, int mode)
          Attaches to outbound server.
static XStreamOut attach(oracle.jdbc.OracleConnection oconn, java.lang.String serverName, byte[] lastPosition, int batchInterval, int idleTimeout, int mode)
          Attaches to outbound server.
 void detach(int mode)
          Detaches from outbound server.
 int getBatchStatus()
          Gets batch status.
 byte[] getFetchLowWatermark()
          Gets fetch low watermark.
 ChunkColumnValue receiveChunk(int mode)
          Receives chunk data in non-callback mode.
 LCR receiveLCR(int mode)
          Receives one LCR in non-callback mode.
 void receiveLCRCallback(XStreamLCRCallbackHandler handler, int mode)
          Receives a stream of LCRs in callback mode.
 void setProcessedLowWatermark(byte[] processedLowWatermark, byte[] oldestPosition, int mode)
          Sets processed low watermark.
 void setProcessedLowWatermark(byte[] processedLowWatermark, int mode)
          Sets processed low watermark.

 

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Field Detail

DEFAULT_MODE

public static final int DEFAULT_MODE
XStreamOut default mode
See Also:
Constant Field Values

NEW_COLUMN_ONLY_MODE

public static final int NEW_COLUMN_ONLY_MODE
This column list mode allows users to receive LCRs with only new columns in the new value list.
By default XStreamOut returns the union of new columns and old columns that are not present in the new column list. This mode is valid for receiveLCR and receiveLCRCallback APIs.
See Also:
Constant Field Values

DEFAULT_BATCH_INTERVAL

public static final int DEFAULT_BATCH_INTERVAL
XStreamOut default acknowledge interval value for batch processing
See Also:
Constant Field Values

DEFAULT_IDLE_TIMEOUT

public static final int DEFAULT_IDLE_TIMEOUT
XStreamOut default timeout value for idle processing
See Also:
Constant Field Values

FINISHED

public static final int FINISHED
XStreamOut batch processing status FINISHED, which is the default status
See Also:
Constant Field Values

EXECUTING

public static final int EXECUTING
XStreamOut batch processing status EXECUTING, which indicates the the batch is in progress
See Also:
Constant Field Values

Method Detail

attach

public static XStreamOut attach(oracle.jdbc.OracleConnection oconn,
                                java.lang.String serverName,
                                byte[] lastPosition,
                                int mode)
                         throws StreamsException
Attaches to outbound server.
This API attaches the client to the specified XStream outbound server. This API is also the factory method that returns an XStreamOut instance once it is attached to a valid XStream outbound server.
Parameters:
oconn - Oracle database connection.
Note that the connection must be made using Oracle OCI (thick) driver.
serverName - Name of the XStream outbound server.
lastPosition - Position that establishes the starting point of the stream. An exception is thrown if the specified position is non-NULL and less than the outbound server's processed low watermark. Otherwise, LCRs with positions greater than the specified position are sent to the client.
mode - The mode of XStream outbound server (for future extension). Use XStreamOut.DEFAULT_MODE for now.
Returns:
an XStreamOut instance.
Throws:
StreamsException - if error occurs during attach.

attach

public static XStreamOut attach(oracle.jdbc.OracleConnection oconn,
                                java.lang.String serverName,
                                byte[] lastPosition,
                                int batchInterval,
                                int idleTimeout,
                                int mode)
                         throws StreamsException
Attaches to outbound server.
This API is the same as the other attach API except that is includes the batchInterval and idleTimeout parameters.
Parameters:
oconn - Oracle database connection.
Note that the connection must be made using Oracle OCI (thick) driver.
serverName - name of the XStream outbound server.
lastPosition - Position that establishes the starting point of the stream. An exception is thrown if the specified position is non-NULL and less than the outbound server's processed low watermark. Otherwise, LCRs with positions greater than the specified position are sent to the client.
batchInterval - XStreamOut batch processing interval.
idleTimeout - XStreamOut idle timeout value.
mode - The mode of XStream outbound server (for future extension). Use XStreamOut.DEFAULT_MODE for now.
Returns:
an XStreamOut instance.
Throws:
StreamsException - if error occurs during attach.

detach

public void detach(int mode)
            throws StreamsException
Detaches from outbound server.
This API detaches the client from the XStream outbound server.
Parameters:
mode - The mode of XStream outbound server (for future extension). Use XStreamOut.DEFAULT_MODE for now.
Throws:
StreamsException - if error occurs during detach.

receiveLCRCallback

public void receiveLCRCallback(XStreamLCRCallbackHandler handler,
                               int mode)
                        throws StreamsException
Receives a stream of LCRs in callback mode.

This API starts LCR streaming from the specified XStream outbound server. You must specify an LCR callback handler that processes each LCR. See more details about LCR callback handlers in XStreamLCRCallbackHandler. For each LCR received, the callback method processLCR() in the given XStreamLCRCallbackHandler is invoked. If chunk data exists in the LCRs, the callback method processChunk() in the given XStreamLCRCallbackHandler is invoked.

To reduce network roundtrip overhead, for each ReceiveLCRCallback call, XStream also starts a batch process to fill the network buffer with LCRs. The batch process is stopped at a transaction boundary after 30 seconds or after one second if the system is idle. ReceiveLCRCallback does not return until one batch process ends.

To receive LCRs with only new columns in the new value list, COLUMN_NEW_ONLY_MODE can be set in the mode flag,
   int mode = XStreamOut.DEFAULT_MODE | XStreamOut.COLUMN_NEW_ONLY_MODE;
 
By default XStreamOut returns the union of new columns and old columns that are not present in the new column list.
Parameters:
handler - The XStreamLCRCallbackHandler for handling the LCRs.
mode - A bit flag indicates the mode of XStream outbound server. There are two supported modes currently, DEFAULT_MODE and COLUMN_NEW_ONLY_MODE
Throws:
StreamsException - if error occurs during the entire batch.
See Also:
XStreamLCRCallbackHandler

receiveLCR

public LCR receiveLCR(int mode)
               throws StreamsException
Receives one LCR in non-callback mode.

This method receives one LCR in the stream from the connected outbound server. To avoid network roundtrip for every ReceiveLCR call, XStream still uses batch processing to fill up the network buffer with LCRs. The batch is stopped at a transaction boundary after 30 seconds or after one second if the system is idle.

You should use getBatchStatus API after receiveLCR call to check the status of batch processing.
To receive LCRs with only new columns in the new value list, COLUMN_NEW_ONLY_MODE can be set in the mode flag,
   int mode = XStreamOut.DEFAULT_MODE | XStreamOut.COLUMN_NEW_ONLY_MODE;
 
By default XStreamOut returns the union of new columns and old columns that are not present in the new column list.
Parameters:
mode - A bit flag indicates the mode of XStream outbound server . There are two supported modes currently, DEFAULT_MODE and COLUMN_NEW_ONLY_MODE
Returns:
An LCR object.
Throws:
StreamsException - if error occurs while receiving an LCR

receiveChunk

public ChunkColumnValue receiveChunk(int mode)
                              throws StreamsException
Receives chunk data in non-callback mode.
This API retrieves streaming LOB, LONG, or XMLTYPE chunk data. Call this method after the receiveLCR() call when the received LCR contains chunk data. All the chunks from one LOB column are returned entirely before switching to the next LOB column.
There is no fixed ordering when LOB columns are returned. You must check the column name to determine the column to which the chunk belongs. Use the the isLastChunk() method in ChunkColumnValue to determine when the last chunk of a LOB column is returned.
Use the isEndOfRow() method in ChunkColumnValue to determine if the last chunk of entire row change has been returned.
Parameters:
mode - The mode of XStream outbound server (for future extension). Use XStreamOut.DEFAULT_MODE for now.
Returns:
A ChunkColumnValue object contains the chunked column data.
Throws:
StreamsException - If error occurs while receiving chunk data or constructing a ChunkColumnValue object.

getBatchStatus

public int getBatchStatus()
Gets batch status.
This method is used to get the status of XStreamOut batch processing in non-callback mode. The return value can be either EXECUTING or FINISHED. See receiveLCR and receiveLCRCallback for more information about batch process in XStreamOut.
When the status is EXECUTING, the current connection associated with XStreamOut is in use for batch receiving the LCRs from outbound server. Therefore, this connection cannot be used for other JDBC calls. When the status is FINISHED, the connection is available for use.
The batch status is updated whenever the receiveLCR() method is invoked.
Returns:
The XStreamOut batch processing status

getFetchLowWatermark

public byte[] getFetchLowWatermark()
Gets fetch low watermark.
This API gets the outbound server's FetchLowWatermark. The FetchLowWatermark denotes that the outbound server has processed all LCRs with positions lower than or equal to this value. This method can be used to increase the position maintained on the client when the system is idle. When the system is actively streaming LCRs, you can maintain the low watermark using received LCRs.
Returns:
The outbound server's FetchLowWatermark

setProcessedLowWatermark

public void setProcessedLowWatermark(byte[] processedLowWatermark,
                                     int mode)
                              throws StreamsException
Sets processed low watermark.
The ProcessedLowWatermark denotes that all LCRs at or below this watermark have been processed by the client. This ProcessedLowWatermark is sent to the outbound server periodically so that archived redo logs containing already processed transactions can be purged. You can call this method anytime between attach and detach calls.
Parameters:
processedLowWatermark - The client's processed low watermark.
mode - The mode of XStream outbound server (for future extension). Use XStreamOut.DEFAULT_MODE for now.
Throws:
StreamsException - if error occurs while setting the low watermark.

setProcessedLowWatermark

public void setProcessedLowWatermark(byte[] processedLowWatermark,
                                     byte[] oldestPosition,
                                     int mode)
                              throws StreamsException
Sets processed low watermark.
The ProcessedLowWatermark denotes that all LCRs at or below this watermark have been processed by the client. This ProcessedLowWatermark is sent to the outbound server periodically so that archived redo logs containing already processed transactions can be purged. You can call this method anytime between attach and detach calls.
Parameters:
processedLowWatermark - The client's processed low watermark.
oldestPosition - The client's oldest position.
mode - The mode of XStream outbound server (for future extension). Use XStreamOut.DEFAULT_MODE for now.
Throws:
StreamsException - if error occurs while setting the low watermark.

Skip navigation links

Oracle® Database XStream Java API Reference
11g Release 2 (11.2)

E16674-02


Copyright © 2009, 2010, Oracle and/or its affiliates. All Rights Reserved.