OracleXmlType Class

An OracleXmlType object represents an Oracle XMLType instance.

Class Inheritance

Object

  OracleXmlType

Declaration

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

Thread Safety

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

Remarks

OracleXmlType objects can be used for well-formed XML documents with or without XML schemas or XML fragments.

Requirements

Namespace: Oracle.DataAccess.Types

Assembly: Oracle.DataAccess.dll

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

---

OracleXmlType Members

OracleXmlType members are listed in the following tables:

OracleXmlType Constructors

The OracleXmlType constructors are listed in Table 6-19.

OracleXmlType Static Methods

The OracleXmlType static methods are listed in Table 6-20.

OracleXmlType Instance Properties

The OracleXmlType instance properties are listed in Table 6-21.

OracleXmlType Instance Methods

The OracleXmlType instance methods are listed in Table 6-22.

---

OracleXmlType Constructors

OracleXmlType constructors create instances of the OracleXmlType class.

Overload List:

• OracleXmlType(OracleClob)

  This constructor creates an instance of the OracleXmlType class using the XML data contained in an OracleClob object.

• OracleXmlType(OracleConnection, string)

  This constructor creates an instance of the OracleXmlType class using the XML data contained in the .NET String.

• OracleXmlType(OracleConnection, XmlReader)

  This constructor creates an instance of the OracleXmlType class using the contents of the .NET XmlReader object.

• OracleXmlType(OracleConnection, XmlDocument)

  This constructor creates an instance of the OracleXmlType object using the contents of the XML DOM document in the .NET XmlDocument object.

OracleXmlType(OracleClob)

This constructor creates an instance of the OracleXmlType class using the XML data contained in an OracleClob object.

Declaration

// C#
public OracleXmlType(OracleClob oraClob);

Parameters

• oraClob

  An OracleClob object.

Exceptions

ArgumentNullException - The OracleClob object is null.

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

Remarks

The CLOB data depends on a valid connection object and the new OracleXMLType uses the OracleConnection in the OracleClob object to store data for the current instance.

OracleXmlType(OracleConnection, string)

This constructor creates an instance of the OracleXmlType class using the XML data contained in the .NET String.

Declaration

// C#
public OracleXmlType(OracleConnection con, string xmlData);

Parameters

• con

  An OracleConnection object.

• xmlData

  A string containing the XML data.

Exceptions

ArgumentNullException - The OracleConnection object is null.

ArgumentException - The xmlData argument is an empty string.

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

Remarks

The new OracleXmlType uses the given OracleConnection object to store data for the current instance.

OracleXmlType(OracleConnection, XmlReader)

This constructor creates an instance of the OracleXmlType class using the contents of the .NET XmlReader object.

Declaration

// C#
public OracleXmlType(OracleConnection con, XmlReader reader);

Parameters

• con

  An OracleConnection object.

• reader

  An XmlReader object.

Exceptions

ArgumentNullException - The OracleConnection object is null.

ArgumentException - The reader argument contains no data.

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

Remarks

The new OracleXMLType uses the given OracleConnection object to store data for the current instance.

OracleXmlType(OracleConnection, XmlDocument)

This constructor creates an instance of the OracleXmlType object using the contents of the XML DOM document in the .NET XmlDocument object.

Declaration

// C#
public OracleXmlType(OracleConnection con, XmlDocument domDoc);

Parameters

• con

  An OracleConnection object.

• domDoc

  An XML document.

Exceptions

ArgumentNullException - The OracleConnection object is null.

ArgumentException - The domDoc argument contains no data.

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

Remarks

The new OracleXMLType uses the given OracleConnection object to store data for the current instance.

---

OracleXmlType Static Methods

The OracleXmlType static methods are listed in Table 6-23.

---

OracleXmlType Instance Properties

The OracleXmlType instance properties are listed in Table 6-24.

Connection

This property indicates the OracleConnection that is used to retrieve and store XML data in the OracleXmlType.

Declaration

// C#
public OracleConnection Connection {get;}

Property Value

An OracleConnection object.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

The connection must explicitly be opened by the user before creating or using OracleXmlType.

IsEmpty

This property indicates whether or not the OracleXmlType is empty.

Declaration

// C#
public bool IsEmpty {get;}

Property Value

Returns true if the OracleXmlType represents an empty XML document. Returns false otherwise.

Exceptions

ObjectDisposedException - The object is already disposed.

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

IsFragment

This property indicates whether the XML data is a collection of XML elements or a well-formed XML document.

Declaration

// C#
public bool IsFragment {get;}

Property Value

Returns true if the XML data contained in the OracleXmlType object is a collection of XML elements with no root element. Returns false otherwise.

Exceptions

ObjectDisposedException - The object is already disposed.

IsSchemaBased

This property indicates whether or not the XML data represented by the OracleXmlType is based on an XML schema.

Declaration

// C#
public bool IsSchemaBased {get;}

Property Value

Returns true if the XML data represented by the OracleXmlType is based on an XML schema. Returns false otherwise.

Exceptions

ObjectDisposedException - The object is already disposed.

RootElement

