Skip navigation links

oracle.streams
Class XStreamOut

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