OracleXmlStream Class

An OracleXmlStream object represents a read-only stream of XML data stored in an OracleXmlType object.

Class Inheritance

Object

  MarshalByRefObject

    Stream

      OracleXmlStream

Declaration

// C#
public sealed class OracleXmlStream : IDisposable, ICloneable

Thread Safety

All public static methods are thread-safe, although instance methods do not guarantee thread safety.

Requirements

Namespace: Oracle.DataAccess.Types

Assembly: Oracle.DataAccess.dll

This class can only be used with Oracle9i Release 2 (9.2) and later.

---

OracleXmlStream Members

OracleXmlStream members are listed in the following tables:

OracleXmlStream Constructors

The OracleXmlStream constructors are listed in Table 6-12.

OracleXmlStream Static Methods

The OracleXmlStream static methods are listed in Table 6-13.

OracleXmlStream Instance Properties

The OracleXmlStream instance properties are listed in Table 6-14.

OracleXmlStream Instance Methods

The OracleXmlStream instance methods are listed in Table 6-15.

---

OracleXmlStream Constructor

This constructor creates an instance of an OracleXmlStream object which provides a Stream representation of the XML data stored in an OracleXmlType object.

Declaration

// C#
public OracleXmlStream(OracleXmlType xmlType);

Parameters

• xmlType

  The OracleXmlType object.

Remarks

The OracleXmlStream implicitly uses the OracleConnection object from the OracleXmlType object from which it was constructed.

---

OracleXmlStream Static Methods

The OracleXmlStream static methods are listed in Table 6-16.

---

OracleXmlStream Instance Properties

The OracleXmlStream instance properties are listed in Table 6-17.

CanRead

Overrides Stream

This property indicates whether or not the XML stream can be read.

Declaration

// C#
public override bool CanRead{get;}

Property Value

If the XML stream is can be read, returns true; otherwise, returns false.

CanSeek

Overrides Stream

This property indicates whether or not forward and backward seek operation can be performed.

Declaration

// C#
public override bool CanSeek{get;}

Property Value

If forward and backward seek operations can be performed, this property returns true. Otherwise, returns false.

Connection

This instance property indicates the OracleConnection that is used to retrieve the XML data.

Declaration

// C#
public OracleConnection Connection {get;}

Property Value

An OracleConnection.

Exceptions

ObjectDisposedException - The object is already disposed.

Length

Overrides Stream

This property indicates the number of bytes in the XML stream.

Declaration

// C#
public override Int64 Length{get;}

Property Value

An Int64 value representing the number of bytes in the XML stream. An empty stream has a length of 0 bytes.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Position

Overrides Stream

This property gets or sets the byte position within the stream.

Declaration

// C#
public override Int64 Position{get; set;}

Property Value

An Int64 that indicates the current position in the stream.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

ArgumentOutOfRangeException - The Position is less than 0.

Remarks

The beginning of the stream is represented by position 0. Seeking to any location beyond the length of the stream is supported.

Value

This property returns the XML data, starting from the first character of the stream as a string.

Declaration

// C#
public string Value{get; set;}

Property Value

A string.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Remarks

The value of Position is neither used nor changed by using this property.

The maximum length of the string that can be returned by this property is 2 GB.

---

OracleXmlStream Instance Methods

The OracleXmlStream instance methods are listed in Table 6-18.

Clone

This method creates a copy of an OracleXmlStream object.

Declaration

// C#
public object Clone();

Return Value

An OracleXmlStream object.

Implements

ICloneable

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Remarks

The cloned object has the same property values as that of the object being cloned.

Close

Overrides Stream

This method closes the current stream and releases any resources associated with it.

Declaration

// C#
public override void Close();

Dispose

This public method releases resources allocated by this object.

Declaration

// C#
public void Dispose();

Implements

IDisposable

Remarks

The object cannot be reused after being disposed. Although some properties can still be accessed, their values cannot be accountable. Since resources are freed, method calls can lead to exceptions.

Read

This method reads a specified amount from the current XML stream instance and populates the array buffer.

Overload List:

• Read(byte[ ], int, int)

  This method reads a specified amount of unicode bytes from the current instance, advances the position within the stream, and populates the byte array buffer.

• Read(char[ ], int, int)

  This method reads a specified amount of characters from the current instance, advances the position within the stream, and populates the character array buffer.

Read(byte[ ], int, int)

Overrides Stream

This method reads a specified amount of unicode bytes from the current instance, advances the position within the stream, and populates the byte array buffer.

Declaration

// C#
public override int Read(byte[ ] buffer, int offset, int count);

Parameters

• buffer

  The byte array buffer that is populated.

• offset

  The zero-based offset (in bytes) at which the buffer is populated.

• count

  The maximum amount of bytes to be read.

Return Value

The number of unicode bytes read into the given byte[] buffer or 0 if the end of the stream has been reached.

Remarks

This method reads a maximum of count bytes from the current stream and stores them in buffer beginning at offset. The current position within the stream is advanced by the number of bytes read. However, if an exception occurs, the current position within the stream remains unchanged.

The XML data is read starting from the position specified by the Position property.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Read(char[ ], int, int)

Overrides Stream

This method reads a specified amount of characters from the current instance, advances the position within the stream, and populates the character array buffer.

Declaration

// C#
public override int Read(char[ ] buffer, int offset, int count);

Parameters

• buffer

  The character array buffer to be populated.

• offset

  The zero-based offset (in characters) in the buffer at which the buffer is populated.

• count

  The maximum amount of characters to be read from the stream.

Return Value

The return value indicates the number of characters read from the stream or 0 if the end of the stream has been reached.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Remarks

This method requires that the Position on the stream instance be zero or an even number.

The XML data is read starting from the position specified by the Position property.

Seek

Overrides Stream.

This method sets the position within the current stream and returns the new position within the current stream.

Declaration

// C#
public long Seek(long offset, SeekOrigin origin);

Parameters

• offset

  A byte offset relative to origin.

  • If offset is negative, the new position precedes the position specified by origin by the number of bytes specified by offset.

  • If offset is zero, the new position is the position specified by origin.

  • If offset is positive, the new position follows the position specified by origin by the number of bytes specified by offset.

• origin

  A value of type SeekOrigin indicating the reference point used to obtain the new position.

Return Value

The new Position within the current stream.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object

Remarks

Use the CanSeek property to determine whether or not the current instance supports seeking. Seeking to any location beyond the length of the stream is supported.