Release 2 (9.2)
Part Number A96616-01
 Home |
 Book List |
 Contents |
 Index |
 Master Index |
 Feedback |
| Oracle9i XML API Reference - XDK and Oracle XML DB Release 2 (9.2) Part Number A96616-01 |
|
This chapter contains the following sections:
Oracle9i supports the UriType family of types that can be used to store and query Uri-refs inside the database. The UriType itself is an abstract object type and the HttpUriType, XDBUriType and DBUriType are subtypes of it.
You can create a UriType column and store instances of the DBUriType, XDBUriType 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 that can be used as a factory method to automatically generate various instances of these UriTypes by scanning the prefix (for example, http:// or /oradb). You can also register your subtype and provide the prefix that you support. For instance, if you have written a subtype to handle the gopher protocol, you can register the prefix gopher:// to be handled by your subtype. The UriFactory will then generate your subtype instance for any URL starting with that prefix.
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.
Instances of this type cannot be created directly. However, you can create columns of this type and store subtype instances in it.
For example,
create table uri_tab ( url uritype); insert into uri_tab values (httpuritype.createuri('http://www.oracle.com')); insert into uri_tab values (dburitype.createuri('/SCOTT/EMPLOYEE/ROW[ENAME="Jack"]'));
Now you can select from the column without having to know what instance of the URL is actually stored. The following line of code would retrieve both the HTTP URL and the DBUri-ref:
select e.url.getclob() from uri_tab e;
This function returns the BLOB located at the address specified by the URL. This function can be overridden in the subtype instances. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
This function returns the CLOB located at the address specified by the URL. This function can be overridden in the subtype instances. This function returns either a permanent CLOB or a temporary CLOB. If a temporary CLOB is returned, it must be freed. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
This function returns the content type of the document pointed to by the URI. This function can be overridden in the subtype instances. This function returns the content type as VARCHAR2.
MEMBER FUNCTION getContentType() RETURN VARCHAR2;
This function returns the URL, in escaped format, stored inside the UriType instance. The subtype instances override this member function to provide additional semantics. For instance, the HttpUriType function does not store the prefix http:// in the URL itself. When generating the external URL, it appends the prefix and generates it. For this reason, use the getExternalUrl function or the getUrl function to get to the URL value instead of using the attribute present in the UriType instance.
MEMBER FUNCTION getExternalUrl() RETURN varchar2;
This function returns the URL, in non-escaped format, stored inside the UriType instance. The subtype instances override this member function to provide additional semantics. For instance, the HttpUriType function does not store the prefix http:// in the URL itself. When generating the external URL, it appends the prefix and generates it. For this reason, use the getExternalUrl function or the getUrl function to get to the URL value instead of using the attribute present in the UriType instance.
MEMBER FUNCTION getUrl() RETURN varchar2;
This function returns the XMLType located at the address specified by the URL. This function can be overridden in the subtype instances. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
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. Proxy and secure wallets are not supported in this release.
The following example creates a uri table to store the Http instances
create table uri_tab ( url httpuritype);
Insert the Http instance.
insert into uri_tab values (httpuritype.createUri('http://www.oracle.com'));
Generate the HTML
select e.url.getclob() from uri_tab e;
This static function constructs a HttpUriType instance. The HttpUriType instance does not contain the prefix http:// in the stored URL.
STATIC FUNCTION createUri(url IN varchar2) RETURN HttpUriType;
This function returns the BLOB located at the address specified by the HTTP URL. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
This function returns the CLOB located at the address specified by the HTTP URL. This function returns either a permanent CLOB or a temporary CLOB. If a temporary CLOB is returned, it must be freed. The options are described in the following table.
| Syntax | Description |
|---|---|
|
RETURN clob; |
Returns the CLOB located at the address specified by the HTTP URL. |
|
RETURN clob; |
Returns the CLOB located at the address specified by the HTTP URL and the content type. |
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
Returns the content type of the document pointed to by the URI.
MEMBER FUNCTION getContentType() RETURN VARCHAR2;
This function returns the URL, in escaped format, stored inside the HttpUriType instance. The subtype instances override this member function to provide additional semantics. The HttpUriType function does not store the prefix http:// in the URL itself. When generating the external URL, it prepends the prefix and generates it.
MEMBER FUNCTION getExternalUrl() RETURN varchar2;
This function returns the URL, in non-escaped format, stored inside the HttpUriType instance.
MEMBER FUNCTION getUrl() RETURN varchar2;
This function returns the XMLType located at the address specified by the URL. An error tis thrown if the address does not point to a valid XML doc. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
This constructs a HttpUriType instance. The HttpUriType instance does not contain the prefix http:// in the stored URL.
CONSTRUCTOR FUNCTION httpUriType(url IN varchar2);
The DBUriType is a subtype of the UriType that provides support for of DBUri-refs. A DBUri-ref is an 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:
<?xml version="1.0"?> <ORADB> <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> </ORADB>
Hence, to reference the State attribute inside the employee table, you can formulate a DBUri-ref as shown:
/ORADB/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 dburitype);
Insert values
insert into dburi_tab values ( dburitype.createUri( '/ORADB/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:
select sys_dburigen( e.ename, e.address.state) AS urlcol from scott.employee e;
This static function constructs a DBUriType instance. Parses the URL given and creates a DBUriType instance.
STATIC FUNCTION createUri( url IN varchar2) RETURN DBUriType;
| Parameter | IN / OUT | Description |
|---|---|---|
|
url |
(IN) |
The URL string, in escaped format, containing a valid DBUri reference. |
This constructs a DBUriType instance.
CONSTRUCTOR FUNCTION DBUriType( url IN varchar2);
This function returns the BLOB located at the address specified by the URL. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
This function returns the CLOB located at the address specified by the DBUriType instance. If a temporary CLOB is returned, it must be freed. The document returned may be an 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 what is returned is only the text content of the column or attribute. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
This function returns the content type of the document pointed to by the URI.
MEMBER FUNCTION getContentType() RETURN VARCHAR2;
This function returns the URL, in escaped format, stored inside the DBUriType instance. The DBUri servlet URL that processes the DBUriType has to be appended before using the escaped URL in web pages.
MEMBER FUNCTION getExternalUrl() RETURN varchar2;
This function returns the URL, in non-escaped format, stored inside the DBUriType instance.
MEMBER FUNCTION getUrl() RETURN varchar2;
This function returns the XMLType located at the address specified by the URL. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
XDBUriType is a new subtype of URIType. It provides a way to expose documents in the Oracle XML DB hierarchy as URIs that can be embedded in any URIType column in a table. The URL part of the URI is the hierarchical name of the XML document it refers to. The optional fragment part uses the XPath syntax, and is separated from the URL part by '#'. The more general XPointer syntax for specifying a fragment is not currently supported.
This static function constructs a XDBUriType instance. Parses the URL given and creates a XDBUriType instance.
STATIC FUNCTION createUri(url IN varchar2) RETURN XDBUriType;
| Parameter | IN / OUT | Description |
|---|---|---|
|
url |
(IN) |
The URL string, in escaped format, containing a valid XDBUri reference. |
This function returns the BLOB located at the address specified by the XDBUriType instance. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
This function returns the CLOB located at the address specified by the XDBUriType instance. If a temporary CLOB is returned, it must be freed. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
This function returns the content type of the document pointed to by the URI. This function returns the content type as VARCHAR2.
MEMBER FUNCTION getContentType() RETURN VARCHAR2;
This function returns the URL, in escaped format, stored inside the XDBUriType instance.
MEMBER FUNCTION getExternalUrl() RETURN varchar2;
This function returns the URL, in non-escaped format, stored inside the XDBUriType instance.
MEMBER FUNCTION getUrl() RETURN varchar2;
This function returns the XMLType located at the address specified by the URL. The options are described in the following table.
| Parameter | IN / OUT | Description |
|---|---|---|
|
content |
(OUT) |
Content type of the document to which URI is pointing. |
This constructs a XDBUriType instance.
CONSTRUCTOR FUNCTION XDBUriType( url IN varchar2);
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'); -- an Http uri type instance DBUriType('/SCOTT/EMPLOYEE/ROW[ENAME="Jack"],null); -- a DBUriType EComUriType('company1/company2=22/comp'); -- a EComUriType instance
This factory method returns the correct URL handler for the given URL string. It returns a subtype instance of the UriType that can handle the protocol. By default, it always creates an XDBUriType instance, if it cannot resolve the URL. A URL handler can be registered for a particular prefix using the registerUrlHandler() function. If the prefix matches, getUrl() would then use that subtype.
FUNCTION getUrl(url IN Varchar2) RETURN UriType;
| Parameter | IN / OUT | Description |
|---|---|---|
|
url |
(IN) |
The URL string, in escaped format, containing a valid HTTP URL. |
This function returns a URL in escaped format. 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. For this reason, use the getExternalUrl function or the getUrl function to get to the URL value instead of using the attribute present in the UriType.
MEMBER FUNCTION escapeUri() RETURN varchar2;
| Parameter | IN / OUT | Description |
|---|---|---|
|
url |
(IN) |
The URL string to be returned in escaped format. |
This function returns a URL in unescaped format. This function is the reverse of the escapeUri function. This function scans the string and converts any non-URL hexadecimal characters into the equivalent UTF-8 characters. Since the return type is a VARCHAR2, the characters would be converted into the equivalent characters as defined by the database character set.
FUNCTION unescapeUri() RETURN varchar2;
| Parameter | IN / OUT | Description |
|---|---|---|
|
url |
(IN) |
The URL string to be returned in unescaped format. |
This procedure registers a particular type name for handling a particular URL. The type specified must be valid and must be a subtype of the UriType or one of its subtypes. It must also implement the following static member function:
STATIC FUNCTION createUri(url IN varchar2) RETURN <typename>;
This function is called by the getUrl() function to generate an instance of the type. The stripprefix parameter indicates that the prefix must be stripped off before calling this function.
PROCEDURE registerUrlHandler( prefix IN varchar2, schemaName IN varchar2, typename IN varchar2, ignoreCase IN boolean := true, stripprefix IN boolean := true);
This procedure unregisters a URL handler. This only unregisters user registered handler prefixes and not predefined system prefixes such as http://.
PROCEDURE unregisterUrlHandler(prefix IN varchar2);
| Parameter | IN / OUT | Description |
|---|---|---|
|
prefix |
(IN) |
The prefix to be unregistered. |
|
 Copyright © 2001, 2002 Oracle Corporation. All Rights Reserved. |
|
