This chapter contains these topics:
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 API is file plus metadata and it can either map to a SecureFiles BLOB (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. This latter form is what is referred to as a "provider."
DBFS Content API comes with a SecureFiles-based store provider implementation (DBMS_DBFS_SFS) to allow creation of SecureFiles LOB-based file systems. Additionally, applications can read and write content that is stored in other (third party) stores through the standard DBFS Content API interface.
Examples of possible providers include:
Content applications like Content DB.
Packaged applications that want to surface data through files.
Custom applications that want to leverage the file system interface. For example, an application that stores medical images.
A store is a collection of documents, each identified by a unique absolute path name, represented as a '/' followed by one or more component names that are separated by a '/'. Some stores may implement only a flat namespace, others might implement directories or folders implicitly, while still others may implement a comprehensive file system-like collection of entities. These may include hierarchical directories, files, symbolic links, hard links, references, and so on. They often include a rich set of metadata associated with documents, and a rich set of behaviors with respect to security, access control, locking, versioning, content addressing, retention control, and so on.
Because stores are typically designed and evolve independently of each other, applications that use a specific store are either written and packaged by the developers of the store, or else require the user to employ a store-specific API. This often requires a detailed knowledge of the schema of the database tables that are used to implement the store itself.
The DBFS Content API is a client-side programmatic API package, DBMS_DBFS_CONTENT, that abstracts out the common features of various stores into a simple and minimalist interface that can be used to build portable client applications while being insulated from store-specific libraries and implementations.
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, and presents this namespace to client applications. This allows clients to access the underlying documents using either a full absolute path name represented by a single string (/store_name/store_specific_path_name), or a store-qualified path name represented by a string tuple (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 service provider interface (SPI) as declared by the package DBMS_DBFS_CONTENT_SPI. The SPI is not a client-side API and serves as a private contract between the implementation of the DBFS Content API and various stores that have to be plugged into it.
The DBFS Content API defines client-visible behavior, both normal and exceptional, of various store operations, while allowing different stores to implement as rich a set of features as they choose. The API allows stores to self-describe their capabilities and allows intelligent client applications to tune their behavior based on these capabilities rather than hard-code logic specific to stores identified by name or by implementation.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT package
DBMS_DBFS_CONTENT is part of the Oracle Database, starting with Oracle Database 11g Release 2, and does not have to be installed.
See Oracle Database PL/SQL Packages and Types Reference for more information.
Access to the Content operational and administrative API (packages, types, tables, and so on) is available through dbfs_role. This role can be granted to all users as needed.
PATH_MAX is the maximum length of an absolute path name visible to clients. NAME_MAX is the maximum length of any individual component of an absolute path name visible to clients. These constants are modeled after their SecureFiles LOB Store counterparts.
PL/SQL types path_t and name_t are portable aliases for strings that can represent path names and component names.
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. However, this has the disadvantage of 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.
PROPNAME_MAX is the maximum length of a property name, and PROPVAL_MAX is the maximum length of the string value of a property.
PL/SQL types propname_t and propval_t are portable aliases for strings that can represent property names and values. A typecode is a numeric value (see the various constants defined in dbms_types) representing the true type of a string-coerced property value. Not all typecodes defined in dbms_types are necessarily even supportable in stores. Simple scalar types (numbers, dates, timestamps, and so on) can be depended upon by clients and must be implemented by stores.
Because standard RDBMS typecodes are positive integers, the DBFS Content API allows negative integers to represent client-defined types by negative typecodes. These typecodes do not conflict with standard typecodes, and are made persistent and returned to the client as needed, but need not be interpreted by the DBFS Content API or any particular store. Portable client applications must not use user-defined typecodes as a back-door way of passing information to specific stores.
The dbms_dbfs_content_property_t object type describes a single (name, value, typecode) property tuple. All properties: standard, optional, and user-defined, are described through such tuples.
dbms_dbfs_content_properties_t is a variable-sized array of property tuples. These two types are used by both the client-facing APIs and by the store providers for the DBFS Content API.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT constants and properties, and Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT_PROPERTY_T package.
Stores can store and provide access to four types of entities:
type_file is a regular file that stores content as a logically linear sequence of bytes accessed as a BLOB.
type_directory is a container of other path name types, including file types.
type_link is a symbolic link that is an uninterpreted string value associated with a path name. Because symbolic links may represent path names that fall outside the scope of any given store, or even the entire aggregation of stores managed by the DBFS Content API, or may not even represent path names, clients must be careful in creating symbolic links and stores must be careful in trying to resolve these links internally.
type_reference is a hard link, always a valid path name alias, to content.
Not all stores must implement all directories, links, or references. See "Store Features", and Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT constants and path name types.
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. However, it is still important to provide client-side programmers with an API that is sufficiently rich and conducive to portable applications.
The DBFS Content API achieves this by allowing different store providers (and different stores) to describe themselves as a feature set (a bit mask indicating which features they support and which ones they do not).
Using the feature set, it is possible, although tricky, for client applications to compensate for the feature deficiencies of specific stores by implementing additional logic on the client side, and deferring complex operations to stores capable of supporting them.
feature_folders is set if the store supports folders (or directories) as part of hierarchical path names.
feature_foiat is set if implicit folder operations within the store (performed as part of a client-requested operation) runs inside autonomous transactions. In general, the use of autonomous transactions is a compromise between simplicity in the implementation and client-controlled transaction scope for all operations, at the cost of greatly reduced concurrency (feature_foiat not set), and more complex implementation and smaller client-controlled transaction scope, at the benefit of greatly increased concurrency (feature_foiat set).
Access to read-only or read-mostly stores should not be greatly affected by this feature.
feature_acls is set if the store supports access control lists (ACLs) and internal authorization and checking based on these ACLs. ACLs are standard properties, but a store may do nothing more than store and retrieve the ACLs without interpreting them in any way.
feature_links or feature_link_deref are set if the store supports symbolic links, and if certain types of symbolic links, such as specifically non-absolute path names, can be internally resolved by the store itself.
feature_references is set if the store supports hard links.
feature_locking is set if the store supports user-level locks, read-only, write-only, or read-write, that can be applied on various items of the store, and if the store uses these lock settings to control various types of accesses to the locked items. User-level locks are orthogonal to transaction locks and persist beyond the scope of any specific transaction, session, or connection. This implies that the store itself may not be able to clean up after dangling locks, and client-applications must perform any garbage collection.
feature_lock_hierarchy is set if the store allows a user-lock to control access to the entire sub-tree under the locked path name. A simpler locking model would have locking semantics that apply only to a specific path name, and depend on the locks placed on its parents or children, unless the requested operation implicitly modifies these parents or children.
feature_lock_convert is set if the store supports upgrade and downgrade of locks from one mode to another.
feature_versioning is set if the store supports at least a linear versioning and version management. Different versions of the same path name are identified by monotonic version numbers, with a version-nonqualified path name representing the latest version.
feature_version_path is set if the store supports a hierarchical namespace for different versions of a path name.
feature_soft_deletes is set if the store supports a soft-delete, deleting a path name and making it invisible to normal operations, but retaining the ability to restore the path name at a later time if it has not been overwritten by a new create operation. The store also supports purging soft-deleted path names, making them truly deleted, and navigation modes that show soft-deleted items.
feature_hashing is set if the store automatically computes and maintains some type of a secure hash of the contents of a path name, typically a type_file path.
feature_hash_lookup is set if the store allows content-based addressing, or the ability to locate a content item based not on its path name but on its content hash.
feature_filtering is set if the store allows clients to pass a filter function, a PL/SQL function that conforms to a specific function signature, that returns a logical boolean indicating if a given store item satisfies a selection predicate. Stores that support filtering may be able to more efficiently perform item listing, directory navigation, and deletions by embedding the filtering logic inside their implementation. If filtering is not supported, clients can retrieve more items than necessary and perform the filtering checks themselves, although less efficiently.
A filter predicate is a function with the following signature:
function filterFunction(
path in varchar2,
store_name in varchar2,
opcode in integer,
item_type in integer,
properties in dbms_dbfs_content_properties_t,
content in blob)
return integer;
Any PL/SQL function conforming to this signature can examine the contents and properties of a store item, and decide if the item satisfies the selection criterion for the current operation. A return value of true (non-zero) results in the DBFS Content API processing the item as part of the current operation; a return value of false (zero or null) results in the item being skipped entirely from processing.
feature_searching is set if the store allows clients to pass a text-search filter query to locate type_file path names based on their content. Stores that support searching may use indexes to accelerate such searches; otherwise, clients must build their own indexes, or else search a potentially larger set of items to locate the ones of interest for the current search.
feature_asof is set if the store allows clients to use a flashback timestamp in query operations (non-mutating getPath(), list, search).
feature_provider_props is set if the store allows per-operation properties (that control the behavior of the store with respect to the current operation, as opposed to properties associated with individual items).
Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT Constants - Store Features.
Stores that support locking should implement three types of locks: lock_read_only, lock_write_only, lock_read_write.
User locks (one of the three types) can be associated with a user-supplied lock_data. This is not interpreted by the store, but can be used by client applications for their own purposes (for example, the user data could indicate the time at which the lock was placed, assuming some part of the client application is interested in later using this information to control its actions, for example, garbage collecting stale locks or explicitly break locks).
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).
More complex lock models: multiple read-locks, lock-scoping across path name hierarchies, lock conversions, group-locking, and so on, are possible but currently not defined by the DBFS Content API.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT constants and lock types.
Standard properties are well-defined, mandatory properties associated with all content path names that all stores must support, in the manner described by the DBFS Content API, with some concessions such as a read-only store need not implement a modification_time or creation_time; 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 because this may cause conflicts in the future.
The menu of the following standard properties is expected to be fairly stable over time.
std_access_time (TYPECODE_TIMESTAMP in UTC)
The time of last access of the contents of a path name.
std_acl (TYPECODE_VARCHAR2)
The access control list (in standard ACL syntax) associated with the path name.
std_canonical_path (TYPECODE_VARCHAR2)
The canonical store-specific path name of an item, suitably cleaned up (leading/, trailing / collapsed, trimmed, and so on).
std_change_time (TYPECODE_TIMESTAMP in UTC)
The time of last change to the metadata of a path name.
std_children (TYPECODE_NUMBER)
The number of child directories or folders a directory or folder path has (this property should be available in providers that support feature_folders).
std_content_type (TYPECODE_VARCHAR2)
The client-supplied mime-type(s) (in standard RFC syntax) describing the (typically type_file) path name. The content type is not necessarily interpreted by the store.
std_creation_time (TYPECODE_TIMESTAMP in UTC)
The time at which the item was created (once set, this value never changes for the lifetime of the path name).
std_deleted (TYPECODE_NUMBER as a boolean)
Set to a non-zero number if the path name has been soft-deleted (see above for this feature), but not yet purged.
std_guid (TYPECODE_NUMBER)
A store-specific unique identifier for a path name. Clients must not depend on the GUID being unique across different stores, but a given (store-name, store-specific-pathname) has a stable and unique GUID for its lifetime.
std_length (TYPECODE_NUMBER)
The length of the content (BLOB) of a type_file or type_reference path, or the length of the referent of a type_link symbolic link. Directories do not have a well-defined length and stores are free to set this property to zero, null, or any other value they choose.
std_modification_time (TYPECODE_TIMESTAMP in UTC)
The time of last change to the data associated with a path name. Change to the content of a type_file or type_reference path, the referent of the type_link path, and addition or deletion of immediate children in a type_directory path, all constitute data changes.
std_owner (TYPECODE_VARCHAR2)
A client-supplied (or implicit) owner name for the path name. The owner name may be used along with the current principal for access checks by stores that support ACLs and or locking.
std_parent_guid (TYPECODE_NUMBER)
A store-specific unique identifier for the parent of a path name. Clients must not depend on the GUID being unique across different stores, but a given (store-name, store-specific-pathname) has a stable and unique GUID for its lifetime.
std_parent_guid (pathname == std_guid(parent(pathname)))
std_referent (TYPECODE_VARCHAR2)
The content of the symbolic link of a type_link path; null otherwise. As mentioned before, the std_referent can be an arbitrary string and must not necessarily be interpreted as path name by clients (or such interpretation should be done with great care).
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT constants and standard 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 because this can cause conflicts in the future.
The menu of the following optional properties is expected to be expand over time.
opt_hash_type (TYPECODE_NUMBER)
The type of hash provided in the opt_hash_value property; see dbms_crypto for possible options.
opt_hash_value (TYPECODE_RAW)
The hash value of type opt_hash_type describing the content of the path name.
opt_lock_count (TYPECODE_NUMBER)
The number of (compatible) locks placed on a path name. If different principals are allowed to place compatible (read) locks on a path, the opt_locker must specify all lockers (with repeats so that lock counts can be correctly maintained).
opt_lock_data (TYPECODE_VARCHAR2)
The client-supplied user-data associated with a user lock, uninterpreted by the store.
opt_locker (TYPECODE_VARCHAR2)
The implicit or client-specified principal(s) that applied a user lock on a path name.
opt_lock_status (TYPECODE_NUMBER)
One of the values (lock_read_only, lock_write_only, lock_read_write) describing the type of lock currently applied on a path name.
opt_version (TYPECODE_NUMBER)
A sequence number for linear versioning of a path name.
opt_version_path (TYPECODE_VARCHAR2)
A version path name for hierarchical versioning of a path name.
Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT constants and optional properties.
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.
prop_none
Used when the client is not interested in any properties, and is invoking the content access method for other reasons, such as path name existence, lockability validation, data access, and so on.
prop_std
Used when the client is interested in the standard properties; all standard properties are retrieved if this flag is specified.
prop_opt
Used when the client is interested in the optional properties; all optional properties are retrieved if this flag is specified.
prop_usr
Used when the client is interested in the user-defined properties; all user-defined properties are retrieved if this flag is specified.
prop_all
An alias for the combination of all standard, optional, and user-defined properties.
prop_data
Used when the client is interested only in data access, and does not care about properties.
prop_spc
Used when the client is interested in a mix-and-match of different subsets of various property namespaces; the names of the specific properties to fetch are passed into the DBFS Content API method call as arguments, and only these property values are fetched and returned to the client. This is useful in cases where there are a very large number of properties potentially accessible, but the client is interested in only a small number of them, and knows the names of those properties beforehand.
prop_spc is applicable only to the various getPath() operations. Other operations that specify properties simply ignore prop_spc specifications.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT constants and property access flags.
DBFS Content API operations can raise any one of the following 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, for their part, should do their best to trap and wrap any internal exceptions into one of the following exception types, as appropriate.
Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT constants and optional codes.
The property_t record type describes a single (value, typecode) property value tuple; the property name is implied (see properties_t in the next code snippet).
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 (see next code snippet).
See Oracle Database PL/SQL Packages and Types Reference for details of the PROPERTY_T record type.
A store_t is a record that describes a store registered with, and managed by the DBFS Content API (see the Administrative APIs in the next section).
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 Oracle Database PL/SQL Packages and Types Reference for details of the STORE_T record type.
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).
The administrative methods in DBMS_DBFS_CONTENT are merely wrappers that delegate to the matching methods in DBMS_DBFS_CONTENT_ADMIN. Clients can use the methods in either package to perform administrative operation.
See Oracle Database PL/SQL Packages and Types Reference for the summary of DBMS_DBFS_CONTENT package methods.
Procedure REGISTERSTORE() registers a new store backed by a provider that uses provider_package as the store service provider (conforming to the DBMS_DBFS_CONTENT_SPI package signature).
This method is designed for use by service providers after they have created a new store. Store names must be unique.
See Oracle Database PL/SQL Packages and Types Reference for details of the REGISTERSTORE() method.
Procedure UNREGISTERSTORE() unregisters a previously registered store, invalidating all mount points associated with it. Once unregistered, all access to the store and its mount points are not guaranteed to work, although consistent read may provide a temporary illusion of continued access.
If the ignore_unknown argument is true, attempts to unregister unknown stores does not raise an exception.
See Oracle Database PL/SQL Packages and Types Reference for details of the UNREGISTERSTORE() method.
Procedure MOUNTSTORE() mounts a registered store and binds it to the mount point.
Once mounted, access to path names of the form /store_mount/xyz is redirected to store_name and its content provider.
Store mount points must be unique, and a syntactically valid path name component (that is, a name_t with no embedded /).
If a mount point is not specified (that is, is null), the DBFS Content API attempts to use the store name itself as the mount point name (subject to the uniqueness and syntactic constraints).
A special empty mount point is available for single stores, that is, a scenario where the DBFS Content API manages a single back-end store. In such cases, the client can directly deal with full path names of the form /xyz because there is no ambiguity in how to redirect these accesses.
Single mount points are indicated by the singleton boolean argument, and the store_mount argument is ignored.
The same store can be mounted multiple times, obviously at different mount points.
Mount properties can be used to specify the DBFS Content API execution environment, that is, default values of the principal, owner, ACL, and asof, for a particular mount point. Mount properties can also be used to specify a read-only store.
See Oracle Database PL/SQL Packages and Types Reference for details of the MOUNTSTORE() method.
Procedure UNMOUNTSTORE() unmounts a previously mounted store, either by name or by mount point. Single stores can be unmounted only by store name because they have no mount points. Attempting to unmount a store by name unmounts all mount points associated with the store.
Once unmounted, all access to the store or mount-point is not guaranteed to work although consistent read may provide a temporary illusion of continued access. If the ignore_unknown argument is true, attempts to unregister unknown stores or mounts does not raise an exception.
See Oracle Database PL/SQL Packages and Types Reference for details of the UNMOUNTSTORE mehtod.
The LISTSTORE() function lists all the available stores. The store_mount field of the returned records is set to null because mount points are separate from stores themselves
See Oracle Database PL/SQL Packages and Types Reference for details of the LISTSTORES Function.
Function LISTMOUNTS() lists all available mount points, their backing stores, and the store features. A single mount results in a single returned row, with its store_mount field set to null.
See Oracle Database PL/SQL Packages and Types Reference for details of the LISTMOUNTS() method.
The GETSTOREBYXXX() and GETFEATUREBYXXX() functions look up the path name, store name, or mount point of the store.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT methods.
Clients can query file system space usage statistics using the SPACEUSAGE() method. Providers are expected to support this method for their stores, and to make a best effort determination of space usage, especially if the store consists of multiple tables, indexes, LOBs, and so on
blksize is the natural tablespace block size that holds the store; if multiple tablespaces with different block sizes are used, any valid block size is acceptable.
tbytes is the total size of the store in bytes, and fbytes is the free or unused size of the store in bytes. These values are computed over all segments that comprise the store.
nfile, ndir, nlink, and nref count the number of currently available files, directories, links, and references in the store.
Because database objects can grow dynamically, it is not easy to estimate the division between free space and used space.
A space usage query on the top level root directory returns a combined summary of the space usage of all available distinct stores under it (if the same store is mounted multiple times, it is counted only once).
See Oracle Database PL/SQL Packages and Types Reference for details of the SPACEUSAGE() method.
Normal client access to the DBFS Content API executes with an implicit context that consists of:
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 is 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.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT methods.
To allow for the DBFS Content API itself to evolve, an internal numeric API version increases with each change to the public API.
See Oracle Database PL/SQL Packages and Types Reference for details of the GETVERSION() method.
Clients of the DBFS Content API refer to store items through absolute path names. These path names may be full (a single string of the form /mount_point/pathname), or 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 as it suits them, 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.
The DBFS Content API allows clients 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 to associate with the primary path name. File path names can optionally specify a BLOB value to use to initially populate the underlying file content, 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 exist produces an error; the one exception is path names that are soft-deleted. In these cases, the soft-deleted item is implicitly purged, and the new item creation is attempted.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT() methods.
The DBFS Content API allows clients 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.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT methods.
Existing path items may be accessed for query or for update, and modified by 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 are 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.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT methods.
Path names can be renamed or moved, possibly across directory hierarchies and mount points, but only within the same store.
Non-directory path names previously accessible by oldPath are 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 are 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 with respect to non-existent or existent and non-directory or directory targets is complex, clients may choose to implement complex rename and move operation as a sequence of simpler moves or copies.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT.RENAMEPATH() methods.
A list_item_t is a (path name, component name, type) tuple 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 (name, value, type) tuples.
See Oracle Database PL/SQL Packages and Types Reference for details of data structures.
Clients of the DBFS Content API can list or search the contents of directory path names, optionally recursively in sub-directories, optionally seeing soft-deleted items, optionally using flashback asof a provided timestamp, and optionally filtering items in and out within the store based on list or search predicates.
The DBFS Content API currently returns only list items; the client is expected to explicitly use one of the getPath() methods to access the properties or content associated with an item, as appropriate.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT methods.
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.
It is the responsibility of the store, assuming it supports user-defined lock checking, to ensure that lock and unlock operations are performed in a consistent manner.
Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT methods.
All of the operations in the DBFS Content API are represented as abstract opcodes. Clients can use these opcodes to directly and explicitly invoke the CHECKACCESS() method to verify 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.
Soft-deletion, purge, and restore operations are all represented by op_delete().
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.
See "DBFS Content API Access Checks" and Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT Constants - Operation Codes.
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.
This is a convenience function for the client; a store that supports access control still internally performs these checks to guarantee security.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT methods.
Function NORMALIZEPATH() performs the following steps:
Verifies that the path name is absolute (starts with a /).
Collapses multiple consecutive /s into a single /.
Strips trailing /s.
Breaks store-specific normalized path names into two components: the parent path name and the trailing component name.
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.
See Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT.RENAMEPATH() methods.
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.
Oracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT methods.
DBFS Content API tracing is a generic tracing facility that may be used by any DBFS Content API user (both clients and providers). 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 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 controls how much additional information the trace reports with each trace record: timestamps, short-stack, and so on. Example 7-1 demonstrates how to enable tracing using the DBFS Content APIs.
Example 7-1 DBFS Content Tracing
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 '');
SeeOracle Database PL/SQL Packages and Types Reference for details of the DBMS_DBFS_CONTENT methods.
The following views describe the structure and properties of Content API.
The DBFS_CONTENT views; see Oracle Database Reference
The DBFS_CONTENT_PROPERTIES views; see Oracle Database Reference