You can enable applications to use DBFS using the DBFS Content API (DBMS_DBFS_CONTENT), which is a client-side programmatic API package.

You can write applications in SQL, PL/SQL, JDBC, OCI, and other programming environments.

The DBFS Content API is a collection of methods that provide a file system-like abstraction. It is backed by one or more DBFS Store Providers. The Content in the DBFS Content interface refers to a file, including metadata, and it can either map to a SecureFiles LOB (and other columns) in a table or be dynamically created by user-written plug-ins in Java or PL/SQL that run inside the database. The plug-in form is referred to as a provider.

Examples of possible providers include:

• Packaged applications that want to surface data through files.

• Custom applications developers use to leverage the file system interface, such as an application that stores medical images.

The DBFS Content API takes the common features of various stores and forms them into a simple interface that can be used to build portable client applications, while allowing different stores to implement the set of features they choose.

The DBFS Content API aggregates the path namespace of one or more stores into a single unified namespace, using the first component of the path name to disambiguate the namespace and then presents it to client applications. This allows clients to access the underlying documents using either a full absolute path name represented by a single string, in this form:

/store-name/store-specific-path-name

or a store-qualified path name as a string 2-tuple, in this form:

["store-name","/store-specific-path-name"]

The DBFS Content API then takes care of correctly dispatching various operations on path names to the appropriate stores and integrating the results back into the client-desired namespace.

Store providers must conform to the store provider interface (SPI) as declared by the package DBMS_DBFS_CONTENT_SPI.

• Creating Your Own DBFS Store

• Oracle Database PL/SQL Packages and Types Reference for DBMS_DBFS_CONTENT package syntax reference

DBMS_DBFS_CONTENT is part of the Oracle Database, starting with Oracle Database 11g Release 2, and does not need to be installed.

Administrative clients and content providers are expected to register content stores with the DBFS Content API. Additionally, administrative clients are expected to mount stores into the top-level namespace of their choice.

The registration and unregistration of a store is separated from the mount and unmount of a store because it is possible for the same store to be mounted multiple times at different mount points (and this is under client control).

This section covers the following topics:

• Registering a Content Store

• Unregistering a Content Store

• Mounting a Registered Store

• Unmounting a Previously Mounted Store

• Listing all Available Stores and Their Features

• Listing all Available Mount Points

• Looking Up Specific Stores and Their Features

You can query file system space usage statistics.

Normal client access to the DBFS Content API executes with an implicit context that consists of certain objects.

• The principal invoking the current operation.

• The owner for all new elements created (implicitly or explicitly) by the current operation.

• The ACL for all new elements created (implicitly or explicitly) by the current operation.

• The ASOF timestamp at which the underlying read-only operation (or its read-only sub-components) execute.

All of this information can be passed in explicitly through arguments to the various DBFS Content API method calls, allowing the client fine-grained control over individual operations.

The DBFS Content API also allows clients to set session duration defaults for the context that are automatically inherited by all operations for which the defaults are not explicitly overridden.

All of the context defaults start out as null and can be cleared by setting them to null.

To allow for the DBFS Content API itself to evolve, an internal numeric API version increases with each change to the public API.

Clients of the DBFS Content API refer to store items through absolute path names.

Absolute path names may be:

• fully qualified (a single string of the form /mount_point/pathname)

• store-qualified (a tuple of the form (store_name, pathname), where the path name is rooted within the store namespace)

Clients may use either naming scheme and can use both naming methods within their programs.

If path names are returned by DBFS Content API calls, the exact values being returned depend on the naming scheme used by the client in the call. For example, a listing or search on a fully qualified directory name returns items with their fully qualified path names, while a listing or search on a store-qualified directory name returns items whose path names are store-specific, and the store-qualification is implied.

The implementation of the DBFS Content API internally manages the normalization and inter-conversion between these two naming schemes.

You must implement the provider SPI so that when clients invoke the DBFS Content API, it causes the SPI to create directory, file, link, and reference elements (subject to store feature support).

All of the creation methods require a valid path name and can optionally specify properties to be associated with the path name as it is created. It is also possible for clients to fetch back item properties after the creation completes, so that automatically generated properties, such as std_creation_time, are immediately available to clients. The exact set of properties fetched back is controlled by the various prop_xxx bit masks in prop_flags.

