Skip Headers

Oracle9i XML Reference
Release 1 (9.0.1)

Part Number A88899-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

14
XML Support

This chapter contains reference document on the types and functions related to XML support in the server including:

DBMS_XMLGEN

The DBMS_XMLGEN is a package to convert the results of SQL queries to a canonical XML format. The package takes in any arbitrary SQL query and converts them into the XML format and returns the result as a CLOB.

The package is similar to the DBMS_XMLQuery package, except that it is written in C and compiled into the kernel. This package may only be run on the database.


Note:

DBMS_XMLGEN is a built-in package in C. In general, use DBMS_XMLGEN instead of DBMS_XMLQuery wherever possible. 


The package uses a canonical XML conversion. It does not support DTD or XMLSchema generation for now and these may be provided in later releases.

An example conversion is shown below:-

Assume an employee table with the following structure,

CREATE TABLE address_t AS OBJECT
(
   street VARCHAR2(20),
   state VARCHAR2(20),
   city VARCHAR2(20),
   zip   VARCHAR2(20)
);
/
CREATE TABLE employee 
(
  empno NUMBER,
  ename VARCHAR2(200),
  address address_t
);

insert into employee values (100,'John',
      address_t('100, Main Street','Jacksonville','FL','32607'));
insert into employee values (200,'Jack',
      address_t('200 Front Road','San Francisco','CA','94011'));

declare 
  ctx dbms_xmlgen.ctxhandle;
  result clob;
begin
  
   -- create a new context with the SQL query
   ctx := dbms_xmlgen.newContext('select * from employee');

   -- generate the CLOB as a result.
   res := dbms_xmlgen.getXML(ctx);

  -- print out the result of the CLOB
  printClobOut(result); -- see the lob manual for examples on printing..
  -- close the context
  dbms_xmlgen.closeContext(ctx);
end;
/

produces a document like,

<?xml version="1.0"?>
<ROWSET>
  <ROW>
    <EMPNO>100</EMPNO>
    <ENAME>John</ENAME>
    <ADDRESS>
      <STREET>100 Main Street</STREET>
      <CITY>Jacksonville</CITY>
      <STATE>FL</STATE>
      <ZIP>32607</ZIP>
    </ADDRESS>
  </ROW>
  <ROW>
    <EMPNO>200</EMPNO>
    <ENAME>Jack</ENAME>
    <ADDRESS>
      <STREET>200 Front Street</STREET>
      <CITY>San Francisco</CITY>
      <STATE>CA</STATE>
      <ZIP>94011</ZIP>
    </ADDRESS>
  </ROW>
</ROWSET>

As you can see from the example, each row of the result gets translated to a ROW element which contains all the columns. The columns themeselves are converted to nested elements with the column name as the element tag name. The object columns (such as address) retain their structure with the object type attributes becoming nested elements of the column.

Thus, deep structuring of the XML can be achieved easily using the object-relational views and tables.

DBMS_XMLGEN Procedures and Functions

The DBMS_XMLGEN package contains a variety of funtions to generate XML and to set the properties of the result.

The order of calling procedures are as follows

  1. Call newContext to get a new context handle given the SQL query.

  2. Call setRowTag or setRowSetTag to change the names of tags.

  3. Set the maxRows and skipRows if needed to change the number of rows fetched or skipped.

  4. Call getXML to get the XML value. You can call this repeatedly to obtain XML from the next set of rows.

  5. You can check if any rows were processed using the getNumRowsProcessed method.

  6. Call closeContext to close the context handle and release resources.

FUNCTION newContext(varchar2) RETURN ctxHandle

Creates a new context handle from a passed in SQL query. The context handle can be used for the rest of the functions.

PROCEDURE setRowTag(ctxHandle, varchar2);

Sets the name of the element enclosing each row of the result. The default tag is "ROW"

PROCEDURE setRowSetTag(ctxHandle, varchar2);

Sets the name of the element enclosing the entire result. The default tag is "ROWSET"

PROCEDURE getXML(ctxHandle, clob, number);

This appends the XML to the CLOB passed in. Use the getNumRowsProcessed function to figure out if any rows were appended.

FUNCTION getXML(ctxHandle, number) RETURN CLOB;

This returns the XML as a CLOB.

FUNCTION getXMLType(ctxHandle, number) RETURN sys.XMLType;

This returns the XML as an XMLType.

