242 Database URI TYPEs

Summary of URITYPE Supertype Subprograms

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, and also select from columns without knowing the instance of the URL stored.

---

GETBLOB

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.

---

GETCLOB

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.

---

GETCONTENTTYPE

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.

Syntax

MEMBER FUNCTION getContentType()
RETURN VARCHAR2;

---

GETEXTERNALURL

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.

Syntax

MEMBER FUNCTION getExternalUrl()
RETURN varchar2;

---

GETURL

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.

Syntax

MEMBER FUNCTION getUrl()
RETURN varchar2;

---

GETXML

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.

Summary of HTTPURITYPE Subtype Subprograms

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.

---

CREATEURI

This static function constructs a HTTPURITYPE instance. The HTTPURITYPE instance does not contain the prefix http:// in the stored URL.

Syntax

STATIC FUNCTION createUri(
   url IN varchar2)
RETURN HTTPURITYPE;

---

GETBLOB

This function returns the BLOB located at the address specified by the HTTP URL.

---

GETCLOB

This function returns the CLOB located by the HTTP URL address. If a temporary CLOB is returned, it must be freed.

---

GETCONTENTTYPE

Returns the content type of the document pointed to by the URI.

Syntax

MEMBER FUNCTION getContentType()
RETURN VARCHAR2;

---

GETEXTERNALURL

This function returns the URL, in escaped format, stored inside the HTTPURITYPE instance. The subtype instances override this member function. The HTTPURITYPE function does not store the prefix http://, but generates it for the external URL.

Syntax

MEMBER FUNCTION getExternalUrl()
RETURN varchar2;

---

GETURL

This function returns the URL, in non-escaped format, stored inside the HTTPURITYPE instance.

Syntax

MEMBER FUNCTION getUrl()
RETURN varchar2;

---

GETXML

This function returns the XMLType located at the address specified by the URL. An error is thrown if the address does not point to a valid XML document.

---

HTTPURITYPE

This constructs a HTTPURITYPE instance. The HTTPURITYPE instance does not contain the prefix http:// in the stored URL.

Syntax

CONSTRUCTOR FUNCTION HTTPURITYPE(
   url IN varchar2);

Summary of DBURITYPE Subtype Subprogams

The DBURITYPE is a subtype of the UriType that provides support for 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.

---

CREATEURI

This static function constructs a DBURITYPE instance. Parses the URL given and creates a DBURITYPE instance.

Syntax

STATIC FUNCTION createUri(
   url IN varchar2)
RETURN DBURITYPE;

---

DBURITYPE

This constructs a DBURITYPE instance.

Syntax

CONSTRUCTOR FUNCTION DBURITYPE(
   url IN varchar2);

---

GETBLOB

This function returns the BLOB located at the address specified by the URL. The options are described in the following table.

---

GETCLOB

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, then what is returned is only the text content of the column or attribute. The options are described in the following table.

---

GETCONTENTTYPE

This function returns the content type of the document pointed to by the URI.

Syntax

MEMBER FUNCTION getContentType()
RETURN VARCHAR2;

---

GETEXTERNALURL

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.

Syntax

MEMBER FUNCTION getExternalUrl()
RETURN varchar2;

---

GETURL

This function returns the URL, in non-escaped format, stored inside the DBURITYPE instance.

Syntax

MEMBER FUNCTION getUrl()
RETURN varchar2;

---

GETXML

This function returns the XMLType located at the address specified by the URL. The options are described in the following table.

Summary of XDBURITYPE Subtype Subprograms

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.

---

CREATEURI

This static function constructs a XDBURITYPE instance. Parses the URL given and creates a XDBURITYPE instance.

Syntax

STATIC FUNCTION createUri(
   url IN varchar2)
RETURN XDBURITYPE

---

GETBLOB

This function returns the BLOB located at the address specified by the XDBURITYPE instance. The options are described in the following table.

---

GETCLOB

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.

---

GETCONTENTTYPE

This function returns the content type of the document pointed to by the URI. This function returns the content type as VARCHAR2.

Syntax

MEMBER FUNCTION getContentType()
RETURN VARCHAR2;

---

GETEXTERNALURL

This function returns the URL, in escaped format, stored inside the XDBURITYPE instance.

Syntax

MEMBER FUNCTION getExternalUrl()
RETURN varchar2;

---

GETURL

This function returns the URL, in non-escaped format, stored inside the XDBURITYPE instance.

Syntax

MEMBER FUNCTION getUrl()
RETURN varchar2;

---

GETXML

This function returns the XMLType located at the address specified by the URL. The options are described in the following table.

---

XDBURITYPE

This constructs a XDBURITYPE instance.

Syntax

CONSTRUCTOR FUNCTION XDBURITYPE(
   url     IN   VARCHAR2,
   flags   IN   RAW := NULL)
 RETURN self AS RESULT;

Summary of URIFACTORY Package Subprograms

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. For example, you 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.

---

GETURI

This factory method returns the correct URI handler for the given URI 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, GETURI would then use that subtype.

Syntax

FUNCTION getUri(
   url IN Varchar2)
RETURN UriType;

---

ESCAPEURI

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 GETURI function to get to the URL value instead of using the attribute present in the UriType.

Syntax

MEMBER FUNCTION escapeUri()
RETURN varchar2;

---

UNESCAPEURI

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.

Syntax

FUNCTION unescapeUri()
RETURN varchar2;

---

REGISTERURLHANDLER

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 createUri static member function. This function is called by the GETURI function to generate an instance of the type. The stripprefix parameter indicates that the prefix must be stripped off before calling this function.

Syntax

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

---

UNREGISTERURLHANDLER

This procedure unregisters a URL handler. This only unregisters user registered handler prefixes and not predefined system prefixes such as http://.

Syntax

PROCEDURE unregisterUrlHandler(
   prefix IN varchar2);