Links and references require an additional path name associated with the primary path name. File path names can optionally specify a BLOB value to initially populate the underlying file content, and the provided BLOB may be any valid LOB, either temporary or permanent. On creation, the underlying LOB is returned to the client if prop_data is specified in prop_flags.

Non-directory path names require that their parent directory be created first. Directory path names themselves can be recursively created. This means that the path name hierarchy leading up to a directory can be created in one call.

Attempts to create paths that already exist produce an error, except for path names that are soft-deleted. In these cases, the soft-deleted item is implicitly purged, and the new item creation is attempted.

Stores and their providers that support contentID-based access accept an explicit store name and a NULL path to create a new content element. The contentID generated for this element is available by means of the OPT_CONTENT_ID property. The PROP_OPT property in the prop_flags parameter automatically implies contentID-based creation.

The newly created element may also have an internally generated path name if the FEATURE_LAZY_PATH property is not supported and this path is available by way of the STD_CANONICAL_PATH property.

Only file elements are candidates for contentID-based access.

You must implement the provider SPI so that when clients invoke the DBFS Content API, it causes the SPI to delete directory, file, link, and reference elements (subject to store feature support).

By default, the deletions are permanent, and remove successfully deleted items on transaction commit. However, repositories may also support soft-delete features. If requested by the client, soft-deleted items are retained by the store. They are not, however, typically visible in normal listings or searches. Soft-deleted items may be restored or explicitly purged.

Directory path names may be recursively deleted; the path name hierarchy below a directory may be deleted in one call. Non-recursive deletions can be performed only on empty directories. Recursive soft-deletions apply the soft-delete to all of the items being deleted.

Individual path names or all soft-deleted path names under a directory may be restored or purged using the RESTOREXXX() and PURGEXXX() methods.

Providers that support filtering can use the provider filter to identify subsets of items to delete; this makes most sense for bulk operations such as deleteDirectory(), RESTOREALL(), and PURGEALL(), but all of the deletion-related operations accept a filter argument.

Stores and their providers that support contentID-based access can also allow deleting file items by specifying their contentID.

You can query existing path items or update them using simple GETXXX() and PUTXXX() methods.

All path names allow their metadata to be read and modified. On completion of the call, the client can request that specific properties be fetched through prop_flags.

File path names allow their data to be read and modified. On completion of the call, the client can request a new BLOB locator through the prop_data bit masks in prop_flags; these may be used to continue data access.

Files can also be read and written without using BLOB locators, by explicitly specifying logical offsets, buffer amounts, and a suitably sized buffer.

Update accesses must specify the forUpdate flag. Access to link path names may be implicitly and internally dereferenced by stores, subject to feature support, if the deref flag is specified. Oracle does not recommend this practice because symbolic links are not guaranteed to resolve.

The read method GETPATH() where forUpdate is false accepts a valid asof timestamp parameter that can be used by stores to implement flashback-style queries.

Mutating versions of the GETPATH() and the PUTPATH() methods do not support asof modes of operation.

The DBFS Content API does not have an explicit COPY() operation because a copy is easily implemented as a combination of a GETPATH() followed by a CREATEXXX() with appropriate data or metadata transfer across the calls. This allows copies across stores, while an internalized copy operation cannot provide this facility.

You can rename or move path names, possibly across directory hierarchies and mount points, but only within the same store.

Non-directory path names previously accessible by oldPath can be renamed as a single item subsequently accessible by newPath, assuming that newPath does not exist.

If newPath exists and is not a directory, the rename implicitly deletes the existing item before renaming oldPath. If newPath exists and is a directory, oldPath is moved into the target directory.

Directory path names previously accessible by oldPath can be renamed by moving the directory and all of its children to newPath (if it does not exist) or as children of newPath (if it exists and is a directory).

Because the semantics of rename and move is complex with respect to non-existent or existent and non-directory or directory targets, clients may choose to implement complex rename and move operations as sequences of simpler moves or copies.

Stores and their providers that support contentID-based access and lazy path name binding also support the Oracle Database PL/SQL Packages and Types Reference SETPATH procedure that associates an existing contentID with a new "path".

Directory listings are handled several different ways.

• A list_item_t is a tuple of path name, component name, and type representing a single element in a directory listing.

• A path_item_t is a tuple describing a store, mount qualified path in a content store, with all standard and optional properties associated with it.

• A prop_item_t is a tuple describing a store, mount qualified path in a content store, with all user-defined properties associated with it, expanded out into individual tuples of name, value, and type.