FUNCTION getNumRowsProcessed(ctxHandle) RETURN number;

This gets the number of SQL rows that were processed in the last call to getXML. You can call this to find out if the end of the result set has been reached.

PROCEDURE setMaxRows(ctxHandle, number);

This sets the maximum number of rows to be fetched each time.

PROCEDURE setSkipRows(ctxHandle, number);

This sets the number of rows to skip everytime before generating the XML. The default is 0.

PROCEDURE setConvertSpecialChars(ctxHandle, boolean);

This sets whether special characters such as $ etc.. which are non-XML characters should be converted or not to their escaped representation. The default is to perform the conversion.

PROCEDURE useItemTagsForColl(ctxHandle);

This forces the use of the collection column name appended with the tag "_ITEM" for collection elements. The default is to set the underlying object type name for the base element of the collection.

PROCEDURE restartQuery(ctx IN ctxHandle);

Restart the query to start fetching from the begining.

PROCEDURE closeContext(ctx IN ctxHandle);

Close the context and release all resources.

DBMS_XMLGEN Type definitons

SUBTYPE ctxHandle IS NUMBER

This is the context handle that is used by all functions.

DTD or schema specifications


Functions Prototypes

newContext()

PURPOSE

Given a query string, generate a new context handle to be used in subsequent functions.

SYNTAX

FUNCTION newContext(queryString IN VARCHAR2) RETURN ctxHandle; 

PARAMETERS

queryString  (IN)-  the query string, the result of which needs to be converted 
to XML 

RETURNS

The context handle

COMMENTS

You need to call this function first to obtain a handle that you can use in the getXML() and other functions to get the XML back from the result.

setRowTag()

PURPOSE

Set the name of the element separating all the rows. The default name is ROW.

SYNTAX

PROCEDURE setRowTag(ctx IN ctxHandle, rowTag IN VARCHAR2);

PARAMETERS

ctx (IN) - the context handle obtained from the newContext call
rowTag (IN) - the name of the ROW element. 
NULL indicates that you do not want the ROW element to be present.

COMMENTS

You can call this function to set the name of the ROW element, if you do not want the default "ROW" name to show up. You can also set this to NULL to supress the ROW element itself. However, this is an error if both the row and the rowset are null and there is more than one column or row in the output.

setRowSetTag()

PURPOSE

Set the name of the document's root element. The default name is "ROWSET"

SYNTAX

PROCEDURE setRowSetTag(ctx IN ctxHandle, rowSetTag IN VARCHAR2);

PARAMETERS

ctx (IN) - the context handle obtained from the newContext call
rowsetTag (IN) - the name of the document element. 
NULL indicates that you do not want the ROW element to be present.

COMMENTS

You can call this function to set the name of the document root element, if you do not want the default "ROWSET" name in the output. You can also set this to NULL to supress the printing of this element. However, this is an error if both the row and the rowset are null and there is more than one column or row in the output.

getXML()

PURPOSE

Get the XML document by fetching the maximum number of rows specified. It appends the XML document to the CLOB passed in.

SYNTAX

PROCEDURE getXML(ctx IN ctxHandle, clobval IN OUT NCOPY clob,  
dtdOrSchema IN number := NONE) 

PARAMETERS

ctx (IN) - The context handle obtained from the newContext() call.
clobval (IN/OUT) - the clob to which the XML document is to be appended.
dtdOrSchema (IN) - whether we should generate the Dtd or Schema or neither 
(NONE). NONE is the only option currently supported.

COMMENTS

Use this version of the getXML function, if you want to avoid any extra CLOB copies and you want to reuse the same CLOB for subsequent calls. The user must create the lob locator, but this is a one-time cost, and so it is recommended that users use this procedure whenever possible.

When generating the XML, the number of rows indicated by the setSkipRows call are skipped, then the maximum number of rows as specified by the setMaxRows call (or the entire result if not specified) is fetched and converted to XML.

Use the getNumRowsProcessed function to check if any rows were retrieved or not.

getXML()

PURPOSE

Generate the XML document and return that as a CLOB.

SYNTAX

FUNCTION getXML(ctx IN ctxHandle, dtdOrSchema IN number := NONE) RETURN clob

PARAMETERS

ctx (IN) - The context handle obtained from the newContext() call.
dtdOrSchema (IN) - whether we should generate the Dtd or Schema or neither 
(NONE). NONE is the only option currently supported.

RETURNS

