Skip navigation links

oracle.streams
Class XStreamIn

java.lang.Object
oracle.streams.XStreamIn

public class XStreamIn

extends java.lang.Object

The XStreamIn class provides APIs for using Oracle XStream In. This is the main Java API for Oracle XStream Inbound. It has the following main API methods as shown in the list.

• Attach(): Attach to an XStream inbound server.
• Detach(): Detach from an XStream inbound server.
• SendLCRCallback(): Send a stream of logical change records (LCRs) to the XStream inbound server in callback mode. Specify an XStreamLCRCallbackHandler that constructs the LCRs that are sent to the XStream inbound server.
• SendLCR(): Send one LCR to the XStream inbound server in non-callback mode.
• SendChunk(): Send chunk data for LCRs that contain LOB, LONG, or XMLTYPE columns. Invoke this API only after invoking the sendLCR() API if the LCR contains chunk data.

Here is an example of using the callback API:

   Connection conn;
   XStreamIn xsIn;
   ...

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

   try
   {
     DriverManager.registerDriver(new oracle.jdbc.OracleDriver());
     conn = DriverManager.getConnection("jdbc:oracle:oci:@hostname:port:sid",
                      "strmadm", "strmadm");
     xsIn = XStreamIn.attach(conn, new String("APPLY1"), new String("CAP1"),
                             XStreamIn.DEFAULT_MODE);
     while(true) 
     {
       xsIn.sendLCRCallback(hdlr, XStreamIn.DEFAULT_MODE);
       // maintain processed low watermark
       maintainWatermark();
       ... 
       if (user_terminate_condition)
       {
         break;
       }
     }
     xsIn.detach(XStreamIn.DEFAULT_MODE);  
   }
   catch(StreamsException e)
   {
      System.out.println("Streams exception: " + e.getMessage()); 
   }
   catch(Exception e)
   {
   }
 

Please see createLCR() and createChunk() in XStreamLCRCallbackHandler for examples of implementing the callback methods.

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

   Connection conn;
   XStreamIn xsIn;
   ...

   try
   {
     DriverManager.registerDriver(new oracle.jdbc.OracleDriver());
     conn = DriverManager.getConnection("jdbc:oracle:oci:@hostname:port:sid",
                      "strmadm", "strmadm");
     xsIn = XStreamIn.attach(conn, new String("APPLY1"), new String("CAP1"),
                             XStreamIn.DEFAULT_MODE);
     lwm = xsIn.getProcessedLowWatermark(XStreamIn.DEFAULT_MODE);
     while(true) 
     {
       RowLCR rowlcr = new DefaultRowLCR(...);

       if (rowlcr has chunk data)
         rowlcr.setChunkDataFlag(true);

       int status = xsIn.sendLCR(rowlcr, XStreamIn.DEFAULT_MODE);

       if (status == EXECUTING)
       {
         for (each chunk in each lob/long/xmltype column)
         {
           ChunkColumnValue chunk = new DefaultChunkColumnValue(...);
           if (chunk is the last one in the column)
             chunk.setLastChunk(true);
           if (chunk is the last one for entire row)
             chunk.setEndOfRow(true);            
           xsIn.sendChunk(chunk, XStreamIn.DEFAULT_MODE);
         }
       }
       else // status == FINISHED
       {
         // maintain watermark
         lwm =  xsIn.getProcessedLowWatermark(XStreamIn.DEFAULT_MODE);
         maintainWatermark();
       }

       if (user_terminate_condition)
       {
         break;
       }
     }
     xsIn.detach(XStreamIn.DEFAULT_MODE);  
   }
   catch(StreamsException e)
   {
      System.out.println("Streams exception: " + e.getMessage()); 
   }
   catch(Exception e)
   {
   }
 

Field Summary

static int	DEFAULT_BATCH_INTERVAL XStreamIn default batch interval value for batch processing
static int	DEFAULT_MODE XStreamIn default mode
static int	EXECUTING XStreamIn batch processing status EXECUTING, which indicates the the batch is in progress
static int	FINISHED XStreamIn batch processing status FINISHED, which is the default status

