| Oracle® Database XStream Guide 11g Release 2 (11.2) Part Number E15874-01 |
|
|
View PDF |
| Oracle® Database XStream Guide 11g Release 2 (11.2) Part Number E15874-01 |
|
|
View PDF |
The Oracle Call Interface (OCI) includes an interface for XStream. This chapter provides an introduction to the OCI interface for XStream.
This chapter contains these topics:
See Also:
Since Oracle Database 11g Release 2, Oracle Streams provides enhanced APIs, known as eXtended Streams (XStream) Out and XStream In, to enable high performance, near real-time information-sharing infrastructure between Oracle databases and non-Oracle databases, non-RDBMS Oracle products, file systems, third party software applications, and so on.
XStream is built on top of Streams infrastructure.
See Also:
Chapter 12, "OCI XStream Functions"XStream Out allows a remote client to attach to an outbound server (a Streams apply process) and extract row changes in the form of Logical Change Records (LCRs). For the basics of LCRs:
To use XStream Out, a capture and an apply process must be created similar to other Streams setup. All data types supported by Oracle Streams including LOB, LONG, and XMLType are supported by XStream. Such an apply process is called an outbound server. The capture and the outbound server may or may not be on the same database instance. After the capture and the outbound server have started, row changes will be captured and sent to the outbound server. An external client can then connect to this outbound server using OCI. After the connection is established, the client can loop waiting for LCRs from the outbound server. The client can register a client-side callback to be invoked each time an LCR is received. At anytime, the client can detach from the outbound server as needed. Upon restart, the outbound server knows where in the redo stream to start streaming LCRs to the client.
See Also:
Chapter 1, "XStream Concepts" for more details of XStream conceptsAn LCR stream must be repeatable.
An LCR stream must contain a list of assembled and committed transactions.
LCRs from one transaction are contiguous. There is no interleaving of transactions in the LCR stream.
Each transaction within an LCR stream must have an ordered list of LCRs and a transaction ID.
The last LCR in each transaction must be a commit LCR.
Each LCR must have a unique position.
The position of all LCRs within a single transaction and across transactions must be strictly increasing.
If the outbound server or the client aborts abnormally, the connection between the two is automatically broken. The client must maintain the processed low position to properly recover after a restart.
The processed low position is a position below which all LCRs have been processed by the client. This position should be maintained by the client while applying each transaction. Periodically this position is sent to the server while the client executes XStream Out APIs. This position indicates to the server that the client has processed all LCRs below or equal to this position; thus, the server can purge redo logs that are no longer needed.
Upon restart, the client must re-attach to the outbound server. During the attach call, the client can notify the outbound server of the last position received by the client. The outbound server then sends LCRs with position greater than this last position. If the client does not specify the last position (that is, a NULL is specified), the outbound server will retrieve the processed low position from its system tables and derive the starting position to mine the redo logs. It will send to the client the LCRs with position greater than this processed low position.
To replicate non-Oracle data into Oracle databases use XStream In which allows a remote client to attach to an inbound server (a Streams apply process) and send row and DDL changes in the form of LCRs.
An external client application connects to the inbound server using OCI. After the connection is established, the client application acts as the capture agent for the inbound server by streaming LCRs to it. A client application can attach to only one inbound server per database connection. Each inbound server only allows one client attaching to it.
XStream In uses the following features of Oracle Streams:
High performance processing of DML changes using an apply process and, optionally, apply process parallelism.
Apply process features such as SQL generation, conflict detection and resolution, error handling, and customized processing with apply handlers.
Streaming network transmission of information with minimal network round trips.
XStream In supports all of the data types that are supported by Oracle Streams, including LOBs, LONG, LONG RAW, and XMLType. A client application sends LOB and XMLType data to the inbound server in chunks. Several chunks comprise a single column value of LOB or XMLType.
The processed low position is the position below which the inbound server no longer requires any LCRs. This position corresponds with the oldest SCN for an Oracle Streams apply process that applies changes captured by a capture process.
The processed low position indicates that the LCRs less than or equal to this position have been processed by the inbound server. If the client re-attaches to the inbound server, it only needs to send LCRs greater than the processed low position because the inbound server discards any LCRs that are less than or equal to the processed low position.
If the client application aborts abnormally, then the connection between the client application and the inbound server is automatically broken. Upon restart, the client application retrieves the processed low position from the inbound server and instructs its capture agent to retrieve changes starting from this processed low position.
To limit the recovery time of a client application using the XStream In interface, the client application can send activity, such as empty transactions, periodically to the inbound server. When there are no LCRs to send to the server, the client can send a row LCR with a commit directive to advance the inbound server's processed low position. This activity acts as an acknowledgment so that the inbound server's processed low position can be advanced. The LCR stream sent to an inbound server must follow the LCR stream properties for XStream Out defined above.
Stream position refers to the position of an LCR in a given LCR stream.
For transactions captured outside Oracle databases the stream position must be encoded in certain format (for example, base-16 encoding) that supports byte comparison. The stream position is key to the total order of transaction stream sent by clients using the XStream In interface.
XStream Out allows regular users to receive LCRs without requiring system level privileges. System level privileges, such as DBA role, are required to configure XStream Out. The user who configures XStream Out can specify a regular user as the connect user who can attach to an outbound server to receive LCRs.
See Also:
Chapter 3, "Configuring XStream" for more about configuring XStreamXStream In allows regular users to update tables in its own schema without requiring system level privileges (for example, DBA) to configure XStream In.
XStream cannot assume that the connected user to the inbound or outbound server is trusted.
OCI clients must connect to an Oracle database before attaching to an XStream outbound or inbound server created on that database. The connected user must be the same as the connect_user configured for the attached outbound server or the apply_user configured for the attached inbound server; otherwise, an error is raised.
XStream Out implicitly converts character data in logical change records (LCRs) from the outbound database character set to the client application character set. XStream In implicitly converts character data in LCRs from the client application character set to the inbound database character set. To improve performance, analyze the LCR data flow from the source to the destination, and set the client character set of the OCI client application to the one that minimizes character conversion, incurs no data loss, and takes advantage of the implicit conversion done by XStream or the destination. For XStream Out, in general, setting the client application character set to the outbound database character set is the best practice.
This appendix describes the attributes for OCI handles and descriptors, which can be read with OCIAttrGet(), and modified with OCIAttrSet().
For each handle type, the attributes which can be read or changed are listed. Each attribute listing includes the following information:
The following modes are valid:
READ - the attribute can be read using OCIAttrGet()
WRITE - the attribute can be modified using OCIAttrSet()
READ/WRITE - the attribute can be read using OCIAttrGet(), and it can be modified using OCIAttrSet().
This is a description of the purpose of the attribute.
This is the data type of the attribute. If necessary, a distinction is made between the data type for READ and WRITE modes.
The following server handle attributes are available:
READ/WRITE
For XStream Out, the ACK interval is the minimum interval in seconds that the outbound server receives the processed low position from the client. After each ACK interval, the outbound server ends any in-progress OCIXStreamOutLCRReceive() or OCIXStreamOutLCRCallbackReceive() call so that the processed low position cached at the client can be sent to the server.
For XStream In, the ACK interval is the minimum interval in seconds that the inbound server sends the processed low position to the client. After each ACK interval, any in-progress OCIXStreamInLCRSend() or OCIXStreamInLCRCallbackSend() call is terminated for the inbound server to send a new processed low position to the client.
The default value for OCI_ATTR_XSTREAM_ACK_INTERVAL is 30 seconds. This attribute is checked only during the OCIXStreamOutAttach() or OCIXStreamInAttach() calls. Thus, it must be set before invoking these APIs; otherwise, the default value is used.
ub4 */ub4
READ/WRITE
The idle timeout is the number of seconds of idle the outbound server waits for an LCR before terminating the OCIXStreamOutLCRReceive() or OCIXStreamOutLCRCallbackReceive() call.
The default for OCI_ATTR_XSTREAM_IDLE_TIMEOUT is one second. This attribute is checked only during the OCIXStreamOutAttach() or OCIXStreamInAttach() call. Thus, it must be set before invoking these APIs; otherwise, the default value is used.
ub4 */ub4
|
 Copyright © 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