A temporary CLOB containing the document.

COMMENTS

You need to free the temporary CLOB that is obtained from this function using the dbms_lob.freetemporary call.

getXMLType()

PURPOSE

Generate the XML document and return it as sys.XMLType.

SYNTAX

FUNCTION getXMLType(ctx IN ctxHandle, dtdOrSchema IN number := NONE) 
	RETURN sys.XMLType

PARAMETERS

ctx (IN) - The context handle obtained from the newContext() call.
dtdOrSchema (IN) - whether we should generate the Dtd or Schema or neither 
(NONE). NONE is the only option supported currently.

RETURNS

XML document as an XMLType

COMMENTS

Further XMLType operations can be done on the result, such as ExistsNode and Extract. This also provides a way to get the result back as string using getStringVal(), if the result size is known to be less than 4K.

getNumRowsProcessed()

PURPOSE

Get the number of SQL rows processed when generating the XML using the getXML call. This count does not include the number of rows skipped before generating the XML.

SYNTAX

FUNCTION getNumRowsProcessed(ctx IN ctxHandle) RETURN number

PARAMETERS

queryString  (IN)-  the query string, the result of which needs to be converted 
to XML 

RETURNS

The number of rows processed in the last call to getXML. This does not include the number of rows skipped.

COMMENTS

Use this function to determine the teminating condition if you are calling getXML in a loop. Note that getXML would always generate a XML document even if there are no rows present.

setMaxRows()

PURPOSE

Set the maximum number of rows to fetch from the SQL query result for every invokation of the getXML call.

SYNTAX

PROCEDURE setMaxRows(ctx IN ctxHandle, maxRows IN NUMBER); 

PARAMETERS

ctx (IN) - the context handle corresponding to the query executed
maxRows (IN) - the maximum number of rows to get per call to getXML

COMMENTS

The maxRows paramter can be used when generating paginated results using this utility. For instance when generating a page of XML or HTML data, you can restrict the number of rows converted to XML and then in subsequent calls, you can get the next set of rows and so on.

This also can provide for faster reponse times.

setSkipRows()

PURPOSE

Skip a given number of rows before generating the XML output for every call to the getXML routine.

SYNTAX

PROCEDURE setSkipRows(ctx IN ctxHandle, skipRows IN NUMBER); 

PARAMETERS

ctx (IN) - the context handle corresponding to the query executed
skipRows (IN) - the number of rows to skip per call to getXML

COMMENTS

The skipRows paramter can be used when generating paginated results for stateless web pages using this utility. For instance when generating the first page of XML or HTML data, you can set skipRows to zero. For the next set, you can set the skipRows to the number of rows that you got in the first case.

setConvertSpecialChars()

PURPOSE

Set whether special characters in the XML data need to be converted into their escaped XML equivalent or not. For example, the "<" sign is converted to &lt;. The default is to perform conversions.

SYNTAX

PROCEDURE setConvertSpecialChars(ctx IN ctxHandle, conv IN boolean); 

PARAMETERS

ctx (IN) - the context handle to use
conv (IN) - true indicates that conversion is needed.

COMMENTS

You can use this function to speed up the XML processing whenever you are sure that the input data cannot contain any special characters such as <, >, ", ' etc. which need to be escaped. Note that it is expensive to actually scan the character data to replace the special characters, particularly if it involves a lot of data. So in cases when the data is XML-safe, then this function can be called to improve performance.

useItemTagsForColl()

PURPOSE

Set the name of the collection elements. The default name for collection elements it he type name itself. You can override that to use the name of the column with the "_ITEM" tag appended to it using this function.

SYNTAX

PROCEDURE useItemTagsForColl(ctx IN ctxHandle); 

PARAMETERS

ctx (IN) - the context handle

COMMENTS

If you have a collection of NUMBER, say, the default tag name for the collection elements is NUMBER. You can override this behavior and generate the collection column name with the _ITEM tag appended to it, by calling this procedure.

restartQuery()

PURPOSE

Restart the query and generate the XML from the first row again.

SYNTAX

PROCEDURE restartQuery(ctx IN ctxHandle);

PARAMETERS

ctx (IN) - the context handle corresponding to the current query

COMMENTS

You can call this to start executing the query again, without having to create a new context.

closeContext()

PURPOSE

Closes a given context and releases all resources associated with that context, including the SQL cursor and bind and define buffers etc.

SYNTAX

