Getting Started with DBMS_DBFS

20.3.1 DBFS Content API Role

Access to the content operational and administrative API (packages, types, tables, and so on) is available through DBFS_ROLE.

The DBFS_ROLE can be granted to all users as needed.

20.3.2 Path Name Constants and Types

Path name constants are modeled after their SecureFiles LOBs store counterparts.

See Also:

DBMS_DBFS_CONTENT Constants for path name constants and their types

20.3.3 Path Properties

Every path name in a store is associated with a set of properties.

For simplicity and generality, each property is identified by a string name, has a string value (possibly null if not set or undefined or unsupported by a specific store implementation), and a value typecode, a numeric discriminant for the actual type of value held in the value string.

Coercing property values to strings has the advantage of making the various interfaces uniform and compact (and can even simplify implementation of the underlying stores), but has the potential for information loss during conversions to and from strings.

It is expected that clients and stores use well-defined database conventions for these conversions and use the typecode field as appropriate.

PL/SQL types path_t and name_t are portable aliases for strings that can represent pathnames and component names,

A typecode is a numeric value representing the true type of a string-coerced property value. Simple scalar types (numbers, dates, timestamps, etc.) can be depended on by clients and must be implemented by stores.

Since standard RDBMS typecodes are positive integers, the DBMS_DBFS_CONTENT interface allows negative integers to represent client-defined types by negative typecodes. These typecodes do not conflict with standard typecodes, are maintained persistently and returned to the client as needed, but need not be interpreted by the DBFS content API or any particular store. Portable client applications should not use user-defined typecodes as a back door way of passing information to specific stores.

See Also:

Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT constants and properties and the DBMS_DBFS_CONTENT_PROPERTY_T package

20.3.4 Content IDs

Content IDs are unique identifiers that represent a path in the store.

See Also:

Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT Content ID constants and properties

20.3.5 Path Name Types

Stores can store and provide access to eight types of entities.

The entities are:

type_file
type_directory
type_link
type_reference
type_scoket
type_character
type_block
type_fifo

Not all stores must implement all directories, links, or references.

See Also:

Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT constants and path name types

20.3.6 Store Features

In order to provide a common programmatic interface to as many different types of stores as possible, the DBFS Content API leaves some of the behavior of various operations to individual store providers to define and implement.

The DBFS Content API remains rich and conducive to portable applications by allowing different store providers (and different stores) to describe themselves as a feature set. A feature set is a bit mask indicating the supported features and the ones that are not supported.

See Also:

Oracle Database PL/SQL Packages and Types Reference for details of the store features and constants

20.3.7 Lock Types

Stores that support locking should implement three types of locks.

The three types of locks are: lock_read_only, lock_write_only, lock_read_write.

User locks (any of these types) can be associated with user-supplied lock_data. The store does not interpret the data, but client applications can use it for their own purposes (for example, the user data could indicate the time at which the lock was placed, and the client application might use this later to control its actions.

In the simplest locking model, a lock_read_only prevents all explicit modifications to a path name (but allows implicit modifications and changes to parent/child path names). A lock_write_only prevents all explicit reads to the path name, but allows implicit reads and reads to parent/child path names. A lock_read_write allows both.

All locks are associated with a principal user who performs the locking operation; stores that support locking are expected to preserve this information and use it to perform read/write lock checking (see opt_locker).

See Also:

Oracle Database PL/SQL Packages and Types Reference for details of the lock types and constants.

20.3.8 Standard Properties

Standard properties are well-defined, mandatory properties associated with all content path names, which all stores must support, in the manner described by the DBFS Content API.

Stores created against tables with a fixed schema may choose reasonable defaults for as many of these properties as needed, and so on.

All standard properties informally use the std namespace. Clients and stores should avoid using this namespace to define their own properties to prevent conflicts in the future.

See Also:

See Oracle Database PL/SQL Packages and Types Reference for details of the standard properties and constants

20.3.9 Optional Properties

Optional properties are well-defined but non-mandatory properties associated with all content path names that all stores are free to support (but only in the manner described by the DBFS Content API).

Clients should be prepared to deal with stores that support none of the optional properties.

All optional properties informally use the opt namespace. Clients and stores must avoid using this namespace to define their own properties to prevent conflicts in the future.

See Also:

Oracle Database PL/SQL Packages and Types Reference for details of the optional properties and constants

20.3.10 User-Defined Properties

You can define your own properties for use in your application.

Ensure that the namespace prefixes do not conflict with each other or with the DBFS standard or optional properties.

20.3.11 Property Access Flags

DBFS Content API methods to get and set properties can use combinations of property access flags to fetch properties from different namespaces in a single API call.

See Also:

Oracle Database PL/SQL Packages and Types Reference for details of the property access flags and constants

20.3.12 Exceptions

DBFS Content API operations can raise any one of the top-level exceptions.

Clients can program against these specific exceptions in their error handlers without worrying about the specific store implementations of the underlying error signalling code.

Store service providers, should try to trap and wrap any internal exceptions into one of the exception types, as appropriate.

See Also:

Oracle Database PL/SQL Packages and Types Reference for details of the Exceptions

20.3.13 Property Bundles

Property bundles are discussed as property_t record type and properties_t.

The property_t record type describes a single (value, typecode) property value tuple; the property name is implied.
properties_t is a name-indexed hash table of property tuples. The implicit hash-table association between the index and the value allows the client to build up the full dbms_dbfs_content_property_t tuples for a properties_t.

There is an approximate correspondence between dbms_dbfs_content_property_t and property_t. The former is a SQL object type that describes the full property tuple, while the latter is a PL/SQL record type that describes only the property value component.

There is an approximate correspondence between dbms_dbfs_content_properties_t and properties_t. The former is a SQL nested table type, while the latter is a PL/SQL hash table type.

Dynamic SQL calling conventions force the use of SQL types, but PL/SQL code may be implemented more conveniently in terms of the hash-table types.

DBFS Content API provides convenient utility functions to convert between dbms_dbfs_content_properties_t and properties_t.

The function DBMS_DBFS_CONTENT.PROPERTIEST2H converts a DBMS_DBFS_CONTENT_PROPERTIES_T value to an equivalent properties_t value, and the function DBMS_DBFS_CONTENT.PROPERTIESH2T converts a properties_t value to an equivalent DBMS_DBFS_CONTENT_PROPERTIES_T value.

See Also:

Oracle Database PL/SQL Packages and Types Reference for details of the PROPERTY_T record type

20.3.14 Store Descriptors

Store descriptors are discussed as store_t and mount_t records.

A store_t is a record that describes a store registered with, and managed by the DBFS Content API .
A mount_t is a record that describes a store mount point and its properties.

Clients can query the DBFS Content API for the list of available stores, determine which store handles accesses to a given path name, and determine the feature set for the store.

See Also:

Administrative and Query APIs
Oracle Database PL/SQL Packages and Types Reference for details of the STORE_T record type