This property represents the name of the top-level or root element of the schema-based XML data contained in the OracleXmlType.

Declaration

// C#
public string RootElement{get;}

Property Value

A string that represents the name of the top-level or root element of the XML data contained in the OracleXmlType.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

If the OracleXmlType instance contains non-schema based XML data, this property returns an empty string.

Schema

This property represents the XML schema for the XML data contained in the OracleXmlType.

Declaration

// C#
public OracleXmlType Schema {get;}

Property Value

An OracleXmlType instance that represents the XML schema for the XML data contained in the OracleXmlType.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

If the OracleXmlType instance contains non-schema based XML data, this property returns an OracleXmlType instance representing an empty XML document.

SchemaUrl

This property represents the XML schema in the database for the XML schema of the XML data contained in the OracleXmlType.

Declaration

// C#
public string SchemaUrl {get;}

Property Value

A string that represents the URL in the database for the XML schema of the XML data.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

If the OracleXmlType instance contains non-schema based XML data, this property returns an empty string.

Value

This property returns the XML data starting from the first character in the current instance as a string.

Declaration

// C#
public string RootElement{get;}

Property Value

The entire XML data as 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.

---

OracleXmlType Instance Methods

The OracleXmlType instance methods are listed in Table 6-25.

Clone

This method creates a copy of this OracleXmlType instance.

Declaration

// C#
public object Clone();

Implements

ICloneable

Return Value

An OracleXmlType object.

Exceptions

ObjectDisposedException - The object is already disposed.

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

Dispose

This method releases the resources allocated by this object.

Declaration

// C#
public void Dispose();

Implements

IDisposable

Extract

This method extracts a subset from the XML data using the given XPath expression.

Overload List:

• Extract(string, string)

  This method extracts a subset from the XML data represented by the OracleXmlType object using the given XPath expression and a string parameter for namespace resolution.

• Extract(string, XmlNameSpaceManager)

  This method extracts a subset from the XML data represented by the OracleXmlType object, using the given XPath expression and a .NET XmlNameSpaceManager object for namespace resolution.

Extract(string, string)

This method extracts a subset from the XML data represented by the OracleXmlType object using the given XPath expression and a string parameter for namespace resolution.

Declaration

// C#
public OracleXmlType Extract(string xpathExpr, string nsMap);

Parameters

• xpathExpr

  The XPath expression.

• nsMap

  The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null. For example:

  xmlns:nsi"=http://www.company1.com" xmlns:nsz="http://www.company2.com"
  
  

Return Value

An OracleXmlType object.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xpathExpr is null or zero-length.

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

Extract(string, XmlNameSpaceManager)

This public method extracts a subset from the XML data represented by the OracleXmlType object, using the given XPath expression and a .NET XmlNameSpaceManager object for namespace resolution.

Declaration

// C#
public OracleXmlType Extract(string xpathExpr, XmlNameSpaceManager nsMgr);

Parameters

• xpathExpr

  The XPath expression.

• nsMgr

  The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null.

Return Value

An OracleXmlType.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xpathExpr is null or zero-length.

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

Remarks

The default namespace is ignored if its value is an empty string.

GetStream

This public method returns an instance of OracleXmlStream which provides a read-only stream of the XML data stored in this OracleXmlType instance.

Declaration

// C#
public Stream GetStream();

Return Value

A Stream object.

Exceptions

ObjectDisposedException - The object is already disposed.

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

GetXmlDocument

This public method returns a XmlDocument object containing the XML data stored in this OracleXmlType instance.

Declaration

// C#
public XmlDocument GetXmlDocument();

Return Value

An XmlDocument object.

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 XML data in the XmlDocument object is a copy of the XML data in the OracleXmlType instance and modifying it does not automatically modify the XML data in the OracleXmlType instance. The XmlDocument instance returned has the PreserveWhitespace property set to true.

GetXmlReader

This public method returns a XmlTextReader object that can be used to manipulate XML data directly using the .NET Framework classes and methods.

Declaration

// C#
public XmlTextReader GetXmlReader();

Return Value

An XmlTextReader object.

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 XmlTextReader is a read-only, forward-only representation of the XML data stored in the OracleXmlType instance.

IsExists

IsExists checks for the existence of a particular set of nodes identified by the XPath expression in the XML data.

Overload List:

• IsExists(string, string)

  This method checks for the existence of a particular set of nodes identified by the XPath expression in the XML data represented by the current OracleXmlType instance using a string parameter for namespace resolution.

• IsExists(string, XmlNameSpaceManager)

  This method checks for the existence of a particular set of nodes identified by the XPath expression in the XML document represented by the current OracleXmlType instance using a .NET XmlNameSpaceManager object for namespace resolution.

IsExists(string, string)

This method checks for the existence of a particular set of nodes identified by the XPath expression in the XML data represented by the current OracleXmlType instance using a string parameter for namespace resolution.

Declaration

// C#
public bool IsExists(string xpathExpr, string nsMap);

Parameters

• xpathExpr

  The XPath expression.

• nsMap

  The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null.

Return Value

Returns true if the required set of nodes exists; otherwise, returns false.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xpathExpr is null or zero-length.

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

