3 OraDAV Programming Interface

OraDAV provides PL/SQL methods (including procedures and functions) that let you expose Oracle Multimedia objects. Exposing objects makes them visible as files in a container for access through a Web browser. When you expose an object, it is not actually copied into the container; instead, only a reference to the content is inserted into the container. Oracle Multimedia OraDAV driver does not support DAV methods that modify exposed objects.

These PL/SQL methods are in a package named DAV_PUBLIC under the ORDSYS schema. By using these methods, you can expose content from existing tables that contain columns of type ORDImage, ORDAudio, ORDVideo, ORDDoc, or BLOB.

These tables can be in different schemas from the one containing your OraDAV container, as long as the container's schema is granted the proper access to the tables. (Containers are explained in Chapter 2.)

Note:

Do not use methods in the DAV_PUBLIC package on any of the container system tables and views described in Chapter 2. Use these methods only for objects stored in tables other than the container system tables and views.

3.1 Options for Exposing Content

You can expose a single object at a time, or all objects in a column:

The Expose_Resource_By_Rowid procedure exposes the single object in a specified column in the row with the associated ROWID.
The Expose_OracleMultimedia_Column and Expose_Blob_Column procedures expose all objects in a specified column.

The following sections describe examples of both options for exposing objects. See Chapter 4 for reference information about these procedures.

The examples in this chapter as well as those in Chapter 4 assume that you work for a real estate firm that wants to make pictures and descriptions of houses for sale available at its Web site. Your database and system setup includes the following:

A container named mywebsite has been created in schema SCOTT (see the creating container example in the README.txt file).
User REALTOR has a table called HOUSES.
The HOUSES table has a column called HOUSE_ID that uniquely identifies each row.
The HOUSES table has a column called HOUSE_PIX, which is of type ORDImage.
The HOUSES table has a column called HOUSE_DOC, which is of type BLOB.
The ORDImage.setProperties( ) method has been invoked such that the contentLength and mimeType attributes of the ORDImage objects are set.
User REALTOR has granted SELECT access on HOUSES to SCOTT.
An OraDAV-enabled Oracle HTTP Server is running on host mywebserver.
That Oracle HTTP Server has been configured with an OraDAV-enabled location called /oradav.

To run these examples, connect to the database as SCOTT.

3.1.1 Example: Exposing a Single Object

Example 3-1 extracts information to uniquely identify the desired object and exposes it, associating it with a URL.

Example 3-1 Exposing a Single Object

DECLARE 
   ldocid INTEGER; 
   loblen INTEGER; 
   lrowid UROWID; 
BEGIN 
SELECT rowid,DBMS_LOB.GETLENGTH(HOUSE_DOC) 
           INTO lrowid, loblen 
           FROM REALTOR.HOUSES 
           WHERE HOUSE_ID = 1; 
ORDSYS.DAV_PUBLIC.expose_resource_by_rowid ( 
   ORDSYS.DAV_PUBLIC.generate_ctx('mywebsite'), 
   'REALTOR', 
   'HOUSES', 
   'HOUSE_DOC', 
   'BLOB', 
   lrowid, 
   '/external_collection', 
   'house', 
   '.html', 
   'text/html', 
   loblen, 
   SYSDATE, 
   ORDSYS.DAV_PUBLIC.DUPE_MODE_FAIL, 
   ldocid); 
COMMIT; 
END; 
/

Upon successful execution of the code in this example, the following URL will return the Web page from REATOR.HOUSES where the HOUSE_ID is 1 (assuming that httpd.conf contains <Location /oradav>):

http://mywebserver/oradav/external_collection/house.html

3.1.2 Example: Exposing All Objects in a Column

If you want to expose all objects in a multimedia column and if it seems too tedious to expose the objects one at a time, you can expose all of the objects in the column by using the Expose_OracleMultimedia_Column procedure (for ORDImage, ORDAudio, ORDVideo, or ORDDoc data) or the Expose_Blob_Column procedure (for BLOB data).

Example 3-2 exposes all the images in the HOUSE_PIX column.

Example 3-2 Exposing All Objects in a Column

DECLARE 
BEGIN 
ORDSYS.DAV_PUBLIC.expose_OracleMultimedia_column( 
   ORDSYS.DAV_PUBLIC.generate_ctx('mywebsite'), 
   'REALTOR', 
   'HOUSES', 
   'HOUSE_PIX', 
   'HOUSE_ID', 
   NULL, 
   NULL, 
   NULL, 
   1,  
   ORDSYS.DAV_PUBLIC.DUPE_MODE_FAIL); 
COMMIT; 
END; 
/

Upon successful execution of the code in this example, all house pictures in REALTOR.HOUSES can be returned by URLs that all start with http://mywebserver/oradav/REALTOR/HOUSES/HOUSE_PIX. The remainder of each URL will be the value of the HOUSE_ID column for that house. For example, the following URL will return the image from REALTOR.HOUSES where the HOUSE_ID is 1:

http://mywebserver/oradav/REALTOR/HOUSES/HOUSE_PIX/1.jpg

3.2 DAV Methods on Exposed Data

The OraDAV implementation allows some DAV protocol methods on exposed data and disallows other methods, as shown in Table 3-1.

Table 3-1 DAV Methods on Exposed Data

Method	Allowed?
GET	Yes
COPY	Yes, as long as the destination is not an exposed collection
PROPFIND	Yes (but you can restrict massive collections by using <Limit> in the `httpd.conf` file)
OPTIONS	Yes
DELETE	Yes (The reference to the data is removed.)
MKCOL	No
PROPPATCH	Yes
PUT	No
LOCK	No
MOVE	No
POST	No
UNLOCK	Yes (but it will always fail because LOCK is not allowed)

If you are using a client on exposed data and a command or operation fails, it may be because the application's command or operation maps to (is implemented using) a DAV method that OraDAV does allow to be used on exposed data.

For more information about DAV methods, see RFC2518 (HTTP Extensions for Distributed Authoring -- WEBDAV).

3.3 Duplicate File Behavior Options

Procedures that expose a resource or a column have a p_dupe_behavior parameter that controls the behavior when a call to the procedure would result in a duplicate file being added to the collection. For example, if the procedure attempts to expose a file named emp100id.jpg and a file named emp100id.jpg is already exposed at the specified location (path), the value of the p_dupe_behavior parameter determines how this condition is handled.

Table 3-2 lists the currently supported values for the dupe_behavior parameter.

Table 3-2 dupe_behavior Parameter Values

Value	Explanation
DUPE_MODE_FAIL	Any duplicate file names result in an exception. Note that if the p_add_triggers parameter is set to TRUE, the trigger could also generate an exception from a simple SQL INSERT or UPDATE statement. Your application must be prepared to handle these exceptions.

See the descriptions for the p_dupe_behavior parameter as well as the usage notes for the Expose_Blob_Column, Expose_OracleMultimedia_Column, and Expose_Resource_By_Rowid procedures.

3.4 Context Parameter

A context parameter is required for enabling annotation and exposing or unexposing data . This parameter is a string in XML format. Because almost every OraDAV routine operates on a container, the context parameter must, at minimum, specify the container name, as shown in Example 3-3.

Example 3-3 Minimal Context Parameter

<ORADAV>
  <DAVPARAM>
    <ORACONTAINERNAME>sales</ORACONTAINERNAME>
  </DAVPARAM>
</ORADAV>

For many procedure calls, a minimal context parameter string such as the one shown in this example is sufficient. You can use the Generate_Ctx function to generate a minimal context string.