Skip Headers

Oracle® Application Developer's Guide - XML 10g (9.0.4) Part Number B12099-01 |
Home | Contents | Index

# 6
Database Uri-references

This chapter contains the following sections:

- Uri-reference (Uri-ref) Concepts

- New Datatypes Store Uri-references

- DBUri-refs, Intra-Databases References

- Using Uri-ref Types (URITypes)

- UriFactory Package

- Why Use Different Uri-refs?

- SYS_DBURIGEN() SQL Function

- Accessing DBUri-refs From Your Browser Using Servlets

## Uri-reference (Uri-ref) Concepts

### What is a Uri-ref?

Uri-Reference (Uri-ref) is a generalization of the URL concept. In this release, URI can reference any document, including HTML and XML. It also provides pointer semantics into the document. Uri-ref consists of two parts:

- URL part, according to the regular URL specification

- Fragment part, that identifies a fragment within that document.

It is in a language specific to the type of the document in question. The fragment part is that part after the "#" in the following examples. The fragment part is not supported in this release.

#### URL Path Created From an XML Document View

Figure 6-2 shows a view of the XML data stored in relational table, Emp, in the database, and the columns of data mapped to elements in the XML document. This mapping is also referred to as an "XML visualization". The resulting URL path can then be created simply from the XML document view.

Typical Uri-ref's look like the following:

- For HTML: http://www.url.com/document1#A

  where A is an anchor inside the document.

- For XML: http://www.xml.com/xml_doc#//po/cust/custname

  where:

  - The portion before the '#' identifies the location of the document itself

  - The portion after the '#' identifies a fragment within that document. This portion is defined by W3C's XPointer specification.

#### Uri-ref can Use Different Protocols to Retrieve Data

Oracle, has introduced new datatypes in the database to store and retrieve uri-ref objects. See "New Datatypes Store Uri-references" in the following section. Uri-ref, can in turn, use different protocols, such as the HTTP, to retrieve data.

Oracle has also introduced a new concept called DBUri-refs. These are references into columns and rows of tables and views inside the database itself.

- HTTP URL references objects that are global

- DBUri-ref references local objects

Using this DBUri-ref mechanism you can access any row or column data in any table or view in the database. In effect it provides a intra-database URL for any data stored in the database. See "DBUri-refs, Intra-Databases References" .

### Advantages of Using DBUri-ref

DBUri-ref advantages include the following:

- Improved Performance by Bypassing the Web Server. Uri-ref is one way to locally reference stylesheets. For example, DBMS-Metadata uses DbUri-ref to reference many stylesheets. If you already have a URL in your XML document and you have to replace this with a reference to the database, you can either:

  - Use a servlet

  - Use an input mechanism, such as the DBUri-ref, to bring back the results

  Using DBUri-ref has performance benefits as you interact directly with the database rather than through a web server.

- Who Needs SQL? You do not need to know SQL to access an XML document stored in the database. DBUri-ref allows you to access an XML document from the database using SQL semantics but without your need to use SQL. In other words, a non-SQL programmer can now easily access XML documents stored in a database.

## New Datatypes Store Uri-references

Oracle has introduced the following new datatypes to store the uri-references:

- UriType. An abstract object type that can store instances of HttpUriType or DBUriType.

- DBUriType. Can obtain data pointed to by the DBUri-ref.

- HttpUriType. Implements the HTTP protocol for accessing remote pages.

- UriFactoryType.

  See Also: Figure 6-3, "UriFactory to Generate UriType Instances".

#### Figure 6-1 New UriTypes

Text description of the illustration xml_type.gif

These datatypes are object types with member functions that can be used to access objects or pages pointed to by the objects. Thus by using the UriType, you can do the following:

- Create columns that can point to data inside or outside the database

- Query the database columns using abstract functions provided by UriType

### Benefits of Using UriTypes

Oracle already supports UTL_HTTP and java.net.URL in PL/SQL and Java respectively, to fetch URL references. The advantages of defining this new UriType datatype in SQL are as follows:

- Better Typing Leads to More Efficient Indexing, Navigation, and Querying Uri-ref also makes the database aware of a new URL type that can be stored in columns of tables or views. Better typing of a column can lead to newer url-aware indexing schemes and better navigation and query capabilities through the URL.

- Improved Mapping of XML Documents to Columns. Uri-ref support is needed when exploding XML documents into object-relational columns, so that the Uri-ref specified in documents can map to a URL column in the database.

  See Also: "Using Uri-ref Types (URITypes)" .

## DBUri-refs, Intra-Databases References

DBUri-Ref, a database relative to URI, is a special case of the Uri-ref mechanism, where ref is guaranteed to work inside the context of a database and session. This ref is not a global ref like the HTTP URL, instead it is local ref (URL) within the database.

You can also access objects pointed to by this URL globally, by "appending" this DBUri-ref to an HTTP URL path that identifies the servlet that can handle DBUri-ref. This is explained later under "Accessing DBUri-refs From Your Browser Using Servlets" .

#### Figure 6-2 DBUri-ref Explained

Text description of the illustration adxml100.gif

### Formulating the DBUri

The URL syntax is obtained by specifying a XPath-like syntax over a virtual XML visualization of the database. See also Figure 6-2, "DBUri-ref Explained".

The "visual model" is a hierarchical view of what a current connected user would see in terms of SQL schemas, tables, rows and columns.

The "XML view" contains a root element that maps to the database. The root XML element contains child elements which are the schemas on which the user has some privileges on any object. The schema elements contain tables and views which the user can see. For example, the user scott can see the following virtual document.

    <?xml version='1.0'?>
    <oradb SID="ORCL">
     <PUBLIC>
        <ALL_TABLES>
           ..
         </ALL_TABLES>
        <EMP>
          <!-- EMp table -->
        </EMP>
     <PUBLIC>
     <SCOTT>
      <ALL_TABLES>
        ....
      </ALL_TABLES>
      <EMP>
       <ROW>
         <EMPNO>1001</EMPNO>
         <ENAME>John</ENAME>
         <EMP_SALARY>20000</EMP_SALARY>
       </ROW>
       <ROW>
         <EMPNO>2001</EMPNO>
         <ENAME xsi:null="true"/>
         <EMP_SALARY xsi:null="true"/>
       </ROW>
      </EMP>
      <DEPT>
       <ROW>
         <DEPTNO>200</DEPTNO>
         <DNAME>Sports</DNAME>
       </ROW>
      </DEPT>
    </SCOTT>
    <JONES>
     <CUSTOMER_OBJ_TAB>
       <ROW>
         <NAME>xxx</NAME>
         <ADDRESS>
            <STATE>CA</STATE>
            <ZIP>94065</ZIP>
         </ADDRESS>
       </ROW>
      </CUSTOMER_OBJ_TAB>
     </JONES>
    </database>