Remarks

The default namespace is ignored if its value is an empty string.

IsExists(string, XmlNameSpaceManager)

This method checks the existence of a particular set of nodes identified by the XPath expression in the XML document represented by the current OracleXmlType instance using a .NET XmlNameSpaceManager object for namespace resolution.

Declaration

// C#
public bool IsExists(string xpathExpr, XmlNameSpaceManager nsMgr);

Parameters

• xpathExpr

  The XPath expression.

• nsMgr

  The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null.

Return Value

Returns true if the required set of nodes exists; otherwise, returns false.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xpathExpr is null or zero-length.

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

Remarks

The default namespace is ignored if its value is an empty string.

Transform

This method transforms the OracleXmlType into another OracleXmlType instance using the given XSL document.

Overload List:

• Transform(OracleXmlType, string)

  This method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document (as an OracleXmlType object) and a string of XSLT parameters.

• Transform(string, string)

  This public method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document and a string of XSLT parameters.

Transform(OracleXmlType, string)

This method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document and a string of XSLT parameters.

Declaration

// C#
public OracleXmlType Transform(OracleXmlType xsldoc, string paramMap);

Parameters

• xsldoc

  The XSL document as an OracleXmlType object.

• paramMap

  A string which provides the parameters for the XSL document.

  For this release, paramMap is ignored.

Return Value

An OracleXmlType object containing the transformed XML document.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xsldoc parameter is null.

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

Transform(string, string)

This method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document and a string of XSLT parameters.

Declaration

// C#
public OracleXmlType Transform(string xsldoc, string paramMap);

Parameters

• xsldoc

  The XSL document to be used for XSLT.

• paramMap

  A string which provides the parameters for the XSL document.

  For this release, paramMap is ignored.

Return Value

An OracleXmlType object containing the transformed XML document.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xsldoc parameter is null.

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

Update

This method updates the XML node or fragment identified by the given XPath expression in the current OracleXmlType instance.

Overload List:

• Update(string, string, string)

  This method updates the XML nodes identified by the given XPath expression with the given string value and a string parameter for namespace resolution.

• Update(string, XmlNameSpaceManager, string)

  This method updates the XML nodes identified by the given XPath expression with the given string value and a .NET XmlNameSpaceManager object for namespace resolution.

• Update(string, string, OracleXmlType)

  This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a string parameter for namespace resolution.

• Update(string, XmlNameSpaceManager, OracleXmlType)

  This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a .NET XmlNameSpaceManager object for namespace resolution.

Update(string, string, string)

This method updates the XML nodes identified by the given XPath expression with the given string value and a string parameter for namespace resolution.

Declaration

// C#
public void Update(string xpathExpr, string nsMap, string value);

Parameters

• xpathExpr

  The XPath expression that identifies the nodes to update.

• nsMap

  The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null. For example:

  xmlns:nsi"=http://www.company1.com" xmlns:nsz="http://www.company2.com"
  
  

• value

  The new value as a string.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xpathExpr is null or zero-length.

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

Remarks

The default namespace is ignored if its value is an empty string.

Update(string, XmlNameSpaceManager, string)

This method updates the XML nodes identified by the given XPath expression with the given string value and a .NET XmlNameSpaceManager object for namespace resolution.

Declaration

// C#
public void Update(string xpathExpr, XmlNameSpaceManager nsMgr, string
  value);

Parameters

• xpathExpr

  The XPath expression that identifies the nodes to update.

• nsMgr

  The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null.

• value

  The new value as a string.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xpathExpr is null or zero-length.

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

Remarks

The default namespace is ignored if its value is an empty string.

Update(string, string, OracleXmlType)

This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a string parameter for namespace resolution.

Declaration

// C#
public void Update(string xpathExpr, string nsMap, OracleXmlType value);

Parameters

• xpathExpr

  The XPath expression that identifies the nodes to update.

• nsMap

  The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null.

• value

  The new value as an OracleXmlType object.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xpathExpr is null or zero-length.

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

Remarks

The default namespace is ignored if its value is an empty string.

Update(string, XmlNameSpaceManager, OracleXmlType)

This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a .NET XmlNameSpaceManager object for namespace resolution.

Declaration

// C#
public void Update(string xpathExpr, XmlNameSpaceManager nsMgr, OracleXmlType     value);

Parameters

• xpathExpr

  The XPath expression that identifies the nodes to update.

• nsMgr

  The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null.

• value

  The new value as an OracleXmlType object.

Exceptions

ObjectDisposedException - The object is already disposed.

ArgumentNullException - The xpathExpr is null or zero-length.

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

Remarks

The default namespace is ignored if its value is an empty string.

Validate

This methods validates whether or not the XML data in the OracleXmlType object conforms to the given XML schema.

Declaration

// C#
public bool Validate(String schemaUrl);

Parameters

• schemaUrl

  A string representing the URL in the database of the XML schema.

Return Value

Returns true if the XML data conforms to the XML schema; otherwise, returns false.

Exceptions

ObjectDisposedException - The object is already disposed.

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

ArgumentNullException - The schemaUrl argument is null or an empty string.