PROCEDURE closeContext(ctx IN ctxHandle); 

PARAMETERS

ctx (IN) - the context handle to close

COMMENTS

Closes all resources associated with this handle. After this you cannot use the handle for any other DBMS_XMLGEN function call.

URI Support

Oracle9i supports the UriType family of types which can be used to store and query Uri-refs inside the database. The UriType itself is an abstract object type and the HttpUriType and DBUriType are subtypes of it.

You can create a UriType column and store instances of the DBUriType or the HttpUriType inside of it.

You can also define your own subtypes of the UriType to handle different URL protocols.

Oracle9i also provides a UriFactory package which can be used as a factory method to generate various instances of these UriTypes automatically by scanning the prefix (e.g.http:// or ftp:// etc..). You can also register your subtype and give the prefix that you support. For instance if you have written a subtype to handle the gopher protocol, you can register that the prefix "gopher://" be handled by your subtype. With that, the UriFactory will generate your subtype instance for any URL starting with that prefix.

UriType

The UriType is the abstract super type. It provides a standard set of functions to get the value pointed to by the Uri. The actual implementation of the protocol must be defined by the subtypes of this type.

You cannot create instances of this type directly. However, you can create columns of this type and store subtype instances in it.

For example,

create table uri_tab ( url sys.uritype);

insert into uri_tab values  
  (sys.httpuritype.createHttpuri('http://www.oracle.com'));
insert into uri_tab values (
   sys.dburitype.createdburi('/SCOTT/EMPLOYEE/ROW[ENAME="Jack"]'));

-- Now you can select from the column without having to know 
-- what instance of the URL is actually stored.
select e.url.getclob() from uri_tab e;

-- would retrieve both the HTTP URL and the DBUri-ref.


Member functions

MEMBER FUNCTION getClob() RETURN clob

This member function returns a CLOB by following the URL and getting the document.

MEMBER FUNCTION getExternalUrl() RETURN varchar2

Get the url stored in the external form, i.e. the non-Url characters such as spaces are escaped, using the standard escape sequence, %xx where xx is the hexadecimal value of the UTF-8 encoding of the character.

MEMBER FUNCTION getUrl() RETURN varchar2;

Returns the URL stored in the type without any escaping. This function must be used instead of directly referencing the url attribute in the type.


Function prototypes

getClob()

PURPOSE

Get the document pointed to by the URL as a CLOB. This function can be overridden in the subtype instances.

SYNTAX

MEMBER FUNCTION getClob() RETURN clob 

RETURNS

A temporary or permanent lob containing the document pointed to by the URL

COMMENTS

You need to free the clob if it is a temporary CLOB.

getExternalUrl()

PURPOSE

Get the URL stored inside the instance after escaping the non-URL characters as specified in the Uri-ref specification.

SYNTAX

MEMBER FUNCTION getExternalUrl() RETURN varchar2

COMMENTS

Generates the escaped URL that can be used in HTML web pages. The subtype instances override this member function to provide additional semantics. For instance, the HttpUriType does not store the prefix http:// in the Url itself. When generating the external Url, it appends the prefix and generates it. This is the reason that you should use the getExternalUrl or getUrl to get to the URL value instead of using the attribute present in the UriType.

getUrl()

PURPOSE

Get the URL stored inside the instance without escaping the non-URL characters.

SYNTAX

MEMBER FUNCTION getUrl() RETURN varchar2

COMMENTS

Generates the URL that is present in the UriType instance. The subtype instances override this member function to provide additional semantics. For instance, the HttpUriType does not store the prefix http:// in the Url itself. When generating the external Url, it appends the prefix and generates it. This is the reason that you should use the getExternalUrl or getUrl to get to the URL value instead of using the attribute present in the UriType.

HttpUritype

The HttpUriType is a subtype of the UriType that provides support for the HTTP protocol. This uses the UTL_HTTP package underneath to access the HTTP urls. This does not support the proxy or secure wallets for this release.

For example,

-- create a uri table to store the Http instances
create table uri_tab ( url sys.httpuritype);

-- insert the Http instance.
insert into uri_tab values 
    (sys.httpuritype.createUri('http://www.oracle.com'));

-- generate the HTML
select e.url.getclob() from uri_tab e;


Member functions

MEMBER FUNCTION getClob() RETURN clob

This member function returns a CLOB by following the HTTPURL and getting the document.

MEMBER FUNCTION getExternalUrl() RETURN varchar2

Get the HTTP url stored in the external form, i.e. the non-Url characters such as spaces are escaped, using the standard escape sequence, %xx where xx is the hexadecimal value of the UTF-8 encoding of the character.

MEMBER FUNCTION getUrl() RETURN varchar2;

Returns the URL stored in the type without any escaping. This function must be used instead of directly referencing the url attribute in the type.

STATIC FUNCTION createUri(url IN varchar2) RETURN HttpUriType

Static function to construct a HTTPUri instance.


Function prototypes

getClob()

PURPOSE

Get the document pointed to by the HTTP URL as a CLOB.

SYNTAX

MEMBER FUNCTION getClob() RETURN clob 

RETURNS

A temporary lob containing the document pointed to by the URL

COMMENTS

You need to free the temporary clob.

getExternalUrl()

PURPOSE

Get the URL stored inside the instance after escaping the non-URL characters as specified in the Uri-ref specification.

SYNTAX

MEMBER FUNCTION getExternalUrl() RETURN varchar2

COMMENTS

Generates the escaped URL that can be used in HTML web pages. The subtype instances override this member function to provide additional semantics. The HttpUriType does not store the prefix http:// in the Url itself. When generating the external Url, it appends the prefix and generates it.

getUrl()

PURPOSE

Get the URL stored inside the instance without escaping the non-URL characters.

SYNTAX

MEMBER FUNCTION getUrl() RETURN varchar2

COMMENTS

Generates the URL that is present in the HttpUri instance.

createUri()

PURPOSE

Static function to construct a Http URL instance.

SYNTAX

STATIC FUNCTION createUri(url IN varchar2) RETURN HttpUriType

PARAMETERS

url (IN) - the url string containing a valid HTTP URL. 
  The url string is assumed to be in the escaped form. i.e. non-url characters
  are represented as %xx where xx is the hexadecimal value for the 
  UTF-8 encoding of the character.

COMMENTS

Parses the Http URL supplied and generates a HttpUri instance. Note that this instance does not contain the prefix "http://" in the url stored.

DbUritype

The DbUriType is a subtype of the UriType that provides support for of DBUri-refs. A DBUri-ref is a intra-database URL that can be used to reference any row or row-column data in the database.

The URL is specified as an XPath expression over a XML visualization of the database. The schemas become elements which contain tables and views. These tables and view further contain the rows and columns inside them.

For example, the virtual document that a user scott can see can be something like this,

<?xml version="1.0"?>
<DATABASE>
  <SCOTT>
    <EMPLOYEE>
      <ROWSET>
         <ROW>
          <EMPNO>100</EMPNO>
          <ENAME>John</ENAME>
          <ADDRESS>
             <STREET>100 Main Street</STREET>
             <CITY>Jacksonville</CITY>
             <STATE>FL</STATE>
             <ZIP>32607</ZIP>
           </ADDRESS>
         </ROW>
         <ROW>
           <EMPNO>200</EMPNO>
           <ENAME>Jack</ENAME>
           <ADDRESS>
             <STREET>200 Front Street</STREET>
             <CITY>San Francisco</CITY>
             <STATE>CA</STATE>
             <ZIP>94011</ZIP>
           </ADDRESS>
         </ROW>
       </ROWSET>
     </EMPLOYEE>
   </SCOTT>
 </DATABASE>

Hence to reference the State attribute inside the employee table, you can formulate a DBUri-ref as shown below:-

/SCOTT/EMPLOYEE/ROW[ENAME="Jack"]/ADDRESS/STATE

You can use the DBUriType to create instances of these and store them in columns.

-- create a table
create table dburi_tab (dburl sys.dburitype);

-- insert values..!
insert into dburi_tab values (
 sys.dburitype.createdUri('/SCOTT/EMPLOYEE/ROW[ENAME="Jack"]/ADDRESS/STATE'));

select e.dburl.getclob() from dburi_tab e;

-- will return,
<?xml version="1.0"?>
<STATE>CA</STATE>

You can also generate the DBUri-ref dynamically using the SYS_DBURIGEN SQL function.

For example you can generate a DBuri-ref to the state attribute as shown below:-

select sys_dburigen(e.ename,e.address.state) AS urlcol
from scott.employee e;

Member functions

MEMBER FUNCTION getClob() RETURN clob

This member function returns a CLOB by following the DBUriType and getting the document.

MEMBER FUNCTION getExternalUrl() RETURN varchar2

Get the DbUri-ref stored in the external form, i.e. the non-Url characters such as spaces are escaped, using the standard escape sequence, %xx where xx is the hexadecimal value of the UTF-8 encoding of the character.

MEMBER FUNCTION getUrl() RETURN varchar2;

Returns the URL stored in the type without any escaping. This function must be used instead of directly referencing the url attribute in the type.

STATIC FUNCTION createUri(url IN varchar2) RETURN DbUriType

Static function to construct a DbUri instance.


Function prototypes

getClob()

PURPOSE

Get the document pointed to by the DBUri-ref

SYNTAX

MEMBER FUNCTION getClob() RETURN clob 

RETURNS

A temporary lob containing the document pointed to by the URL

COMMENTS

You need to free the temporary clob.

The document obtained may be a XML document or a text document. When the DBUri-ref identifies an element in the XPath, the result is a well-formed XML document. On the other hand, if it identifies a text node (using the text() function), then we get back only the text contents of the column or attribute.

getExternalUrl()

PURPOSE

Get the URL stored inside the instance after escaping the non-URL characters as specified in the Uri-ref specification.

SYNTAX

MEMBER FUNCTION getExternalUrl() RETURN varchar2

COMMENTS

Generates the escaped URL that can be used in HTML web pages. You would still have to append the DBUri servlet that can process the DBUri-ref before using it in web pages.

getUrl()

PURPOSE

Get the URL stored inside the instance without escaping the non-URL characters.

SYNTAX

MEMBER FUNCTION getUrl() RETURN varchar2

COMMENTS

Generates the URL that is present in the HttpUri instance.

createUri()

PURPOSE

Static function to construct a DbUri-ref instance.

SYNTAX

STATIC FUNCTION createUri(url IN varchar2) RETURN DbUriType

PARAMETERS

url (IN) - the url string containing a valid HTTP URL. 
  The url string is assumed to be in the escaped form. i.e. non-url characters
  are represented as %xx where xx is the hexadecimal value for the 
  UTF-8 encoding of the character.

COMMENTS

Parses the URL given and creates a Uri-ref type instance.

UriFactory Package

The UriFactory package contains factory methods that can be used to generate the appropriate instance of the Uri types without having to hard code the implementation in the program.

The UriFactory package also provides the ability to register new subtypes of the UriType to handle various other protocols not supported by Oracle9i. For example, one can invent a new protocol "ecom://" and define a subtype of the UriType to handle that protocol and register it with UriFactory. After that any factory method would generate the new subtype instance if it sees the ecom prefix.

For example,

create table url_tab (urlcol varchar2(20));

-- insert a Http reference
insert into url_tab values ('http://www.oracle.com');

-- insert a DBuri-ref reference
insert into url_tab values ('/SCOTT/EMPLOYEE/ROW[ENAME="Jack"]');

-- create a new type to handle a new protocol called ecom://
create type EComUriType under UriType 
(
  overriding member function getClob() return clob,
  overriding member function getBlob() return blob, -- not supported
  overriding member function getExternalUrl() return varchar2,
  overriding member function getUrl() return varchar2,

  -- MUST NEED THIS for registering with the url handler
  static member function createUri(url in varchar2) return EcomUriType
);
/

-- register a new protocol handler.
begin

  -- register a new handler for ecom:// prefixes. The handler
  -- type name is ECOMURITYPE, schema is SCOTT
  -- Ignore the prefix case, when comparing and also strip the prefix
  -- before calling the createUri function
  urifactory.registerHandler('ecom://','SCOTT','ECOMURITYPE',
     true,true);
end;
/
insert into url_tab values ('ECOM://company1/company2=22/comp');

-- now use the factory to generate the instances.!
select urifactory.getUri(urlcol) from url_tab;

-- would now generate
HttpUriType('www.oracle.com'); -- a Http uri type instance

DBUriType('/SCOTT/EMPLOYEE/ROW[ENAME="Jack"],null); -- a DBUriType

EComUriType('company1/company2=22/comp'); -- a EComUriType instance


Package functions

FUNCTION getUri(varchar2) RETURN UriType

This function takes in the Url string and generates the appropriate handler instance.

FUNCTION escapeUri(varchar2) RETURN varchar2

Escape the given URL in to the external form, i.e. the non-Url characters such as spaces are escaped, using the standard escape sequence, %xx where xx is the hexadecimal value of the UTF-8 encoding of the character.

FUNCTION unescapeUri(varchar2) RETURN varchar2;

Un-escape a URL. i.e. convert the %xx escape sequence into the corresponding characters.

PROCEDURE registerUrlHandler(varchar2, varchar2, varchar2, boolean, boolean)

This procedure registers a Url handler given the prefix to scan for and the schema and type name that handles the given URL.

PROCEDURE unRegisterUrlHandler(varchar2)

This function deletes a handler for a particular prefix.


Function prototypes

getUri()

PURPOSE

Factory method to get the correct Url handler for the given URL string. Returns a subtype instance of the UriType.

SYNTAX

FUNCTION getUrl(url IN Varchar2) RETURN UriType

PARAMETERS

url (IN) - the url string containing a valid HTTP URL. 
  The url string is assumed to be in the escaped form. i.e. non-url characters
  are represented as %xx where xx is the hexadecimal value for the 
  UTF-8 encoding of the character.

RETURNS

A subtype instance of the UriType which can handle the protocol. By default it always creates a DBuri-ref instance, if it cannot resolve the URL.

COMMENTS

The user can register a URL handler for a particular prefix using the registerUrlHandler and the getUrl would use that subtype if the prefix matches.

escapeUri()

PURPOSE

Escape the url string by replacing the non-URL characters as specified in the Uri-ref specification by their equivalent escape sequence.

SYNTAX

MEMBER FUNCTION escapeUri() RETURN varchar2

PARAMETERS

url (IN) - the url string containing a valid URL. 
 

COMMENTS

Generates the escaped URL that can be used in HTML web pages. The subtype instances override this member function to provide additional semantics. For instance, the HttpUriType does not store the prefix http:// in the Url itself. When generating the external Url, it appends the prefix and generates it. This is the reason that you should use the getExternalUrl or getUrl to get to the URL value instead of using the attribute present in the UriType.

unescapeUri()

PURPOSE

Un-escape a given url.

SYNTAX

FUNCTION unescapeUri() RETURN varchar2

PARAMETERS

url (IN) - the url string that needs to be un-escaped

COMMENTS

Reverse of the escapeUri. Scans the string and converts any %xx into the equivalent UTF-8 character. Since the return type is a VARCHAR2, the character would be converted into the equivalent character as defined by the database character set.

registerUrlHandler()

PURPOSE

Register a particular type name for handling a particular URL.

SYNTAX

PROCEDURE registerUrlHandler(prefix IN varchar2, schemaName in varchar2,
   typename in varchar2, ignoreCase in boolean := true, 
   stripprefix in boolean := true)

PARAMETERS

prefix (IN) - the prefix to handle (e.g. http://)
schemaName (IN) - the name of the schema in which the type resides
typename (IN) - the name of the type to handle the URL
       Both the typename and schemaname are case sensitive.
ignorecase (IN) - should the case be ignored when matching prefixes?
stripprefix (IN) - should the prefix be stripped before generating
      the instance of the type?

COMMENTS

Register a URL handler. The type specified must be valid and MUST be a subtype of the UriType or one of it's subtypes. The type MUST also implement the following static member function

STATIC FUNCTION createUri(url IN varchar2) RETURN <typename>;

This function is called by the getUrl() to generate an instance of the type. The stripprefix indicates that the prefix must be stripped off before calling this function.

unRegisterUrlHandler()

PURPOSE

Un-register a Url handler.

SYNTAX

PROCEDURE unregisterUrlHandler(prefix in varchar2)

PARAMETERS

prefix (IN) -  the prefix that should be unregistered.

COMMENTS

Un-registers a particular prefix. Note that this would only un-register user registered handler prefixes and not the sytem predefined prefixes such as http://

XMLType

Oracle9i has introduced a new datatype for handling XML data. This datatype is a system defined object type that has predefined member function on it to extract XML nodes and fragments.

You can create columns of XMLType and insert XML documents into it. You can also generate XML documents as XMLType instances dynamically using the SYS_XMLGEN and SYS_XMLAGG SQL functions.

For example,

create table xml_tab ( xmlval sys.xmltype);

insert into xml_tab values (
   sys.xmltype.createxml('<?xml version="1.0"?>
                          <EMP>
                            <EMPNO>221</EMPNO>
                            <ENAME>John</ENAME>
                          </EMP>'));

insert into xml_tab values (
   sys.xmltype.createxml('<?xml version="1.0"?>
                          <PO>
                            <PONO>331</PONO>
                            <PONAME>PO_1</PONAME>
                          </PO>'));

-- now extract the numerical values for the employee numbers
select e.xmlval.extract('//EMPNO/text()').getNumVal() as empno
from xml_tab 
where e.xmlval.existsnode('/EMP/EMPNO')  = 1;
 

Member functions

STATIC FUNCTION createXML(varchar2) RETURN sys.XMLType

This static function creates an XMLType instance from a string.

STATIC FUNCTION createXML(clob) RETURN sys.XMLType

This static function creates an XMLType instance from a CLOB.

MEMBER FUNCTION existsNode(varchar2) RETURN number

Checks if the given XPath expression returns any result nodes. Returns 1 for true.

MEMBER FUNCTION extract(varchar2) RETURN sys.XMLType

Applies the XPath expression over the XML data to return a XMLType instance containing the resultant fragment.

MEMBER FUNCTION isFragment() RETURN number

Returns 1 or 0 indicating if the XMLType instance contains a fragment or a well-formed document.

MEMBER FUNCTION getClobVal() RETURN clob

Returns the document as a CLOB.

MEMBER FUNCTION getNumVal() RETURN clob

Returns the fragment or text value in the XMLType to a number.

MEMBER FUNCTION getStringVal() RETURN varchar2

Returns the document as a string.


Function prototypes

createXML()

PURPOSE

Static function to create the XMLType instance from a string.

SYNTAX

STATIC FUNCTION createXML(xmlval IN varchar2) RETURN sys.XMLType deterministic

PARAMETERS

xmlval (IN) - string containing the XML document

RETURNS

An XMLType instance.

COMMENTS

The string must contain a well-formed and valid XML document.

createXML()

PURPOSE

Static function to create the XMLType instance from a CLOB.

SYNTAX

STATIC FUNCTION createXML(xmlval IN clob) RETURN sys.XMLType deterministic

PARAMETERS

xmlval (IN) - CLOB containing the XML document

RETURNS

An XMLType instance.

COMMENTS

The CLOB must contain a well-formed and valid XML document.

existsNode()

PURPOSE

Given an XPath expression, checks if the XPath applied over the document can return any valid nodes.

SYNTAX

MEMBER FUNCTION existsNode(xpath IN varchar2) RETURN number deterministic

PARAMETERS

xpath (IN) - the XPath expression to test

RETURNS

0 if the XPath expression does not return any nodes else 1.

COMMENTS

If the XPath string is null or the document is empty, then a value of 0 is returned.

extract()

PURPOSE

Given an XPath expression, applies the XPath to the document and returns the fragment as an XMLType

SYNTAX

MEMBER FUNCTION extract(xpath IN varchar2) RETURN sys.XMLType deterministic

PARAMETERS

xpath (IN) - the XPath expression to apply

RETURNS

An XMLType instance containing the result node(s).

COMMENTS

If the XPath does not result in any nodes, then the result is NULL.

isFragment()

PURPOSE

Determine if the XMLType instance corresponds to a well-formed document, or a fragment.

SYNTAX

MEMBER FUNCTION isFragment() RETURN boolean deterministic

RETURNS

Returns 1 or 0 indicating if the XMLType instance contains a fragment or a well-formed document.

getClobVal()

PURPOSE

Gets the document as a CLOB

SYNTAX

MEMBER FUNCTION getClobVal() RETURN clob deterministic

RETURNS

An CLOB containing the seralized XML representation.

COMMENTS

You need to free the temporary CLOB after use.

getNumVal()

PURPOSE

Gets the numeric value pointed to by the XMLType as a number

SYNTAX

MEMBER FUNCTION getNumVal() RETURN number deterministic

RETURNS

An number formatted from the text value pointed to by the XMLType instance.

COMMENTS

The XMLType must point to a valid text node that contains a numerical value.

getStringVal()

PURPOSE

Gets the document as a string.

SYNTAX

MEMBER FUNCTION getStringVal() RETURN varchar2 deterministic

RETURNS

A string containing the seralized XML representation, or in case of text nodes, the text itself.

COMMENTS

If the XML document is bigger than the maximum size of the varchar2, which is 4000, then an error is raised at run time.


Go to previous page Go to next page
Oracle
Copyright © 1996-2001, Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index