Remember, that this is a virtual XML document based on the privileges that you have at the time of access.

You can make the following observations from the foregoing example:

- The scott user can see the scott schema and jones schema. These are schemas on which the user has some table or views that he can read.

- Table emp shows up as EMP with row element tags. This is the default mapping for all tables. The same for dept and the customer_obj_tab table under the JONES schema.

- Null elements are shown as being absent. This will change with later releases to conform to the XMLSchema specification which specifies a special null attribute to indicate nullness.

- There is also a PUBLIC element under which are tables and views accessible without schema qualification. For example, a select query such as:

      select * from emp;

  when queried by the user scott, will match the table emp under the scott schema and if not found, would try to match it with a public synonym that is available. In the same way, the PUBLIC element contains all the tables and views that are either visible to the user through his/her schema and all the tables that are visible through the PUBLIC synonym.

### The DB-Uri Specification

With the database being visualized as an XML tree, you can perform XPath traversals to any part of the virtual document. This translates to any row-column intersection of the database tables or views. By specifying an XPath over the visualization model, you can create references to any piece of data in the database.

DbUri is specified in a simplified XPath format. For this release Oracle does not support the full flavor of XPath or Xpointer for DBUri- ref. The following sections discuss the structure of these DBUri.

Note: When exposing the DBUri through a global HTTP URL, you may have to "escape" certain characters such as']','',.... in the XPath syntax. You can use the `getExternalUrl()` functions in the types to get an escaped version of the URL.

As stated above, you can now create DBUri's to any piece of data. You can use the following units of reference:

- A scalar or object or collection instance in a column

- An attribute of an object type

  Note: Oracle does not currently support references within a scalar, XMLType or LOB data value.

With DBUri's, you can also create globally reference able URLs. This is explained in a later section, "Accessing DBUri-refs From Your Browser Using Servlets" .

### DBUri Syntax Guidelines

There are restrictions on the kind of XPath queries that can be used to specify a reference. In general, DBUri-ref's must adhere to the following syntax guidelines:

- Include the user schema name or PUBLIC to resolve the table name without a specific schema.

- Include a table or view name.

- Include the ROW tag for identifying the ROW element.

- Identify the column or object attribute that you wish to extract.

- Include predicates at any level in the path other than the schema and table elements.

- Indicate predicates not on the selection path in the ROW element. For example, if you wanted to specify the predicate, pono = 100, but the selection path is /scott/purchase_obj_tab[..]/ROW/line_item_list, then you must include the pono predicate along with the ROW node as:

       /scott/purchase_obj_tab/ROW[spono=100]//line_item_list

- DBUri-ref must identify exactly a single data value which may be an object type or collection. The data value can be an entire row in which case ROW node must be used to indicate that. The uri-ref can also point to an entire table.

#### Using Predicate (XPath) Expressions in DBUri

The predicate expressions can use the following XPath expressions:

- Boolean operators - AND, OR and NOT

