XStreamOut (Oracle Database XStream Java API Reference)

java.lang.Object
- 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.

Attach(): Attach to an XStream outbound server.
Detach(): Detach from an XStream outbound server.
ReceiveLCR(): Receive one LCR from the XStream outbound server in non-callback mode.
ReceiveChunk(): Retrieve chunk data in non-callback mode. Invoke this API after ReceiveLCR() if the LCR contains LOB, LONG, or XMLTYPE data.
ReceiveLCRCallback(): Receive a stream of LCRs from the XStream outbound server in callback mode. You can specify an XStreamLCRCallbackHandler to process the LCRs received from the XStream outbound server.

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.ATTACH_APP_CONTAINER_MODE + 
                               XStreamOut.ATTACH_EXTENDED_ID_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.ATTACH_APP_CONTAINER_MODE + 
                               XStreamOut.ATTACH_EXTENDED_ID_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

Fields
Modifier and Type	Field and Description
`static int`	`ATTACH_APP_CONTAINER_MODE` This attach mode captures application container statements.
`static int`	`ATTACH_EXTENDED_ID_MODE` This attach mode returns transaction ID using extended format, "pdb_id.nn.nn.nn".
`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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
  - ATTACH_APP_CONTAINER_MODE
```
public static final int ATTACH_APP_CONTAINER_MODE
```
    This attach mode captures application container statements.
    
    See Also:
    
    Constant Field Values
  - ATTACH_EXTENDED_ID_MODE
```
public static final int ATTACH_EXTENDED_ID_MODE
```
    This attach mode returns transaction ID using extended format, "pdb_id.nn.nn.nn".
    
    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). Valid modes are
    XStreamOut.ATTACH_APP_CONTAINER_MODE and
    XStreamOut.ATTACH_EXTENDED_ID_MODE. These modes can be added
    together.
    
    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.

Class XStreamOut

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_MODE

NEW_COLUMN_ONLY_MODE

DEFAULT_BATCH_INTERVAL

DEFAULT_IDLE_TIMEOUT

FINISHED

EXECUTING

ATTACH_APP_CONTAINER_MODE

ATTACH_EXTENDED_ID_MODE

Method Detail

attach

attach

detach

receiveLCRCallback

receiveLCR

receiveChunk

getBatchStatus

getFetchLowWatermark

setProcessedLowWatermark

setProcessedLowWatermark