Method Summary

static XStreamIn	attach(oracle.jdbc.OracleConnection oconn, java.lang.String serverName, java.lang.String sourceName, int mode) Attaches to an inbound server.
static XStreamIn	attach(oracle.jdbc.OracleConnection oconn, java.lang.String serverName, java.lang.String sourceName, int batchInterval, int mode) Attaches to an inbound server.
byte[]	detach(int mode) Detaches from an inbound server.
void	flush(int mode) Flushes the network.
byte[]	getLastPosition() Gets last position.
byte[]	getOldestPosition() Gets the oldest position.
byte[]	getProcessedLowWatermark() Gets the processed low watermark.
void	sendChunk(ChunkColumnValue chunk, int mode) Sends chunk data in non-callback mode.
int	sendLCR(LCR lcr, int mode) Sends one LCR in non-callback mode.
void	sendLCRCallback(XStreamLCRCallbackHandler handler, int mode) Sends a stream of LCRs in callback mode.

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

XStreamIn default mode

See Also:

Constant Field Values

DEFAULT_BATCH_INTERVAL

public static final int DEFAULT_BATCH_INTERVAL

XStreamIn default batch interval value for batch processing

See Also:

Constant Field Values

FINISHED

public static final int FINISHED

XStreamIn batch processing status FINISHED, which is the default status

See Also:

Constant Field Values

EXECUTING

public static final int EXECUTING

XStreamIn batch processing status EXECUTING, which indicates the the batch is in progress

See Also:

Constant Field Values

Method Detail

attach

public static XStreamIn attach(oracle.jdbc.OracleConnection oconn,
                               java.lang.String serverName,
                               java.lang.String sourceName,
                               int mode)
                        throws StreamsException

Attaches to an inbound server.
This API attaches the client to the specified XStream inbound server. This is also the factory method that returns an XStreamIn instance once it is attached to a valid XStream inbound server.
After successfully attached to an XStream inbound server, call getLastPosition() to decide where to start sending LCRs in the LCR stream.

Parameters:

oconn - Oracle database connection.
Note that the connection must be made using Oracle OCI (thick) driver.

serverName - Name of the XStream inbound server.

sourceName - Name of the data source.

mode - The mode of XStream inbound server (for future extension). Use XStreamIn.DEFAULT_MODE for now.

Returns:

an XStreamIn instance object

Throws:

StreamsException - if error occurs during attach.

attach

public static XStreamIn attach(oracle.jdbc.OracleConnection oconn,
                               java.lang.String serverName,
                               java.lang.String sourceName,
                               int batchInterval,
                               int mode)
                        throws StreamsException

Attaches to an inbound server.
This API is the same as the other attach API except that it includes the batchInterval parameter.

Parameters:

oconn - Oracle database connection.
Note that the connection must be made using Oracle OCI (thick) driver.

serverName - Name of the XStream inbound server.

sourceName - Name of the data source

batchInterval - XStreamIn batch processing interval.

mode - The mode of XStream inbound server (for future extension). Use XStreamIn.DEFAULT_MODE for now.

Returns:

an XStreamIn instance object

Throws:

StreamsException - if error occurs during attach.

detach

public byte[] detach(int mode)
              throws StreamsException

Detaches from an inbound server.
This API detaches the client from the XStream inbound server.

Parameters:

mode - The mode of XStream inbound server (for future extension). Use XStreamIn.DEFAULT_MODE for now.

Returns:

the inbound server's processed low watermark.

Throws:

StreamsException - if error occurs during detach.

sendLCRCallback

public void sendLCRCallback(XStreamLCRCallbackHandler handler,
                            int mode)
                     throws StreamsException

Sends a stream of LCRs in callback mode.
This API starts sending an LCR stream to the specified XStream inbound server using callback mode. You must supply an LCR callback handler that uses the createLCR() and createChunk() callback methods. See XStreamLCRCallbackHandler for details about the LCR callback handler.
To reduce network roundtrip overhead, this method also starts a batch process that sends LCRs to the inbound server. The batch process is stopped after 30 seconds or when a NULL LCR is returned in the createLCR() callback method.