- Relational operators - <, >, <=,!=, >=, =, mod, div, * (multiply)

  Note: No XPath axes other than the child axes are supported. Thus the wild card (*), descendant (//), and other operations are not valid. No XPath functions other than text() are supported.`text()` is also valid only on a scalar node. Thus you cannot apply the text() node say at the ROW level or at the table level

The predicates can be defined at any element other than the schema and table elements. If you have object columns, then you can search on the attribute values as well. For example, if address was a column in the emp table, which contains say the state, city, street and zipcode attributes, then the following dburi-ref is valid:

    /SCOTT/EMP/ROW[ADDRESS/STATE='CA' OR ADDRESS/STATE='OR']/ADDRESS[CITY='Portland'
    OR ./ZIPCODE=94404]/CITY

This dburi-ref identifies the city attribute of the address column in the emp table whose state is either California or Oregon or the city name is Portland or the zipcode is 94404.

### Some Common DBUri-ref Scenarios

The DBUri-ref can identify various objects, such as the table, a particular row, a particular column in a row, or a particular attribute of an object column. Here are some common DBUri-ref scenarios:-

1. Identifying the whole table. This returns an XML document that retrieves the whole table. The enclosing tag is the name of the table. The row values are enclosed inside a "ROW" element, as follows:

   Use the following syntax:

       /<schemaname>/<tablename>

   For example:

       /SCOTT/EMP

   returns the following XML document,:

       <?xml version="1.0"?>
       <EMP>
       	 <ROW>
       	 	 <EMPNO>7369</EMPNO>
         <ENAME>Smith</ENAME>
          ... <!-- other columns -->
        </ROW>
        <!-- other rows -->
       </EMP>

2. Identifying a particular row of the table. This identifies a particular ROW element in a table. The result is an XML document that contains the ROW element with it's columns as child elements:

   Use the following syntax:

       /<schemaname>/<tablename>/ROW[<predicate_expression>]

   For example:

       /SCOTT/EMP/ROW[EMPNO=7369]

   returns the following XML document:

       <?xml version="1.0"?>
       <ROW>
         <EMPNO>7369</EMPNO>
         <ENAME>SMITH</ENAME>
         <JOB>CLERK</JOB>

                <!-- other columns -->
           </ROW>

   Note: Here, the predicate expression must identify a unique row.

3. Identifying a target column. In this case a target column or an attribute of a column is identified and retrieved as XML.

   Note: You cannot traverse into nested table or VARRAY columns.

Use the following syntax:

    /<schemaname>/<tablename>/ROW[<predicate expression>]/<columnname>
    /<schemaname>/<tablename>/ROW[<preciate expression>]/ <columnname>/
    <attribute>*

Example 1:

    /SCOTT/EMP/ROW[EMPNO=7369 and DEPTNO =20]/ENAME

retrieves the ename column in the emp table, where empno is 7369, and department number is 20, as follows:

    <?xml version="1.0"?>
    <ENAME>SMITH</ENAME>

Example 2:

    /SCOTT/EMP/ROW[EMPNO=7369]/ADDRESS/STATE

retrieves the state attribute inside an address object column for the employee whose empno is 7369, as follows:

    <?xml version="1.0"?>
    <STATE>CA</STATE>

- Retrieving the text value of a column. In many cases, it can be useful to retrieve only the text values of a column and not the enclosing tags. For example, if the XSL stylesheets are stored in a CLOB column, you can retrieve such XML documents without having an enclosing column name tag put around them. In these cases, the`text()` function helps identify that only the text value of the node is to be retrieved.

  Use the following syntax:

      /<schemaname>/<tablename>/ROW[<predicate expression>]/<columnname>/text()

  For example:

      /SCOTT/EMP/ROW[EMPNO=7369]/ENAME/text()

  retrieves the text value of the employee name, without the XML tags, for employee with empno = 7369. This returns a text document, not an XML document, with value "SMITH".

  Note: The XPath alone does not constitute a valid URI. Oracle calls it a DBUri since it behaves like a URI within the database, but it can be translated in to a globally valid Uri-Ref.

  Note: The DBUri is case-sensitive. So to specify scott.emp, you use SCOTT/EMP since the actual table names are stored capitalized in the Oracle dictionary. To create a table name or column name in small letters in the database use the " " to enclose the names.

  ### How DBUri's Differ from Object References

  DBUri-ref has column and attribute level access and is loosely typed. Oracle8 object features provide object references which are references to row objects in the system. DBUri-ref is inherently a superset of this reference mechanism.

  DBUri-ref can not only identify a particular row, but can also provide access to a column or an object attribute of the row. However, it is loosely typed unlike the object reference. The result of the Uri-ref traversal can be an object in the system.

  ### DBUri-ref Applies to a Database and Session

  An important aspect of DBUri-ref is that it is scoped to a database and session. Since DBUri-ref itself does not carry any session specific information, it is assumed that you are connected to the database in a particular session context and are resolving the Uri-ref in that context. This is similar to the object reference mechanism, where the derefencing of an object reference requires that you have privileges to read the referenced object.

  Note: The same DBUri-ref may give different results based on the session context used, particularly if the PUBLIC path is used. For example, /PUBLIC/FOO_TAB can resolve to SCOTT.FOO_TAB when connected as scott, and resolve as JONES.FOO_TAB when connected as JONES.

  ### Where Can DBUri-ref be Used?

  Uri-ref can be used in a number of scenarios, including the following:

  #### For Storing URLs to Related Documents

  In the case of a travel story web site where you store travel stories in a table, you may have to create links to related stories. DBUri's can help, since you can create an intra-database link to the related story.

  #### For Storing Stylesheets in the Database

  Applications can use XSL stylesheets to convert XML into other formats. This data is transformed into XML. The XSL stylesheets used are stored in CLOBs. The application can use DBUri references in the following manner:

  - To access the XSL stylesheets stored in the database for use during parsing

  - To have references to related XSL stylesheets, such as, import/include,... within the XSL stylesheet itself.

    Note: DBUri-ref does not provide the following support: As a general purpose XPointer mechanism to XML data. It is not a replacement for database object references. The syntax and semantics of references differ from those of Uri-ref type. It does not enforce or create any new security models or restrictions. Instead, it relies on the underlying security architecture to enforce privileges.

  ## Using Uri-ref Types (URITypes)

  This section describes how to use Uri-ref to store pointers to documents and how to access such Uri-refs in the database.

  ### Storing Pointers to Documents with UriType

  As explained earlier, UriType is an abstract type that can store instances of it's subtypes in a column. This type contains a single VARCHAR2 attribute containing the Uri-ref string and has functions for traversing the reference and extracting the data.

  You can create columns of UriType and store Uri-references in the database. Oracle provides standard classes for HTTP and DBUri traversals. You can navigate the URI using a rich set of navigational functions.

  Table 6-1 lists some useful UriType methods.

  Note: You can plug-in any new protocol using the inheritance mechanism. Oracle provides the HttpUriType and DBUriType types for handling HTTP protocol and for deciphering DBUri references. You can for instance, implement a subtype of the UriType, to handle say, the gopher protocol.

  ##### Table 6-1 URIType Methods

  URIType Method | Description
  --- | ---
  getClob | This returns the value pointed to by the URL as a character lob value. The character encoding will be that of the database character set.
  getUrl | Returns the url that is stored in the UriType. Do not use the attribute "url" directly. Use this function instead. This can be overridden by subtypes to give you the correct url. For instance, the HttpUriType, stores only the URL and not the "http://" prefix. So the getUrl() actually appends the prefix and returns the value.
  getExternalUrl | Similar to the latter (getUrl), except that it calls the escaping mechanism to escape the characters in the URL as to conform to the URL specification. (For example spaces are converted to the escaped value %20)

  ### URIType Examples

  #### URIType Example 1: Creating URL References to a List of Purchase Orders

  You can create a list of all purchase orders with URL references to these purchase orders as follows:

      CREATE TABLE uri_tab
      (
         poUrl SYS.UriType,  -- Note that we have created abstract type columns
      -- if we knew what kind of uri's we are going to store, we can actually
      -- create the appropriate types.
         poName VARCHAR2
      );

       -- insert an absolute url into SYS.UriType..!
       -- the factory will create the correct instance (in this case a FtpUriType
      INSERT INTO uri_tab VALUES
        (sys.UriFactory.getUri('http://www.oracle.com/cust/po'),'AbsPo');

      -- insert a URL by directly calling the SYS.HttpUriType constructor.
      -- Note this isstrongly discouraged. Note the absence of the
      -- http:// prefix when creating SYS.HttpUriType instance through the default
      -- constructor.
      INSERT INTO uri_tab VALUES (sys.HttpUriType('proxy.us.oracle.com'),'RelPo');

      -- Now extract all the purchase orders
      SELECT e.poUrl.getClob(), poName FROM uri_tab e;

      -- In PL/SQL
      declare
         a SYS.UriType;
      begin

       -- absolute URL
       SELECT poUrl into a from uri_Tab WHERE poName like 'AbsPo%';
       printDataOut(	a.getClob());

       SELECT poUrl into a from uri_Tab WHERE poName like 'RelPo%';
       -- here u need to supply a prefix before u can get at the data..!
       printDataOut(a.getClob());
      end;
      /

  See: "UriFactory Package" for a description on how to use URIFactory.

  #### URIType Example 2: Using the Substitution Mechanism

  You can create columns of the UriType directly, and insert both HttpUriTypes and DBUriTypes into that column. You can also query the column without knowing where the referenced document lies.

  For example, from the first example, you can insert DBUri-ref references as well into the uri_tab table as follows:

      INSERT INTO uri_tab VALUES
        (UriFactory.getUrl(
           '/SCOTT/PURCHASE_ORDER_TAB/ROW[PONO=1000]'),'ScottPo');

  This insert, assumes that there is a purchase order table in the SCOTT schema. Now, the url column in the table contains values that are pointing through HTTP to documents globally as well as pointing to virtual documents inside the database.

  A select on the column using the `getClob()` method, would retrieve the results as a CLOB irrespective of where the document resides:

      select e.poURL.getclob() from uri_tab e;

  would retrieve values from the global HTTP address stored in the first row as well as the local DBUri reference.

  ### Using HttpUriType and DBUriType

  HttpUriType and DBUriType are sub types of UriType and implement the functions for HTTP and DBUri-ref references respectively.

  Note: HttpUriType cannot store relative HTTP references, in this release.

  ### DBUriType Examples

  #### DBUriType Example 1: Creating DBUri-ref References

  The following example creates a table with a column of type DBUriType and assigns a value to it.

      CREATE TABLE DBURiTab(DBUri DBUriType, dbDocName VARCHAR2(2000));

      -- insert values into it..!
      INSERT INTO DBUriTab VALUES
         (sys.UriFactory.createUri('/ORADB/SCOTT/EMP/ROW[EMPNO=7369]'),'emp1');

      INSERT INTO DBUriTab VALUES
         (sys.DBUriType('/SCOTT/EMP/ROW[EMPNO=7369]/'),'emp2');

      -- access the references
      SELECT e.DBUri.getCLOB() from dual;

  ## UriFactory Package

  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. See Figure 6-3.

  The `factory` method can take in strings representing the various URLs and return the appropriate subtype instance. For example:

  - If the prefix starts with http://, it creates a SYS.HttpUriType and returns a reference to that instance, after stripping out the http:// prefix.

  - If the string starts with a "/oradb/" prefix or does not match any of the well known prefixes (such as http://....), then it creates a SYS.DBUriType instance and returns that.

  #### Registering New UriType Subtypes

  The UriFactory package also provides the ability to register new subtypes of the UriType to handle various other protocols not currently supported by Oracle. 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.

  #### Figure 6-3 UriFactory to Generate UriType Instances

  Text description of the illustration adxml099.gif

  ### UriFactory Example: Registering the ecom Protocol

  To register the new protocol ecom://. You need to do the following:

  - Define a type to handle the protocol

  - Register it with the UriFactory package, as follows:

        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 SYS.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

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

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

  ## Why Use Different Uri-refs?

  As explained in earlier sections, Uri-ref is an abstract class with various derivations which implement different protocols. The advantage of separation of the various derivations is two fold.

  - If you choose a subtype for representing a column, it provides an implicit constraint on the column to contain only instances of that protocol type. This might be useful for implementing specialized indexes on that column for specific protocols. For example for the DbUri-ref you can implement some specialized indexes that can directly go and fetch the data from the disk blocks rather than executing SQL queries.

  - The second reason is that, you can have different constraints on the columns based on the type involved. For instance for the HTTP case, you could potentially define proxy and firewall constraints on the column so that any access through the HTTP would use the proxy server.

  The separation of the implementation classes from the abstract Uri-ref class provides:

  - Better modelling

  - Better extension capabilities.

  You can now implement your own protocol and actually make the database treat that as an Uri-ref for purposes of navigation, indexing, and so on.

  ## SYS_DBURIGEN() SQL Function

  DBUri reference can be created by specifying the path expression to the constructor or the UriFactory methods. However, you also need methods to generate these DBUri references dynamically given target columns. For this purpose a new SQL function, called `SYS_DBURIGEN(),` has been introduced.

  Figure 6-4 shows the SYS_DBURIGEN() syntax.

  #### Figure 6-4 SYS_DBURIGEN() Syntax

  Text description of the illustration sys_dbur.gif

  The following example uses the `SYS_DBURIGEN()` function to generate a URL of datatype `DBUriType` to the email column of the row in the sample table `hr.employees` where the employee_id = 206:

      SELECT SYS_DBURIGEN(employee_id, email)
         FROM employees
         WHERE employee_id = 206;

      SYS_DBURIGEN(EMPLOYEE_ID,EMAIL)(URL, SPARE)
      -------------------------------------------------------------------
      DBURITYPE('/PUBLIC/EMPLOYEES/ROW[EMPLOYEE_ID = "206"]/EMAIL', NULL)

  `SYS_DBURIGEN()` function takes as its argument one or more columns or attributes, and optionally a rowid, and generates a URL of datatype `DBUriType` to a particular column or row object. You can then use the URL to retrieve an XML document from the database. The function takes an additional parameter to indicate if the text value of the node is needed.

  All columns or attributes referenced must reside in the same table. They must perform the function of a primary key. That is, they need not actually match the primary keys of the table, but they must reference a unique value. If you specify multiple columns, all but the final column identify the row in the database, and the last column specified identifies the column within the row.

  By default the URL points to a formatted XML document. If you want the URL to point only the text of the document, specify the optional '`text()`'. (In this XML context, the lowercase '`text`' is a keyword, not a syntactic placeholder.)

  If the table or view containing the columns or attributes does not have a schema specified in the context of the query, Oracle interprets the table or view name as a public synonym.

  The column or attribute passed to the `SYS_DBURIGEN()` function must obey the following rules:

  - Unique mapping: The column or UDT attribute must be uniquely mappable back to the table or view from which it comes. This means that virtual columns are not allowed. The only exception is the VALUE and REF operators. The column may come from a TABLE() subquery or an online view provided that the online view does not rename the columns.

  - Key columns: Either the rowid or a set of key columns must be specified. The list of key columns need not match the list of keys in the table so long as the columns can uniquely identify a particular row in the result.

  - Same table: All columns referenced in the `SYS_DBURIGEN()` function MUST come from the same table or view.

  - PUBLIC element: If the table or view pointed by the rowid or key columns does not have a database schema specified, then the PUBLIC keyword would be used instead of the schema. This has the effect of using the current binding (that is, table or synonym or view) to the table name when the DBUri is accessed.

  - TEXT function: DBuri, by default, retrieves an XML document containing the result. To retrieve only the text value, use the 'text()' keyword as the final argument to the function.

    For example:

        select SYS_DBURIGEN(empno,ename,'text()') from scott.emp,

    generates a URL of the form:

        /SCOTT/EMP/ROW[EMPNO=7369]/ENAME/text()

  - Single column argument: If there is a single column argument, then the column is used both as the key column to identify the row and as the referenced column. For example:

        select SYS_DBURIGEN(empno) from emp;

    would use the empno both as the key column and the referenced column, that is, it would generate a URL of the form:

        /SCOTT/EMP/ROW[EMPNO=7369]/EMPNO,

    for the row which has empno = 7369.

  ### SYS_DBURIGEN Example 1: Inserting Database References

      CREATE TABLE doc_list_tab(docno number primary key, doc_ref SYS.DBUriType);

      -- inserts /SCOTT/EMP/ROW[rowid='xxx']/EMPNO
      INSERT INTO doc_list_tab(1001,
           (select SYS_DBURIGEN(rowid,empno) from emp where empno = 100);

      -- insert a Uri-ref to point to the empname column of emp!
      INSERT INTO doc_list_tab
         select empno, SYS_DBURIGEN(empno, ename) from emp));

      -- result of the DBURIGEN looks like, /SCOTT/EMP/ROW[EMPNO=7369]/ENAME

  ### SYS_DBURIGEN Example 2: Returning Partial Results

  When selecting the results of a column such as a lob column, you might want to retrieve only a portion of the result and create a URL to the column instead. For example, consider the case of a travel story web site. If you have a table which stores all the travel stories and the user queries over the table to find all relevant stories according to his search criterion, then you do not want to list the entire story in the result page. You, instead show the first 100 characters or the gist of the story and then return a URL to the actual story instead.

  This can be done as follows:

  Assume that the travel story table is defined as follows:

      create table travel_story
      (
        story_name varchar2(100),
        story clob
      );

      -- insert some value..!
      insert into travel_story values ('Egypt','This is my story of how I spent my
      time in Egypt, with the pyramids in full view from my hotel room');

  Now, you create a function that returns only the first 20 characters from the story,

      create function charfunc(clobval IN clob ) return varchar2 is
       res varchar2(20);
       amount number := 20;
      begin
        dbms_lob.read(clobval,amount,1,res);
        return res;
      end;
      /

  Now, you create a view which selects out only the first 100 characters from the story and then returns a DBUri reference to the story column.

      create view travel_view as select story_name, charfunc(story) short_story,
         SYS_DBURIGEN(story_name,story,'text()') story_link
      from travel_story;

  Now, a select from the view returns the following:

      select * from travel_view;

      STORY_NAME      SHORT_STORY             STORY_LINK
      -----------------------------------------------------------------------------
      Egypt           This is my story of h

      SYS.DBUriType('/PUBLIC/TRAVEL_STORY/ROW[SHORT_STORY='Egypt']/STORY/text()')

  ### SYS_DBURIGEN Example 3: RETURNING Uri-refs

  You can use `SYS_DBURIGEN` in the RETURNING clause of DML statements. This is useful to retrieve the URL to an object inserted. For example, consider table, clob_tab:

      CREATE TABLE clob_tab ( docid number, doc clob);

  If you insert a document, you may need to retrieve a URL to that document and store it in another table, uri_tab. This would be useful for auditing or other purposes.

      CREATE TABLE uri_tab (docs sys.DBUriType);

  You can do that as part of the insertion into clob_tab, using the RETURNING clause. You can use the EXECUTE IMMEDIATE syntax to execute the `SYS_DBURI` function inside PL/SQL as follows:

      declare
        ret sys.dburitype;
      begin
        -- exucute the insert and get the url
       EXECUTE IMMEDIATE
      'insert into clob_tab values (1,''TEMP CLOB TEST'')
       RETURNING SYS_DBURIGEN(docid, doc, ''text()'') INTO :1 '
       RETURNING INTO ret;
       -- insert the url into uri_tab
      insert into uri_tab values (ret);
      end;
      /

  The URL created would be of the form:

      /SCOTT/CLOB_TAB/ROW[DOCID="xxx"]/DOC/text()

  Note: The text() keyword is appended to the end, indicating that you want the URL to return just the CLOB value and not an XML document enclosing the CLOB text.

  ## Accessing DBUri-refs From Your Browser Using Servlets

  DBUri reference, is a database reference. It can be extended to be accessible from your browser or any other web server in the following ways:

  - By writing a servlet that runs on the Oracle Servlet Engine or the Apache JServ module which can execute the DBUri-ref URL and return the values

  - Through the default servlet provided to perform the same task. This servlet can only be run on the OSE as it uses JNI (Java Native Interface) to talk to the DBUri resolution code linked in to the server.

  ### oracle.xml.dburi.OraDbUriServlet() Servlet Mechanism

  For the above methods, a servlet, `OraDBUriServlet()` class, runs in Oracle servlet engine. This servlet takes in a path expression following the servlet name as the DbUri reference and outputs the document pointed to by the DBUri to the output stream. It can do either of the following:

  - Generate the MIME type of the document automatically. In this release the only values supported are "text/xml" and "text/plain". In the case the DBUri ends in a text() function, then the "text/plain" mime type is used, else an XML document is generated with the mime type of "text/xml".

  - Override the mime value using the contenttype argument to the servlet.

  For example to retrieve the empno column of employee table, you can write a URL such as one of the following:

  - http://machine.oracle.com:8080/oradb/SCOTT/EMP/ROW[EMPNO=7369]/ENAME/text() -- Generates a contenttype of text/plain

  - http://machine.oracle.com:8080/oradb/SCOTT/EMP/ROW[EMPNO=7369/ENAME -- Generates a contenttype of text/xml

  where the machine machine.oracle.com is running the OSE, with a web service at port 8080 listening to requests. The oradb is the virtual path that maps to the OraDbUriServlet.

  Note: In HTTP access special characters such as, ']','[','&','|' have to be escaped using the %xxx format, where the xxx is the decimal number that points to the ASCII code for that character. Use the getExternalUrl() function in the UriType family to get the escaped URL version.

  ### OraDBUriServlet Security

  Consider these security issues when publishing `OraDbServlet`:

  - Publishing `OraDBServlet` Under the DBUser realm

  - Publishing `OraDBServlet` Under no realm

  #### Publishing OraDBServlet Under the DBUser Realm

  The OraDBUri servlet supplied, when published under the `DbUser` realm, automatically switches to the authenticated user and executes the query under that authenticated user.

  For example:

  - If the servlet is published as SYS under the DBUser realm, then the queries are always executed as the user who is logged in.

  - If the servlet is published under the Rdbms realm, then the servlet is run as the publisher and not as the authenticated user.

  Take care that the servlet is not published under a realm other than the DBUser realm, particularly, if it is published in the SYS schema or if you want to enforce security to data access.

  #### Publishing OraDBServlet Under No Realm

  If you do not publish the servlet under any realm, then the users can access the servlet directly without having to enter any username/password. The servlet executes under the privileges of the published user, and users of the servlet can access all data that the published user is privileged to see.

  This can be useful in cases where you have a user that has restricted privileges and contains data (such as documents or demos or example schemas), which you would like any user to access.

  For example, you can have a HELP user containing all helpful documentation related to a product or a company's operations and publish the servlet in that schema, giving access to everyone to access all the documents.

  Special Note: If you publish the servlet under a realm other than the DbUserRealm, then queries are executed under the published user. So care MUST be taken to publish the servlet only in the DBUser realm, or if published under some other realm, the privileges granted to the published user must be limited. See the examples, starting with: "DBUri Servlet Example 1: First Create a DBUriServer Web Service [tkxmsrv.ssh]" . Do not publish the servlet in any other realm other than the DBUser realm for the SYS user, otherwise users accessing the servlet will have privileges to access all your database data!

  ### Installing OraDBUri Servlet

  `OraDbUriServlet` is shipped in the jar file OraDbUri.jar under rdbms/jlib/ directory in your $ORACLE_HOME. To install the servlet, perform the following tasks:

  You can skip the first two steps, since the Java classes corresponding to the Java classes is already installed under the SYS user and execute privileges are granted to all the users. However, if you want the Java classes corresponding to the servlet to reside in your schema, then perform the following steps:

  1. Run SQL*Plus and connect to the required schema that you want to install the servlet under. The preferred schema is the SYS schema.

  2. Load the jar file in to the required schema by running the inituris.sql script found in the admin directory. You can also use loadjava to load the jar file into the schema. You need IO privileges to access files when running the dbms_java interface.

  3. Now use the sess_sh to connect to your database at the admin port. See the Oracle9i Oracle Servlet Engine User's Guide for more details.

  4. Set up the appropriate web services and realms. An example of setting up a DBUser realm is available under the servlet demos.

  5. Once you have set up all the necessary realms and contexts, publish the servlet. For example in the sess_sh shell:

         publishservlet -virtualpath /oradb/*  -stateless
         /webdomains/default/contexts DBUriServlet SYS:oracle.xml.uri.OraDbUriServlet

     - Note the use of /oradb/*. The * is necessary to indicate that any path following oradb is to be mapped to the same servlet. The oradb is published as the virtual path. Here, if you have installed the servlet in your own schema, then change the SYS: keyword to the schema name that the servlet is installed under.

     - The stateless parameter indicates that the servlet itself is stateless and hence the same connection can be used to invoke the servlet.

     - The /webdomains/default/contexts is the context under which the servlet is being published. Note that a context may have a virtual path already defined, in which case the virtual path that you publish the servlet under would be under that path. For example, if the context given here had a virtual path of /servlets, then the DBUriServlet can be accessed by the path /servlets/oradb/*.

     - The `DBUriServlet` is the name of the servlet.

     - The`oracle.xml.uri.OraDbUriServlet` is the name of the class to use under the SYS schema. Change the schema name to the schema under which the jar file was loaded.

     - After this you can access the servlet directly through the Apache server using the mod_ose module or go directly to the OSE through the port on which the web service is listening.

  ### DBUri Servlet Example 1: First Create a DBUriServer Web Service [tkxmsrv.ssh]

  Script `tkxmsrv.ssh`, creates a DBUriServer Web service at port 8088 (hard coded in the script) and assigns ownership of the service to the user whose ID is passed as a parameter to the script. This script must be run before running any of the following scripts. In the environment in which the script was created, AURORA_AWS_ADMIN_PORT is set to 8080 and we have to connect to AURORA_AWS_ADMIN_PORT to do administrative activities. You can configure the Web service for any port by changing this part of the script.

      #   USAGE :
      #   sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsrv.ssh
      <user-name>"
      #
      # This script does the following :
      #   1. Creates dburiServer service with -root /dburidomain.
      #   2. Assigns ownership to user passed as parameter

      destroywebdomain dburidomain
      destroyservice   dburiServer

      echo "Creating dburiService ..."
      createwebservice -root /dburidomain dburiServer

      #The following line requires this script to be run as SYS
      rmendpoint -force dburiServer main
      addendpoint -port 8088 -register dburiServer main

      chown -R &1 /dburidomain

      echo "Service creation complete"

  ### DBUri Servlet Example 2: Creating DBUridomain -- Publishing OraDbUriServlet

  This script creates webdomain under the service created by `tkxmsrv.ssh`. It publishes URI servlet in this domain using the default context. URI Servlet classes must be loaded under the SYS schema before running this script.

      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsrv.ssh SYS"
      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsys.ssh"

      #   USAGE :
      #   sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsys.ssh"
      #   tkxmsrv.ssh must be run before running this script.
      #
      # This script does the following :
      #   1. Creates webdomain /dburidomain.
      #   2. Publishes the OraDbUriServlet servlet under SYS.

      echo "Creating dburidomain ..."
      createwebdomain /dburidomain

      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/default -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/default -add /errors/internal -scheme <NONE>

      echo "Domain creation complete"

      echo "Publishing servlet under default context .."

      publishservlet /dburidomain/contexts/default -virtualpath /norealm/*
      DBUriServlet SYS:oracle.xml.dburi.OraDbUriServlet

      echo "Servlet publishing complete .."

  ### DBUri Servlet Example 3: Publishing OraDbUriServlet Under SYS [tkxmsysd.ssh]

  This script creates a webdomain under the service created by `tkxmsrv.ssh`. It publishes URI servlet in this domain using the default context mapped to DBUSER-realm. URI Servlet classes must be loaded under SYS schema before running this script.

      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsrv.ssh SYS"
      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsysd.ssh"

      #   USAGE :
      #   sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsysd.ssh"
      #   tkxmsrv.ssh must be run before running this script.
      #
      # This script does the following :
      #   1. Creates webdomain /dburidomain.
      #   2. Creates and protects dburirealm
      #   3. Publishes the OraDbUriServlet servlet under SYS.
      #   4. Grant permission to execute the servlet to SCOTT and ADAMS.

      echo "Creating dburidomain ..."
      createwebdomain /dburidomain
      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/default -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/default -add /errors/internal -scheme <NONE>
      echo "Domain creation complete"

      echo "Creating and protecting dburirealm "
      realm publish -w /dburidomain -r dburirealm -type DBUSER
      realm publish -w /dburidomain -add dburirealm -type DBUSER
      realm map -s /dburidomain/contexts/default -add /oradb/* -scheme
      basic:dburirealm
      realm perm -w /dburidomain -realm dburirealm -s /dburidomain/contexts/default
      -name SYS -path /oradb/* + get,post
      realm perm -w /dburidomain -realm dburirealm -s /dburidomain/contexts/default
      -name SCOTT -path /oradb/* + get,post
      realm perm -w /dburidomain -realm dburirealm -s /dburidomain/contexts/default
      -name ADAMS -path /oradb/* + get,post
      echo "Realm creation complete"

      echo "Publishing servlet under default context .."

      publishservlet /dburidomain/contexts/default -virtualpath /oradb/* DBUriServlet
      SYS:oracle.xml.dburi.OraDbUriServlet

      chmod +x SCOTT /dburidomain/contexts/default/named_servlets/DBUriServlet

      chmod +x ADAMS /dburidomain/contexts/default/named_servlets/DBUriServlet

      echo "Servlet publishing complete .."

  ### DBUri Servlet Example 4: Publishing OraDbUriServlet Under ADAMS

  This script creates webdomain under the service created by `tkxmsrv.ssh`. It publishes URI servlet in this domain using the uritests context. URI Servlet classes must be loaded under SYS schema before running this script.

      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsrv.ssh
      ADAMS"
      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmadam.ssh"

      #   USAGE :
      #   sess_sh -s http://localhost:8080 -u adams/wood -c "@tkxmadam.ssh"
      #   tkxmsrv.ssh must be run before running this script.
      #
      # This script does the following :
      #   1. Creates webdomain /dburidomain.
      #   2. Creates uritests context.
      #   3. Publishes the OraDbUriServlet servlet under ADAMS using the class
      #      under SYS.

      echo "Creating dburidomain and uritests context ..."
      createwebdomain /dburidomain

      echo "Creating uritests context ..."
      createcontext -virtualpath /adamscon/ /dburidomain uritests

      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/default -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/default -add /errors/internal -scheme <NONE>

      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/uritests -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/uritests -add /errors/internal -scheme <NONE>

      echo "Domain creation complete"

      echo "Publishing servlet under uritests context"

      publishservlet /dburidomain/contexts/uritests -virtualpath /adamsdb/*
      DBUriServlet SYS:oracle.xml.dburi.OraDbUriServlet

      echo "Servlet publishing complete .."

  ### DBUri Servlet Example 5: Publishing OraDbUriServlet Under SCOTT [tkxmsctd.ssh]

  This script creates webdomain under the service created by `tkxmsrv.ssh`. It publishes URI servlet in this domain using the uritests context mapped to DBUSER-realm. URI Servlet classes must be loaded under SYS schema before running this script.

      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsrv.ssh
      SCOTT"
      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsctd.ssh"

      #   USAGE :
      #   sess_sh -s http://localhost:8080 -u scott/tiger -c "@tkxmsctd.ssh"
      #   tkxmsrv.ssh must be run before running this script.
      #
      # This script does the following :
      #   1. Creates webdomain /dburidomain.
      #   2. Creates uritests context.
      #   3. Creates and protects dburirealm
      #   4. Publishes the OraDbUriServlet servlet under SCOTT.

      echo "Creating dburidomain and uritests context ..."
      createwebdomain /dburidomain

      echo "Creating uritests context and granting ownership to SCOTT ..."
      createcontext -virtualpath /scottcon/ /dburidomain uritests

      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/default -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/default -add /errors/internal -scheme <NONE>

      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/uritests -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/uritests -add /errors/internal -scheme <NONE>

      echo "Domain creation complete"

      echo "Creating and protecting dburirealm "
      realm publish -w /dburidomain -r dburirealm -type DBUSER
      realm publish -w /dburidomain -add dburirealm -type DBUSER
      realm map -s /dburidomain/contexts/uritests -add /scottdb/* -scheme
      basic:dburirealm
      realm perm -w /dburidomain -realm dburirealm -s /dburidomain/contexts/uritests
      -name PUBLIC -path /scottdb/* + get,post
      echo "Realm creation complete"

      echo "Publishing servlet under uritests context"

      publishservlet /dburidomain/contexts/uritests -virtualpath /scottdb/*
      DBUriServlet SYS:oracle.xml.dburi.OraDbUriServlet

      echo "Servlet publishing complete .."

  ### DBUri Servlet Example 6: Creating and Mapping dburirealm -- OraDbUriServlet

  This script creates webdomain under the service created by `tkxmsrv.ssh`. It publishes URI servlet in this domain using the default context mapped to RDBMS-realm. URI Servlet classes must be loaded under SYS schema before running this script.

      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsrv.ssh SYS"
      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsysr.ssh"

      #   USAGE :
      #   sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsysr.ssh"
      #   tkxmsrv.ssh must be run before running this script.
      #
      # This script does the following :
      #   1. Creates webdomain /dburidomain.
      #   2. Creates and protects dburirealm using RDBMS realm mapping.
      #   3. Publishes the OraDbUriServlet servlet under SYS.
      #   4. Grant permission to execute the servlet to SCOTT and ADAMS.

      echo "Creating dburidomain ..."
      createwebdomain /dburidomain
      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/default -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/default -add /errors/internal -scheme <NONE>
      echo "Domain creation complete"

      echo "Creating and protecting dburirealm "

      realm publish -w /dburidomain -r dburirealm -type rdbms
      realm publish -w /dburidomain -add dburirealm -type rdbms
      # create a user in the realm
      realm user -w /dburidomain -realm dburirealm -add alex -p welcome
      # create a group in the realm
      realm group -w /dburidomain -realm dburirealm -add uriGroup -p welcome
      # add 'alex' to the 'uriGroup'
      realm parent -w /dburidomain -realm dburirealm -group uriGroup -add alex
      # Allow 'uriGroup' to execute http requests with the GET,POST methods
      realm perm -w /dburidomain -realm dburirealm -s /dburidomain/contexts/default
      -name uriGroup -path /rdbrealm/* + get,post
      # protect the resource '/rdbrealm'
      realm map -s /dburidomain/contexts/default -add /rdbrealm/* -scheme
      Basic:dburirealm

      echo "Realm creation complete"

      echo "Publishing servlet under default context .."

      publishservlet /dburidomain/contexts/default -virtualpath /rdbrealm/*
      DBUriServlet SYS:oracle.xml.dburi.OraDbUriServlet

      chmod +x SCOTT /dburidomain/contexts/default/named_servlets/DBUriServlet

      echo "Servlet publishing complete .."

  ### DBUri Servlet Example 7: Publishing OraDbUriServlet Under the ADAMS Schema

  This script creates webdomain under the service created by `tkxmsrv.ssh`. It publishes URI servlet in this domain using `uritests` context. URI Servlet classes must be loaded under ADAMS schema before running this script.

      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsrv.ssh
      ADAMS"
      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmadmn.ssh"

      #   USAGE :
      #   sess_sh -s http://localhost:8080 -u adams/wood -c "@tkxmadmn.ssh"
      #   tkxmsrv.ssh must be run before running this script.
      #
      # This script does the following :
      #   1. Creates webdomain /dburidomain.
      #   2. Creates uritests context.
      #   3. Publishes the OraDbUriServlet servlet under ADAMS using the class
      #      under ADAMS.

      echo "Creating dburidomain and uritests context ..."
      createwebdomain /dburidomain

      echo "Creating uritests context ..."
      createcontext -virtualpath /adamscon/ /dburidomain uritests

      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/default -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/default -add /errors/internal -scheme <NONE>

      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/uritests -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/uritests -add /errors/internal -scheme <NONE>

      echo "Domain creation complete"

      echo "Publishing servlet under uritests context"

      publishservlet /dburidomain/contexts/uritests -virtualpath /adamsdb/*
      DBUriServlet ADAMS:oracle.xml.dburi.OraDbUriServlet

      echo "Servlet publishing complete .."

  ### DBUri Servlet Example 8: Publishing OraDbUriServlet Under the ADAMS Schema

  This script creates webdomain under the service created by `tkxmsrv.ssh`. It publishes URI servlet in this domain using uritests context mapped to DBUSER-realm. URI Servlet classes must be loaded under ADAMS schema before running this script.

      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmsrv.ssh
      ADAMS"
      sess_sh -s http://localhost:8080 -u sys/change_on_install -c "@tkxmadmd.ssh"

      #   USAGE :
      #   sess_sh -s http://localhost:8080 -u adams/wood -c "@tkxmadmd.ssh"
      #   tkxmsrv.ssh must be run before running this script.
      #
      # This script does the following :
      #   1. Creates webdomain /dburidomain.
      #   2. Creates uritests context.
      #   3. Creates and protects dburirealm
      #   4. Publishes the OraDbUriServlet servlet under ADAMS using the class
      #      under ADAMS.

      echo "Creating dburidomain and uritests context ..."
      createwebdomain /dburidomain

      echo "Creating uritests context and granting ownership to ADAMS ..."
      createcontext -virtualpath /adamscon/ /dburidomain uritests

      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/default -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/default -add /errors/internal -scheme <NONE>

      #ensure that error pages are not protected
      realm map -s /dburidomain/contexts/uritests -add /system/errors/* -scheme <NONE>
      realm map -s /dburidomain/contexts/uritests -add /errors/internal -scheme <NONE>

      echo "Domain creation complete"

      echo "Creating and protecting dburirealm "
      realm publish -w /dburidomain -r dburirealm -type DBUSER
      realm publish -w /dburidomain -add dburirealm -type DBUSER
      realm map -s /dburidomain/contexts/uritests -add /adamsdb/* -scheme
      basic:dburirealm
      realm perm -w /dburidomain -realm dburirealm -s /dburidomain/contexts/uritests
      -name PUBLIC -path /adamsdb/* + get,post
      echo "Realm creation complete"

      echo "Publishing servlet under uritests context"

      publishservlet /dburidomain/contexts/uritests -virtualpath /adamsdb/*
      DBUriServlet ADAMS:oracle.xml.dburi.OraDbUriServlet

      echo "Servlet publishing complete .."

  ### Configuring the UriFactory Package to Handle DBUri-refs

  The UriFactory, as explained earlier, "UriFactory Package" , if given an URL, would generate the appropriate subtypes of the UriType to handle the particular protocol. In the case of HTTP URLs, UriFactory would create instances of the HttpUriType. But, when you have a HTTP url which is really pointing into the database using the DBUri-ref mechanism, then it would be more efficient to store and process it as a DBUriType instance in the database.

  Inside the server, it is always more efficient to process the DBUri-ref directly using the DBUriType instances, instead of going through the HTTP URL mechanism. This is because the latter involves additional data transfer through the JavaVM, servlet, and web server layers, and could introduce additional character conversions.

  If you have installed OraDBUriServlet to process the DBUri-refs, so that any URL such as `http://machine-name/servlets/oradb/` gets handled by that servlet, then you can configure the UriFactory to use that prefix and create instances of the DBUriType instead of the HttpUriType.

      begin
       -- register a new handler for the dburi prefix..
      urifactory.registerHandler('http://machine-name/servlets/oradb'
              ,'SYS','DBURITYPE', true,true);
      end;
      /

  Once you have executed this block in your session, then any `UriFactory.getUri()` call in that session, would automatically create an instance of the DBUriType for those HTTP URLs that have the prefix. In this way, you can convert the true DBUri URLs in to DBUriType instances for efficient processing.

| Copyright © 2001, 2003 Oracle Corporation. All Rights Reserved. |
Home | Contents | Index