Clients of the DBFS Content API can list or search the contents of directory path names, with optional modes.

Optional Modes:

• searching recursively in sub-directories

• seeing soft-deleted items

• using flashback asof a provided timestamp

• filtering items in and out within the store based on list or search predicates.

The DBFS Content API currently only returns list items; clients explicitly use one of the getPath() methods to access the properties or content associated with an item, as appropriate.

DBFS Content API clients can apply user-level locks,depending on certain criteria.

Clients of the DBFS Content API can apply user-level locks to any valid path name, subject to store feature support, associate the lock with user data, and subsequently unlock these path names. The status of locked items is available through various optional properties.

If a store supports user-defined lock checking, it is responsible for ensuring that lock and unlock operations are performed in a consistent manner.

The DBFS Content API checks the access of specific path names by operations.

Function CHECKACCESS() checks if a given path name (path, pathtype, store_name) can be manipulated by an operation, such as the various op_xxx opcodes) by principal, as described in "DBFS Content API Locking Operations"

This is a convenience function for the client; a store that supports access control still internally performs these checks to guarantee security.

All of the operations in the DBFS Content API are represented as abstract opcodes.

Clients can useopcodes to directly and explicitly invoke the CHECKACCESS() method which verifies if a particular operation can be invoked by a given principal on a particular path name.

An op_acl() is an implicit operation invoked during an op_create() or op_put() call, which specifies a std_acl property. The operation tests to see if the principal is allowed to set or change the ACL of a store item.

op_delete() represents the soft-deletion, purge, and restore operations.

The source and destination operations of a rename or move operation are separated, although stores are free to unify these opcodes and to also treat a rename as a combination of delete and create.

op_store is a catch-all category for miscellaneous store operations that do not fall under any of the other operational APIs.

There is a process for performing API path normalization.

Function NORMALIZEPATH() performs the following steps:

1. Verifies that the path name is absolute (starts with a /).

2. Collapses multiple consecutive /s into a single /.

3. Strips trailing /s.

4. Breaks store-specific normalized path names into two components: the parent path name and the trailing component name.

5. Breaks fully qualified normalized path names into three components: store name, parent path name, and trailing component name.

Note that the root path / is special: its parent path name is also /, and its component name is null. In fully qualified mode, it has a null store name unless a singleton mount has been created, in which case the appropriate store name is returned.

The return value is always the completely normalized store-specific or fully qualified path name.

DBFS provides support to reduce the expense of collecting DBFS Content API statistics.

DBFS Content API statistics are expensive to collect and maintain persistently. DBFS has support for buffering statistics in memory for a maximum of flush_time centiseconds or a maximum of flush_count operations, whichever limit is reached first), at which time the buffers are implicitly flushed to disk.

Clients can also explicitly invoke a flush using flushStats. An implicit flush also occurs when statistics collection is disabled.

setStats is used to enable and disable statistics collection; the client can optionally control the flush settings by specifying non-null values for the time and count parameters.

Any DBFS Content API user (both clients and providers) can use DBFS Content API tracing, a generic tracing facility.

The DBFS Content API dispatcher itself uses the tracing facility.

Trace information is written to the foreground trace file, with varying levels of detail as specified by the trace level arguments. The global trace level consists of two components: severity and detail. These can be thought of as additive bit masks.

The severity component allows the separation of top-level as compared to low-level tracing of different components, and allows the amount of tracing to be increased as needed. There are no semantics associated with different levels, and users are free to set the trace level at any severity they choose, although a good rule of thumb would be to use severity 1 for top-level API entry and exit traces, severity 2 for internal operations, and severity 3 or greater for very low-level traces.

The detail component controls how much additional information the trace reports with each trace record: timestamps, short-stack, and so on.

function    getTrace
        return  integer;
    procedure   setTrace(
        trclvl      in              integer);
    function    traceEnabled(
        sev         in              integer)
        return  integer;
    procedure   trace(
        sev         in              integer,
        msg0        in              varchar2,
        msg1        in              varchar     default '',
        msg2        in              varchar     default '',
        msg3        in              varchar     default '',
        msg4        in              varchar     default '',
        msg5        in              varchar     default '',
        msg6        in              varchar     default '',
        msg7        in              varchar     default '',
        msg8        in              varchar     default '',
        msg9        in              varchar     default '',
        msg10       in              varchar     default '');

You can see descriptions of Content API structure and properties in certain views.

Certain views describe the structure and properties of Content API.