Parameters:

handler - The XStreamLCRCallbackHandler for constructing LCRs.

mode - The mode of XStream inbound server (for future extension). Use XStreamIn.DEFAULT_MODE for now.

Throws:

StreamsException - if error occurs during the batch.

sendLCR

public int sendLCR(LCR lcr,
                   int mode)
            throws StreamsException

Sends one LCR in non-callback mode.
This method sends one LCR to the connected inbound server. To avoid a network round trip for each SendLCR call, XStreamIn starts a batch process internally to fill the network buffer with LCRs. This batch process is stopped after 30 seconds has elapsed.
This method returns a batch status value of either EXECUTING or FINISHED. Note that when a RowLCR has chunkDataFlag set, the return status is always EXECUTING.

Parameters:

lcr - A constructed LCR.

Returns:

The XStreamIn batch processing status.

Throws:

StreamsException - if the LCR is NULL or invalid, or error occurs while sending the LCR.

sendChunk

public void sendChunk(ChunkColumnValue chunk,
                      int mode)
               throws StreamsException

Sends chunk data in non-callback mode.
This API sends streaming LOB, LONG, and XMLTYPE chunk data.
Call this API after calling sendLCR() to send chunk data for an LCR. Ensure that all of the chunks for one LOB column are sent before sending the chunks for another LOB column. The LOB columns can be sent in any order.
Use setLastChunk() in chunkColumnValue to indicate whether the current chunk is the last chunk for a column. Use setEndOfRow() in chunkColumnValue to indicate whether the current chunk is the last chunk for an entire row change.

Parameters:

chunk - A ChunkColumnValue object that contains the chunk data for the LOB, LONG, or XMLTYPE column in a RowLCR

mode - The mode of XStream inbound server (for future extension). Use XStreamIn.DEFAULT_MODE for now.

Throws:

StreamsException - if error occurs while sending chunk data.

getProcessedLowWatermark

public byte[] getProcessedLowWatermark()

Gets the processed low watermark.
Use this method to get the inbound server's processed low watermark. After attaching to an XStream inbound server, the client caches a local copy of the inbound server's processed low watermark. Each of the following calls refreshes the local copy with the inbound server's processed low watermark and returns the FINISHED batch status from sendLCR:

    attach 
    sendLCR
    sendLCRCallback
    flush
 

This method can be called while the client is attached to an XStream inbound server.

Returns:

The inbound server's processed low watermark.

getOldestPosition

public byte[] getOldestPosition()

Gets the oldest position.
Use this method to get the inbound server's oldest position. After attaching to an XStream inbound server, the client caches a local copy of the inbound server's oldest position. Each of the following calls refreshes the local copy with the inbound server's oldest position and returns the FINISHED batch status from sendLCR:

    attach 
    sendLCR
    flush
 

This method can be called while the client is attached to an XStream inbound server.

Returns:

The inbound server's processed low watermark.

getLastPosition

public byte[] getLastPosition()

Gets last position.
This method gets the inbound server's last position after an attach call. After attaching to an XStream inbound server, this method retrieves the inbound server's last position and sends it to the client. The client can use this last position to decide where to stream LCRs. Ensure that this method is called after successfully attaching to an XStream inbound server.

Returns:

The inbound server's processed low watermark.

flush

public void flush(int mode)
           throws StreamsException

Flushes the network.
This method flushes the network while attaching to an XStream inbound server. Ensure that this method is called only when there are no LCRs to send to the inbound server and the client needs to determine the progress of the inbound server.
It terminates any in-progress batch processing and should not called in callback mode.
This method contacts the inbound server to get the inbound server's processed low watermark. The getProcessedLowWatermark() method can retrieve the processed low watermark.

Parameters:

mode - The mode of XStream inbound server (for future extension). Use XStreamIn.DEFAULT_MODE for now.

Throws:

StreamsException - if error occurs while flushing network.

Skip navigation links