Skip Headers

Oracle® Application Developer's Guide - XML
10g (9.0.4)
Part Number B12099-01
Go To Documentation Library
Home		 Go To Table Of Contents
Contents		 Go To Index
Index

Go to previous page Go to next page

6
Database Uri-references

This chapter contains the following sections:

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:

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:

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.

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:

New Datatypes Store Uri-references

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

Figure 6-1 New UriTypes

Text description of xml_type.gif follows

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:

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:

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 adxml100.gif follows

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 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:

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:

Using Predicate (XPath) Expressions in DBUri

The predicate expressions can use the following XPath expressions:

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:

    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:

    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 adxml099.gif follows

    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:

    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.

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

    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 sys_dbur.gif follows

    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:

    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:

    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:

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

    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

    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:

    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.

    • Go to previous page Go to next page
    		Oracle
    Copyright © 2001, 2003 Oracle Corporation.
    All Rights Reserved.
    Go To Documentation Library
    Home    		 Go To Table Of Contents
    Contents    		 Go To Index
    Index