Oracle® Data Provider for .NET Developer's Guide 10g Release 2 (10.2) Part Number B14307-01 |
|
|
View PDF |
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.
See Also:
OracleXmlType
members are listed in the following tables:
OracleXmlType Constructors
The OracleXmlType
constructors are listed in Table 6-19.
Table 6-19 OracleXmlType Constructors
Constructor | Description |
---|---|
OracleXmlType Constructors | Creates an instance of the OracleXmlType class (Overloaded) |
OracleXmlType Static Methods
The OracleXmlType
static methods are listed in Table 6-20.
Table 6-20 OracleXmlType Static Methods
Methods | Description |
---|---|
Equals |
Inherited from Object (Overloaded) |
OracleXmlType Instance Properties
The OracleXmlType
instance properties are listed in Table 6-21.
Table 6-21 OracleXmlType Instance Properties
Properties | Description |
---|---|
Connection | Indicates the OracleConnection that is used to retrieve and store XML data in the OracleXmlType |
IsEmpty | Indicates whether or not the OracleXmlType is empty |
IsFragment | Indicates whether the XML data is a collection of XML elements or a well-formed XML document |
IsSchemaBased | Indicates whether or not the XML data represented by the OracleXmlType is based on an XML schema |
RootElement |
Represents the name of the top-level element of the schema-based XML data contained in the OracleXmlType |
Schema |
Represents the XML schema of the XML data contained in the OracleXmlType |
SchemaUrl |
Represents in the database for the XML schema of the XML data contained in the OracleXmlType . |
Value |
Returns the XML data starting from the first character in the current instance as a string |
OracleXmlType Instance Methods
The OracleXmlType
instance methods are listed in Table 6-22.
Table 6-22 OracleXmlType Instance Methods
Methods | Description |
---|---|
Clone | Creates a copy of the OracleXmlType instance |
Dispose | Releases the resources allocated by this OracleXmlType object |
Equals |
Inherited from Object |
Extract | Extracts a subset from the XML data using the given XPath expression (Overloaded) |
GetHashCode |
Inherited from Object |
GetStream | Returns an instance of OracleXmlStream which provides a read-only stream of the XML data stored in this OracleXmlType instance |
GetType |
Inherited from Object |
GetXmlDocument | Returns a XmlDocument object containing the XML data stored in this OracleXmlType instance |
GetXmlReader | Returns a XmlTextReader object that can be used to manipulate XML data directly using the .NET Framework classes and methods |
IsExists | Checks for the existence of a particular set of nodes identified by the given XPath expression in the XMLdata (Overloaded) |
ToString |
Inherited from Object |
Transform | Transforms the OracleXmlType into another OracleXmlType instance using the given XSL document (Overloaded) |
Update | Updates the XML node or fragment identified by the given XPath expression in the current OracleXmlType instance (Overloaded) |
Validate |
Validates whether or not the XML data in the OracleXmlType object conforms to the given XML schema. |
OracleXmlType
constructors create instances of the OracleXmlType
class.
Overload List:
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.
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.
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.
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.
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.
The OracleXmlType
static methods are listed in Table 6-23.
Table 6-23 OracleXmlType Static Methods
Methods | Description |
---|---|
Equals |
Inherited from Object (Overloaded) |
The OracleXmlType
instance properties are listed in Table 6-24.
Table 6-24 OracleXmlType Instance Properties
Properties | Description |
---|---|
Connection |
Indicates the OracleConnection that is used to retrieve and store XML data in the OracleXmlType |
IsEmpty |
Indicates whether or not the OracleXmlType is empty |
IsFragment |
Indicates whether the XML data is a collection of XML elements or a well-formed XML document |
IsSchemaBased |
Indicates whether or not the XML data represented by the OracleXmlType is based on an XML schema |
RootElement |
Represents the name of the top-level element of the schema-based XML data contained in the OracleXmlType |
Schema |
Represents the XML schema of the XML data contained in the OracleXmlType |
SchemaUrl |
Represents URL in the database for the XML schema of the XML data contained in the OracleXmlType |
Value |
Returns the XML data starting from the first character in the current instance as a string |
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
.
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.
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.
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.
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.
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.
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.
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.
The OracleXmlType
instance methods are listed in Table 6-25.
Table 6-25 OracleXmlType Instance Methods
Methods | Description |
---|---|
Clone | Creates a copy of the OracleXmlType instance |
Dispose | Releases the resources allocated by this OracleXmlType object |
Equals |
Inherited from Object |
Extract | Extracts a subset from the XML data using the given XPath expression (Overloaded) |
GetHashCode |
Inherited from Object |
GetStream | Returns an instance of OracleXmlStream which provides a read-only stream of the XML data stored in this OracleXmlType instance |
GetType |
Inherited from Object |
GetXmlDocument | Returns a XmlDocument object containing the XML data stored in this OracleXmlType instance |
GetXmlReader | Returns a XmlTextReader object that can be used to manipulate XML data directly using the .NET Framework classes and methods |
IsExists | Checks for the existence of a particular set of nodes identified by the given XPath expression in the XMLdata (Overloaded) |
ToString |
Inherited from Object |
Transform | Transforms the OracleXmlType into another OracleXmlType instance using the given XSL document (Overloaded) |
Update | Updates the XML node or fragment identified by the given XPath expression in the current OracleXmlType instance (Overloaded) |
Validate |
Validates whether or not the XML data in the OracleXmlType object conforms to the given XML schema. |
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.
This method releases the resources allocated by this object.
Declaration
// C# public void Dispose();
Implements
IDisposable
This method extracts a subset from the XML data using the given XPath expression.
Overload List:
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.
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.
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.
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.
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
.
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
checks for the existence of a particular set of nodes identified by the XPath expression in the XML data.
Overload List:
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.
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.
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.
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.
This public method transforms the current OracleXmlType
instance into another OracleXmlType
instance using the given XSL document and a string of XSLT parameters.
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.
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.
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.
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.
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.
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.
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.
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.