43 DBMS_DBFS_CONTENT

Using DBMS_DBFS_CONTENT

• Overview

• Security Model

• Constants

• Exceptions

• Operational Notes

Overview

The DBMS_DBFS_CONTENT package provides an interface comprising a file system-like abstraction backed by one or more Store Providers. The "Content" in the DBFS Content interface refers to a file including metadata, and it can map to a 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 referred to as a "Store Provider."

For applications that already use LOBs as columns in their schema, the DBFS Content interface comes with a default implementation to access the BLOB columns. This enables existing applications to easily add PL/SQL provider implementations and provide access through the DBFS Content interface without rewriting their schema or their business logic. Additionally, applications can read and write content that is stored in other (third party) stores through the standard DBFS Content programming interface.

Examples of providers include:

• Content applications like Content DB

• Packaged applications that want to surface data through file

• Custom applications that want to leverage the file system interface -- for example, an application that stores medical image

The DBS_DBFS_CONTENT package abstracts out the common features of various stores into a simple and minimalist interface used to build portable client applications while insulated from store-specific libraries and implementation.

The content interface aggregates the path namespace of one or more stores into a single unified namespace, using the first component of the path name as a disambiguator, and presents this namespace to client-applications.

This allows clients to access the underlying documents using either a full-absolute path name as a single string:

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

or a store-qualified path name as a string 2-tuple:

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

The interface 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 service 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 interface and serves as a private contract between the implementation of the content interface and various stores that wish to be pluggable into it.

The content interface defines client-visible behavior (normal and exceptional) of various store operations, while allowing different stores to implement as rich a set of features as they choose - the interface 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).

Security Model

The DBMS_DBFS_CONTENT package runs under AUTHID CURRENT_USER.

Constants

The DBMS_DBFS_CONTENT package uses the constants shown in the following tables:

• DBMS_DBFS_CONTENT Constants - Path Names

• DBMS_DBFS_CONTENT Constants - ContentID

• DBMS_DBFS_CONTENT Constants - Properties

• DBMS_DBFS_CONTENT Constants - Path Name Types

• DBMS_DBFS_CONTENT Constants - Store Features

• DBMS_DBFS_CONTENT Constants - Lock Types

• DBMS_DBFS_CONTENT Constants - Standard Properties

• DBMS_DBFS_CONTENT Constants - Optional Properties

• DBMS_DBFS_CONTENT Constants - Property Access Flags

• DBMS_DBFS_CONTENT Constants - Operation Codes

Path Name Constants and Types

The following constants are useful for declaring paths and item names. Paths are limited to 1024 characters and item names are limited to 256 characters.

ContentID Constants

Stores may expose to the user a unique identifier that represents a particular path item in the store. These identifiers are limited to 128 characters.

Properties Constants

Every path name in a store is associated with a set of properties. For simplicity and to provide generic basis, each property is identified by a string "name", has a string "value" (which might be NULL if unset 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 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.

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.

Path Name Types

Path items in a store have a item type associated with them. These types represent the kind of entry the item represents in the store.

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.

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 service providers (and different stores) to describe themselves through a "feature set" (a bitmask indicating which features they support and which ones they do not).

Using the feature set, it is possible, albeit 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.

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;

Lock types

Stores that support locking should implement 3 types of locks: LOCK_READ_ONLY, LOCK_WRITE_ONLY, and LOCK_READ_WRITE.

User-locks (of one of these 3 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, such as garbage collect 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_WREAD_WRITE allows both.

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

More complex lock models: multiple read-locks, lock-scoping across path name hierarchies, lock conversions, group-locking, and other strategies, are possible but currently not defined by the content interface.

Standard properties

Standard properties are well-defined, mandatory properties associated with all content path names that all stores should support (in the manner described by the content interface), with some concessions. For example, 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 since this can cause conflicts in future.

The menu of standard properties is expected to be fairly stable over time.

STD_PARENT_GUID(path name) == STD_GUID(parent(path name))

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 should avoid using this namespace to define their own properties since this can cause conflicts in the future.

The menu of optional properties is expected to be expand over time.

Property Access Flags

Content interface methods to get or set properties can use combinations of property access flags to fetch properties from different name spaces in a single interface call.

Operation Codes

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

Clients can use these opcodes to directly and explicitly by invoking the CHECKACCESS Function to verify if a particular operation can be invoked by a given principal on a particular path name.

Exceptions

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 signally code.

Store service providers, for their part, should do their best to trap or wrap any internal exceptions into one of the following exception types, as appropriate

Operational Notes

• Implementation

• Path Names

• Creation Operations

• Deletion Operations

• Get (Retrieve) and Put (Insert) Operations

• Rename and Move Operations

• Directory Navigation and Search

• Locking Operations

• Access Check Operation

Implementation

Since the interconnection of the DBMS_DBFS_CONTENT interface and the provider SPI is a 1-to-many pluggable architecture, the interface uses dynamic SQL to invoke methods in the provider SPI, this can lead to runtime errors.

There are no explicit INIT or FINI methods to indicate when the DBMS_DBFS_CONTENT interface plugs or unplugs a particular provider SPI. Provider SPIs must be willing to auto-initialize themselves at any SPI entry-point.

All operations performed by a service provider are "stateless" in that they are complete operations unto themselves. If state is necessary to be maintained for some reason, then the state must be maintained in data structures such as auxiliary tables that can be queried as needed.

Path Names

All path names used in the provider SPI are store-qualified in pair form (store_name, pathname) where the path name is rooted within the store namespace.

Stores and their providers that support contentID-based access (see FEATURE_CONTENT_ID in DBMS_DBFS_CONTENT Constants - Store Features) also support a form of addressing that is not based on path names. Content items are identified by an explicit store name, a NULL path name, and possibly a contentID specified as a parameter or by way of the OPT_CONTENT_ID (see DBMS_DBFS_CONTENT Constants - Optional Properties) property.

Not all operations are supported with contentID-based access, and applications should depend only on the simplest create or delete functionality being available.

Creation Operations

The provider SPI must allow the DBFS content API to create directory, file, link, and reference elements subject to store feature support.

All of the creation subprograms require a valid path name, but note the special exemption for contentID-based access. Creation subprograms can optionally specify properties to be associated with the path name as it is created. It is also possible for clients to returns item properties after the creation completes so that automatically generated properties, such as STD_CREATION_TIME (see DBMS_DBFS_CONTENT Constants - Standard Properties) are immediately available to clients. The exact set of properties fetched back is controlled by the various PROP_XXX bitmasks in the prop_flags parameter.

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). On creation, the underlying LOB is returned to the client, provided that PROP_DATA is specified in the prop_flags parameter.

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

Attempts to create paths that already exist is an error; the sole exception is path names that are "soft-deleted" (as discussed in the context of Deletion Operations) 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 (see DBMS_DBFS_CONTENT Constants - Optional Properties), contentID-based creation being automatically implied by PROP_OPT property in the prop_flags parameter).

The newly created element may also have an internally generated path name if FEATURE_LAZY_PATH property is not supported (see DBMS_DBFS_CONTENT Constants - Store Features) and this path is available by way of the STD_CANONICAL_PATH property (see DBMS_DBFS_CONTENT Constants - Standard Properties).

Only file elements are candidates for contentID-based access.

Deletion Operations

The provider SPI must allow the DBFS content API to delete directory, file, link, and reference elements (subject to store feature support).

By default, the deletions are permanent, removing the successfully deleted items on transaction commit, but stores may also support "soft-delete" features. If requested by the client, soft-deleted items are retained by the store, although they are not typically visible in normal listings or searches.

Soft-deleted items can be restored, or explicitly purged.

Directory path names can be recursively deleted, with the path name hierarchy below a directory 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, as well as all soft-deleted path names under a directory, can be restored or purged by means of the various restore and purge subprograms.

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 the DELETEDIRECTORY Procedure, PROPVARCHAR2 Function, and RESTOREALL Procedure, but all of the deletion-related operations accept a filter argument.

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

Get (Retrieve) and Put (Insert) Operations

Existing path items can be accessed (for query or for update) and modified using simple get and put subprograms. All path names allow their metadata (properties) to be read and modified. On completion of the call, the client can request specific properties to be fetched by means of the prop_flags parameter.

File path names allow their data (content) to be read and modified. On completion of the call, the client can use the PROP_DATA bitmasks in the prop_flags parameter to request a new BLOB locator to continue data access.

Files can also be read or 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 can be implicitly and internally de-referenced by stores (subject to feature support) if the deref flag is specified, however, this may have undetermined outcomes since symbolic links are not always resolvable.

The read methods, such as the GETPATH Procedures where forUpdate is specified as 0, also accepts a valid asof timestamp in the ctx parameter that can be used by stores to implement "as of" style flashback queries. Mutating versions of the GETPATH Procedures and the PUTPATH Procedures methods do not support "as of" modes of operation.

The GETPATHNOWAIT Procedures implies that the operation is for an update, and, if implemented (see FEATURE_NOWAIT in DBMS_DBFS_CONTENT Constants - Store Features), this allows providers to return an exception (ORA-00054) rather than wait for row locks.

Rename and Move Operations

Path names can be renamed or moved, possibly across directory hierarchies and mount-points, but within the same store.

Nondirectory path names previously accessible by way of specifying the oldPath parameter are renamed as a single item subsequently accessible by specifying newPath, assuming that newPath does not already exist.

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

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

Stores and their providers that support contentID-based access and lazy path name binding also support the SETPATH Procedures that associates an existing contentID with a new "path".

Directory Navigation and Search

The DBMS_DBFS_CONTENT interface can list or search the contents of directory path names, optionally operating recursively into sub-directories, optionally seeing soft-deleted items, optionally using flashback "as of" a provided timestamp, and optionally filtering items in or out within the store based on list or search predicates.

Locking Operations

Clients of the DBMS_DBFS_CONTENT interface 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 using various optional properties (note the previous discussion regarding opt_lock).

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.

Access Check Operation

This operation ascertains if a given path name (store_name, path, pathtype) can be manipulated by operation (see the various DBMS_DBFS_CONTENT.OP_XXX opcodes in DBMS_DBFS_CONTENT Constants - Optional Properties) by the user acting on the store utilizing the principal parameter. This is a convenience function for the DBMS_DBFS_CONTENT interface; a store that supports access control still internally performs these checks to guarantee security.

Data Structures

The DBMS_DBFS_CONTENT package defines RECORD types and TABLE types.

RECORD Types

• FEATURE_T Record Type

• MOUNT_T Record Type

• PATH_ITEM_T Record Type

• PROP_ITEM_T Record Type

• PROPERTY_T Record Type

• STORE_T Record Type

TABLE Types

• FEATURES_T Table Type

• MOUNTS_T Table Type

• PATH_ITEMS_T Table Type

• PROP_ITEMS_T Table Type

• PROPERTIES_T Table Type

• STORES_T Table Type

Usage Notes

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.

Likewise, 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.

The DBMS_DBFS_CONTENT interface provides convenient utility functions to convert between DBMS_DBFS_CONTENT_PROPERTIES_T and PROPERTIES_T (see propertiesT2H and propertiesH2T).

Clients can query the DBMS_DBFS_CONTENT interface for the list of available stores, determine which store is to handle access to a given path name, and determine the feature set for the store.

FEATURE_T Record Type

This type describes a store mount point and its properties.

Syntax

TYPE feature_t IS RECORD (
   feature_name    VARCHAR2(32),
   feature_mask    INTEGER,
   feature_state   VARCHAR2(3));

Fields

MOUNT_T Record Type

This type describes a store mount point and its properties.

Syntax

TYPE mount_t IS RECORD (
   store_name          VARCHAR2(32),
   store_id            NUMBER,
   provider_name       VARCHAR2(32),
   provider_pkg        VARCHAR2(32),
   provider_id         NUMBER,
   provider_version    VARCHAR2(32),
   store_features      INTEGER,
   store_guid          NUMBER,
   store_mount         NAME_T,
   mount_properties    DBMS_DBFS_CONTENT_PROPERTIES_T);

Fields

PATH_ITEM_T Record Type

A PATH_ITEM_T is a tuple describing a (store, mount) qualified path in a store, with all standard and optional properties associated with it.

Syntax

TYPE path_item_t IS RECORD (
   store                    NAME_T,
   mount                    NAME_T,
   pathname                 PATH_T,
   pathtype                 VARCHAR2(32),
   filedata                 BLOB,
   std_access_time          TIMESTAMP,
   std_acl                  VARCHAR2(1024),
   std_change_time          TIMESTAMP,
   std_children             NUMBER,
   std_content_type         VARCHAR2(1024),
   std_creation_time        TIMESTAMP,
   std_deleted              INTEGER,
   std_guid                 INTEGER,
   std_modification_time    TIMESTAMP,
   std_owner                VARCHAR2(32),
   std_parent_guid          INTEGER,
   std_referent             VARCHAR2(1024),
   opt_hash_type            VARCHAR2(32),
   opt_hash_value           VARCHAR2(128),
   opt_lock_count           INTEGER,
   opt_lock_data            VARCHAR2(128),
   opt_locker               VARCHAR2(128),
   opt_lock_status          INTEGER,
   opt_version              INTEGER,
   opt_version_path         PATH_T,
   opt_content_id           CONTENT_ID_T);

Fields

std_parent_guid(pathname) == std_guid(parent(pathname))

PROP_ITEM_T Record Type

A PROP_ITEM_T is a tuple describing a (store, mount) qualified path in a store, with all user-defined properties associated with it, expanded out into individual (name, value, type) tuples.

Syntax

TYPE prop_item_t IS RECORD (
   store               NAME_T,
   mount                    NAME_T,
   pathname                 PATH_T,
   property_name            PROPNAME_T, 
   property_value           PROPVAL_T,   
   property_type            INTEGER);

Fields

PROPERTY_T Record Type

This type describes a single (value, typecode) property value tuple; the property name is implied (see PROPERTIES_T Table Type).

Syntax

TYPE property_t  IS RECORD (
   propvalue    PROPVAL_T,
   typecode     INTEGER); 

Fields

STORE_T Record Type

This type describes a store registered with and managed by the DBMS_DBFS_CONTENT interface.

Syntax

TYPE store_t IS RECORD (
   store_name          VARCHAR2(32),
   store_id            NUMBER,
   provider_name       VARCHAR2(32),
   provider_pkg        VARCHAR2(32),
   provider_id         NUMBER,
   provider_version    VARCHAR2(32),
   store_features      INTEGER,
   store_guid          NUMBER);

Fields

FEATURES_T Table Type

A table type of FEATURE_T Record Type.

Syntax

TYPE features_t IS TABLE OF feature_t;

MOUNTS_T Table Type

A table type of MOUNT_T Record Type.

Syntax

TYPE mounts_t IS TABLE OF mount_t;

PATH_ITEMS_T Table Type

A table type of PATH_ITEM_T Record Type

Syntax

TYPE path_items_t IS TABLE OF path_item_t;

PROP_ITEMS_T Table Type

A table type of PATH_ITEM_T Record Type.

Syntax

TYPE prop_items_t IS TABLE OF prop_item_t;

PROPERTIES_T Table Type

This 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.

Syntax

TYPE properties_t IS TABLE OF property_t INDEX BY propname_t;

STORES_T Table Type

This type describes a store registered with and managed by the DBMS_DBFS_CONTENT interface.

Syntax

TYPE stores_t IS TABLE OF store_t;

Summary of DBMS_DBFS_CONTENT Subprograms

CHECKACCESS Function

This function reports if the user (principal) can perform the specified operation on the given path. This enables verifying the validity of an operation without attempting to perform the operation. If CHECKACCESS returns 0, then the subprogram invoked to implement that operation should fail with an error.

Syntax

DBMS_DBFS_CONTENT.CHECKACCESS (
   path           IN     VARCHAR2,
   pathtype       IN     INTEGER,
   operation      IN     VARCHAR2,
   principal      IN     VARCHAR2,
   store_name     IN     VARCHAR2  DEFAULT NULL)
  RETURN  BOOLEAN;

Parameters

Usage Notes

Whether or not the user invokes this function, a store that supports access control internally performs these checks to guarantee security.

CHECKSPI Functions and Procedures

Given the name of a putative DBMS_DBFS_CONTENT_SPI conforming package, this function or procedure checks whether the package implements all of the provider subprograms with the proper signatures, and reports on the conformance.

Syntax

DBMS_DBFS_CONTENT.CHECKSPI (
   package_name        IN              VARCHAR2)
  RETURN  CLOB;
 
DBMS_DBFS_CONTENT.CHECKSPI (
   schema_name         IN              VARCHAR2,
   package_name        IN              VARCHAR2)
  return  clob;
 
DBMS_DBFS_CONTENT.CHECKSPI (
   package_name        IN              VARCHAR2,
   chk                 IN OUT NOCOPY   CLOB);
 
DBMS_DBFS_CONTENT.CHECKSPI (
   schema_name         in              VARCHAR2,
   package_name        in              VARCHAR2,
   chk                 in out nocopy   CLOB);

Parameters

Usage Notes

• The functional form returns a cached temporary LOB of session duration with the results of the analysis. The caller is expected to manage the lifetime of this LOB, as needed.

• The procedural form generates the results of the analysis into the chk LOB parameter; if the value passed in is NULL, the results are written to the foreground trace file provided that DBMS_DBFS_CONTENT interface tracing is enabled. If neither tracing is enabled nor a valid LOB passed in, the checker does not provide any useful indication of the analysis (other than raise exceptions if it encounters a serious error).

• If schema_name is NULL, standard name resolution rules (current schema, private synonym, public synonym) are used to try and locate a suitable package to analyze.

CREATEDIRECTORY Procedures

This procedure creates a directory.

Syntax

DBMS_DBFS_CONTENT.CREATEDIRECTORY (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
   prop_flags  IN              INTEGER     DEFAULT PROP_STD,
   recurse     IN              BOOLEAN     DEFAULT FALSE,
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.CREATEDIRECTORY (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   PROPERTIES_T,
   prop_flags  IN              INTEGER     DEFAULT PROP_STD,
   recurse     IN              BOOLEAN     DEFAULT FALSE,
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

Parameters

CREATEFILE Procedures

This procedure creates a file.

Syntax

DBMS_DBFS_CONTENT.CREATEFILE (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
   content     IN OUT NOCOPY   BLOB,
   prop_flags  IN              INTEGER     DEFAULT (PROP_STD + PROP_DATA),
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.CREATEFILE (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   PROPERTIES_T,
   content     IN OUT NOCOPY   BLOB,
   prop_flags  IN              INTEGER     DEFAULT (PROP_STD + PROP_DATA),
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

Parameters

CREATELINK Procedures

This procedure creates a new reference to the source file system element (such as a file, or directory). The resulting reference points to the source element but does not directly share metadata with the source element. This is analogous to a UNIX file system symbolic link.

Syntax

DBMS_DBFS_CONTENT.CREATELINK (
   srcPath     IN              VARCHAR2,
   dstPath     IN              VARCHAR2,
   properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
   prop_flags  IN              INTEGER     DEFAULT PROP_STD,
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.CREATELINK (
   srcPath     IN              VARCHAR2,
   dstPath     IN              VARCHAR2,
   properties  IN OUT NOCOPY   PROPERTIES_T,
   prop_flags  IN              INTEGER     DEFAULT PROP_STD,
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

Parameters

CREATEREFERENCE Procedures

This procedure creates a physical link to an already existing file system element (such as file or directory). The resulting entry shares the same metadata structures as the value of the srcPath parameter, and so is similar to incrementing a reference count on the file system element. This is analogous to a UNIX file system hard link.

Syntax

DBMS_DBFS_CONTENT.CREATEREFERENCE (
   srcPath     IN              VARCHAR2,
   dstPath     IN              VARCHAR2,
   properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
   prop_flags  IN              INTEGER     DEFAULT PROP_STD,
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.CREATEREFERENCE (
   srcPath     IN              VARCHAR2,
   dstPath     IN              VARCHAR2,
   properties  IN OUT NOCOPY   PROPERTIES_T,
   prop_flags  IN              INTEGER     DEFAULT PROP_STD,
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

Parameters

DECODEFEATURES Function

Given a feature bit set integer value, this function returns a FEATURES_T table of the feature bits as FEATURE_T records.

Syntax

DBMS_DBFS_CONTENT.DECODEFEATURES (
   featureSet          IN      INTEGER)
  RETURN FEATURES_T DETERMINISTIC PIPELINED;

Parameters

Return Values

FEATURES_T Table Type

DELETECONTENT Procedure

This procedure deletes the file specified by the given contentID.

Syntax

DBMS_DBFS_CONTENT.DELETECONTENT (
   store_name     IN     VARCHAR2    DEFAULT NULL,
   contentID      IN     RAW,
   filter         IN     VARCHAR2    DEFAULT NULL,
   soft_delete    IN     BOOLEAN     DEFAULT NULL,
   principal      IN     VARCHAR2    DEFAULT NULL);

Parameters

DELETEDIRECTORY Procedure

This procedure deletes a directory. If recurse is nonzero, it recursively deletes all elements of the directory. A filter, if supplied, determines which elements of the directory are deleted.

Syntax

DBMS_DBFS_CONTENT.DELETEDIRECTORY (
   path           IN     VARCHAR2,
   filter         IN     VARCHAR2    DEFAULT NULL,
   soft_delete    IN     BOOLEAN     DEFAULT NULL,
   recurse        IN     BOOLEAN     DEFAULT FALSE,
   store_name     IN     VARCHAR2    DEFAULT NULL,
   principal      IN     VARCHAR2    DEFAULT NULL);

Parameters

DELETEFILE Procedure

This procedure deletes the specified file.

Syntax

DBMS_DBFS_CONTENT.DELETEFILE (
   path           IN     VARCHAR2,
   filter         IN     VARCHAR2    DEFAULT NULL,
   soft_delete    IN     BOOLEAN     DEFAULT NULL,
   store_name     IN     VARCHAR2    DEFAULT NULL,
   principal      IN     VARCHAR2    DEFAULT NULL);

Parameters

FEATURENAME Function

Given a feature bit, this function returns a VARCHAR2 of that feature's name.

Syntax

DBMS_DBFS_CONTENT.FEATURENAME (
   featureBit          IN      INTEGER)
  RETURN VARCHAR2 DETERMINISTIC;

Parameters

Return Values

Name of the feature

FLUSHSTATS Function

This procedure flushes DBMS_DBFS_CONTENT statistics to disk.

Syntax

DBMS_DBFS_CONTENT.FLUSHSTATS;

GETDEFAULTACL Procedure

This procedure returns the ACL parameter of the default context. This information can be inserted explicitly by way of argument into other method calls, allowing for a more fine-grained control.

Syntax

DBMS_DBFS_CONTENT.GETDEFAULTACL (
   acl    OUT NOCOPY     VARCHAR2);

Parameters

GETDEFAULTASOF Procedure

This procedure returns the "as of" parameter of the default context. This information can be inserted explicitly by way of argument into other method calls, allowing for a more fine-grained control.

Syntax

DBMS_DBFS_CONTENT.GETDEFAULTASOF (
  asof    OUT NOCOPY     TIMESTAMP);

Parameters

GETTDEFAULTCONTEXT Procedure

This procedure returns the default context. The information contained in the context can be inserted explicitly by way of arguments to the various method calls, allowing for fine-grained control over individual operations.

Syntax

DBMS_DBFS_CONTENT.GETTDEFAULTCONTEXT (
   principal    OUT NOCOPY     VARCHAR2,
   owner        OUT NOCOPY     VARCHAR2,
   acl          OUT NOCOPY     VARCHAR2,
   asof         OUT NOCOPY     TIMESTAMP);

Parameters

GETDEFAULTOWNER Procedure

This procedure returns the "owner" parameter of the default context. This information can be inserted explicitly by way of argument into other method calls, allowing for a more fine-grained control.

Syntax

DBMS_DBFS_CONTENT.GETDEFAULTOWNER (
   principal    IN     VARCHAR2);

Parameters

GETDEFAULTPRINCIPAL Procedure

This procedure returns the "principal" parameter of the default context. This information contained can be inserted explicitly by way of argument into other method calls, allowing for a more fine-grained control.

Syntax

DBMS_DBFS_CONTENT.GETDEFAULTPRINCIPAL (
   principal    OUT NOCOPY     VARCHAR2);

Parameters

GETFEATURESBYMOUNT Function

This function returns features of a store by mount point.

Syntax

DBMS_DBFS_CONTENT.GETFEATURESBYMOUNT (
   store_mount       IN      VARCHAR2)
  RETURN INTEGER;

Parameters

Return Values

A bit mask of supported features (see FEATURES_T Table Type)

GETFEATURESBYNAME Function

This function returns features of a store by store name.

Syntax

DBMS_DBFS_CONTENT.GETFEATURESBYNAME (
   store_name       IN      VARCHAR2)
  RETURN INTEGER;

Parameters

Return Values

A bit mask of supported features (see FEATURES_T Table Type)

GETFEATURESBYPATH Function

This function returns features of a store by path.

Syntax

DBMS_DBFS_CONTENT.GETFEATURESBYPATH (
   path       IN      PATH_T)
  RETURN INTEGER;

Parameters

Return Values

A bit mask of supported features (see FEATURES_T Table Type)

GETPATH Procedures

This procedure returns existing path items (such as files and directories). This includes both data and metadata (properties).

The client can request (using prop_flags) that specific properties be returned. File path names can be read either by specifying a BLOB locator using the prop_data bitmask in prop_flags (see DBMS_DBFS_CONTENT Constants - Property Access Flags) or by passing one or more RAW buffers.

When forUpdate is 0, this procedure also accepts a valid asof timestamp parameter as part of ctx that can be used by stores to implement "as of" style flashback queries. Mutating versions of the GETPATH Procedures do not support these modes of operation.

Syntax

DBMS_DBFS_CONTENT.GETPATH (
        path        IN              VARCHAR2,
        properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
        content     OUT    NOCOPY   BLOB,
        item_type   OUT             INTEGER,
        prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
        asof        IN              TIMESTAMP   DEFAULT NULL,
        forUpdate   IN              BOOLEAN     DEFAULT FALSE,
        deref       IN              BOOLEAN     DEFAULT FALSE,
        store_name  IN              VARCHAR2    DEFAULT NULL,
        principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.GETPATH (
        path        IN              VARCHAR2,
        properties  IN OUT NOCOPY   PROPERTIES_T,
        content     OUT    NOCOPY   BLOB,
        item_type   OUT             INTEGER,
        prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
        asof        IN              TIMESTAMP   DEFAULT NULL,
        forUpdate   IN              BOOLEAN     DEFAULT FALSE,
        deref       IN              BOOLEAN     DEFAULT FALSE,
        store_name  IN              VARCHAR2    DEFAULT NULL,
        principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.GETPATH (
        path        IN              VARCHAR2,
        properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
        amount      IN OUT          NUMBER,
        offset      IN              NUMBER,
        buffers     OUT    NOCOPY   RAW,
        prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
        asof        IN              TIMESTAMP   DEFAULT NULL,
        store_name  IN              VARCHAR2    DEFAULT NULL,
        principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.GETPATH (
        path        IN              VARCHAR2,
        properties  IN OUT NOCOPY   PROPERTIES_T,
        amount      IN OUT          NUMBER,
        offset      IN              NUMBER,
        buffers     OUT    NOCOPY   RAW,
        prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
        asof        IN              TIMESTAMP   DEFAULT NULL,
        store_name  IN              VARCHAR2    DEFAULT NULL,
        principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.GETPATH (
        path        IN              VARCHAR2,
        properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
        amount      IN OUT          NUMBER,
        offset      IN              NUMBER,
        buffers     OUT    NOCOPY   DBMS_DBFS_CONTENT_RAW_T,
        prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
        asof        IN              TIMESTAMP   DEFAULT NULL,
        store_name  IN              VARCHAR2    DEFAULT NULL,
        principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.GETPATH (
        path        IN              VARCHAR2,
        properties  IN OUT NOCOPY   PROPERTIES_T,
        amount      IN OUT          NUMBER,
        offset      IN              NUMBER,
        buffers     OUT    NOCOPY   DBMS_DBFS_CONTENT_RAW_T,
        prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
        asof        IN              TIMESTAMP   DEFAULT NULL,
        store_name  IN              VARCHAR2    DEFAULT NULL,
        principal   IN              VARCHAR2    DEFAULT NULL);

Parameters

GETPATHBYMOUNTID Function

If the underlying GUID is found in the underlying store, this function returns the full absolute path name.

Syntax

DBMS_DBFS_CONTENT.GETPATHBYMOUNTID (
   store_mount         IN      VARCHAR2,
   guid                IN      INTEGER)
  RETURN VARCHAR2;

Parameters

Usage Notes

If the GUID is unknown, a NULL value is returned. Clients are expected to handle this as appropriate.

Return Values

Path of the path item represented by GUID in store_mount

GETPATHBYSTOREID Function

If the underlying GUID is found in the underlying store, this function returns the store-qualified path name.

Syntax

DBMS_DBFS_CONTENT.GETPATHBYSTOREID (
   store_name          IN      VARCHAR2,
   guid                IN      INTEGER)
  RETURN VARCHAR2;

Parameters

Usage Notes

If the GUID is unknown, a NULL value is returned. Clients are expected to handle this as appropriate.

Return Values

Store-qualified path name represented by the GUID

GETPATHNOWAIT Procedures

This procedure implies that the operation is for an update, and, if implemented (see FEATURE_NOWAIT in DBMS_DBFS_CONTENT Constants - Store Features), allows providers to return an exception (ORA-00054) rather than wait for row locks.

Syntax

DBMS_DBFS_CONTENT.GETPATHNOWAIT (
        path        IN              VARCHAR2,
        properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
        content     OUT    NOCOPY   BLOB,
        item_type   OUT             INTEGER,
        prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
        deref       IN              BOOLEAN     DEFAULT FALSE,
        store_name  IN              VARCHAR2    DEFAULT NULL,
        principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.GETPATHNOWAIT (
        path        IN              VARCHAR2,
        properties  IN OUT NOCOPY   PROPERTIES_T,
        content     OUT    NOCOPY   BLOB,
        item_type   OUT             INTEGER,
        prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
        deref       IN              BOOLEAN     DEFAULT FALSE,
        store_name  IN              VARCHAR2    DEFAULT NULL,
        principal   IN              VARCHAR2    DEFAULT NULL);

Parameters

GETSTOREBYMOUNT Function

This function returns a store by way of its name.

Syntax

DBMS_DBFS_CONTENT.GETSTOREBYMOUNT (
   store_mount       IN      VARCHAR2)
  RETURN STORE_T;

Parameters

Return Values

STORE_T Record Type

GETSTOREBYNAME Function

This function returns a store by way of its name.

Syntax

DBMS_DBFS_CONTENT.GETSTOREBYNAME (
   store_name       IN      VARCHAR2)
  RETURN STORE_T;

Parameters

Return Values

STORE_T Record Type

GETSTOREBYPATH Function

This function returns a store by way of its path.

Syntax

DBMS_DBFS_CONTENT.GETSTOREBYPATH (
   path       IN      PATH_T)
  RETURN STORE_T;

Parameters

Return Values

STORE_T Record Type

GETSTATS Procedure

This procedure returns information about DBMS_DBFS_CONTENT statistics collection.

Syntax

DBMS_DBFS_CONTENT.GETSTATS (
   enabled         OUT    BOOLEAN,
   flush_time      OUT    INTEGER,
   flush_count     OUT    INTEGER);

Parameters

GETTRACE Function

This function returns whether DBMS_DBFS_CONTENT tracing is turned on or not.

Syntax

DBMS_DBFS_CONTENT.GETTRACE
  RETURN INTEGER.

Return Values

Returns 0 if tracing is off, non-zero if tracing is on.

GETVERSION Function

This function marks each version of the DBMS_DBFS_CONTENT interface.

Syntax

DBMS_DBFS_CONTENT.GETVERSION (
  RETURN VARCHAR2;

Return Values

A string enumerating the version of the DBMS_DBFS_CONTENT interface in standard naming convention: string: a.b.c corresponding to major, minor, and patch components.

LIST Function

This function lists the path items in the specified path meeting the specified filter and other criteria.

Syntax

DBMS_DBFS_CONTENT.LIST (
   path          IN     VARCHAR2,
   filter        IN     VARCHAR2    DEFAULT NULL,
   recurse       IN     INTEGER     DEFAULT 0,
   asof          IN     TIMESTAMP   DEFAULT NULL,
   store_name    IN     VARCHAR2    DEFAULT NULL,
   principal     IN     VARCHAR2    DEFAULT NULL)
  RETURN  DBMS_DBFS_CONTENT_LIST_ITEMS_T PIPELINED;

Parameters

Return Values

DBMS_DBFS_CONTENT_LIST_ITEMS_T Table Type

LISTALLPROPERTIES Function

This function returns a table of all properties for all path items in all mounts

Syntax

DBMS_DBFS_CONTENT.LISTALLPROPERTIES 
  RETURN  PROP_ITEMS_T PIPELINED;

Return Values

PROP_ITEMS_T Table Type

LISTALLCONTENT Function

This function lists all path items in all mounts.

Syntax

DBMS_DBFS_CONTENT.LISTALLCONTENT 
  RETURN  PATH_ITEMS_T PIPELINED;

Return Values

PATH_ITEMS_T Table Type

LISTMOUNTS Function

This function lists all available mount points, their backing stores, and the store features.

Syntax

DBMS_DBFS_CONTENT.LISTMOUNTS 
  RETURN MOUNTS_T PIPELINED;

Return Values

MOUNTS_T Table Type

Usage Notes

A single mount results in a single returned row, with its store_mount field of the returned records set to NULL.

LISTSTORES Function

This function lists all available stores and their features.

Syntax

DBMS_DBFS_CONTENT.LISTSTORES 
  RETURN STORES_T PIPELINED;

Return Values

STORES_T Table Type

Usage Notes

The store_mount field of the returned records is set to NULL (since mount-points are separate from stores themselves).

LOCKPATH Procedure

This procedure applies user-level locks to the given valid path name (subject to store feature support), and optionally associates user-data with the lock.

Syntax

DBMS_DBFS_CONTENT.LOCKPATH (
   path           IN     VARCHAR2,
   lock_type      IN     INTEGER     DEFAULT LOCK_READ_ONLY,
   lock_data      IN     VARCHAR2    DEFAULT NULL,
   store_name     IN     VARCHAR2    DEFAULT NULL,
   principal      IN     VARCHAR2    DEFAULT NULL);

Parameters

MOUNTSTORE Procedure

This procedure mounts a previously registered store and binds it to the mount point.

Syntax

DBMS_DBFS_CONTENT.MOUNTSTORE (
   store_mount    in      VARCHAR2   DEFAULT NULL,
   singleton      in      BOOLEAN    DEFAULT FALSE,
   principal      in      VARCHAR2   DEFAULT NULL,
   owner          in      VARCHAR2   DEFAULT NULL,
   acl            in      VARCHAR2   DEFAULT NULL,
   asof           in      TIMESTAMP  DEFAULT NULL,
   read_only      in      BOOLEAN    DEFAULT FALSE);

Parameters

Usage Notes

• Once mounted, accesses to path names of the form /store_mount/xyz... are redirected to store_name and its content provider.

• Store mount points must be unique, and a syntactically valid path name component (specifically, a NAME_T with no embedded /).

• If a mount point is not specified (NULL), the invoked subprogram 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, specifically a scenario where the content interface manages a single backend store - in such cases, the client can directly deal with full path names of the form /xyz... since there is no ambiguity in how to redirect these accesses.

• Singleton 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 execution environment, specifically, the 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 mount. If a flashback mount is specified (through asof), it implies a read-only mount.

NORMALIZEPATH Functions

This function converts a store-specific or full-absolute path name into normalized form:

• verifies that the path name is absolute, and so starts with "/"

• collapses multiple consecutive "/" into a single "/"

• strips trailing "/"

• breaks up a store-specific normalized path name into 2 components - parent pathname, trailing component name

• breaks up a full-absolute normalized path name into 3 components - store name, parent pathname, trailing component name

Syntax

DBMS_DBFS_CONTENT.NORMALIZEPATH (
   path        IN              VARCHAR2,
   parent      OUT NOCOPY      VARCHAR2,
   tpath       OUT NOCOPY      VARCHAR2)
  RETURN VARCHAR2;

DBMS_DBFS_CONTENT.NORMALIZEPATH (
   path        IN              VARCHAR2,
   store_name  OUT NOCOPY      VARCHAR2,
   parent      OUT NOCOPY      VARCHAR2,
   tpath       OUT NOCOPY      VARCHAR2)
  RETURN VARCHAR2;

Parameters

Return Values

The completely normalized store-specific or full-absolute path name

PROPANY Functions

This function provides constructors that take one of a variety of types and return a PROPERTY_T.

Syntax

DBMS_DBFS_CONTENT.PROPANY (
   val      IN      NUMBER)
RETURN PROPERTY_T;

DBMS_DBFS_CONTENT.PROPANY (
   val      IN      VARCHAR2)
RETURN PROPERTY_T;

DBMS_DBFS_CONTENT.PROPANY (
   val      IN      TIMESTAMP)
RETURN PROPERTY_T;

DBMS_DBFS_CONTENT.PROPANY (
   val      IN      RAW)
RETURN PROPERTY_T;

Parameters

Return Values

PROPERTY_T Record Type

PROPERTIESH2T Function

This function converts a PROPERTY_T hash to a DBMS_DBFS_CONTENT_PROPERTIES_T table.

Syntax

DBMS_DBFS_CONTENT.PROPERTIEST2H (
   pprops      IN      PROPERTIES_T)
RETURN DBMS_DBFS_CONTENT_PROPERTIES_T;

Parameters

Return Values

DBMS_DBFS_CONTENT_PROPERTIES_T Table Type

PROPERTIEST2H Function

This function converts a DBMS_DBFS_CONTENT_PROPERTIES_T table to a PROPERTY_T hash.

Syntax

DBMS_DBFS_CONTENT.PROPERTIEST2H (
   sprops      IN      DBMS_DBFS_CONTENT_PROPERTIES_T)
RETURN properties_t;

Parameters

Return Values

PROPERTIES_T Table Type

PROPNUMBER Function

This function is a constructor that takes a number and returns a PROPERTY_T.

Syntax

DBMS_DBFS_CONTENT.PROPNUMBER (
   val      IN      NUMBER)
RETURN PROPERTY_T;

Parameters

Return Values

PROPERTY_T Record Type

PROPRAW Function

This function is a constructor that takes a RAW and returns a PROPERTY_T.

Syntax

DBMS_DBFS_CONTENT.PROPRAW (
   val      IN      RAW)
RETURN PROPERTY_T;

Parameters

Return Values

PROPERTY_T Record Type

PROPTIMESTAMP Function

This function is a constructor that takes a TIMESTAMP and returns a PROPERTY_T.

Syntax

DBMS_DBFS_CONTENT.PROPTIMESTAMP (
   val      IN      TIMESTAMP)
RETURN PROPERTY_T;

Parameters

Return Values

PROPERTY_T Record Type

PROPVARCHAR2 Function

This function is a constructor that takes a VARCHAR2 and returns a PROPERTY_T.

Syntax

DBMS_DBFS_CONTENT.PROPVARCHAR2 (
   val      IN      VARCHAR2)
RETURN PROPERTY_T;

Parameters

Return Values

PROPERTY_T Record Type

PURGEALL Procedure

This procedure purges all soft-deleted entries matching the path and optional filter criteria.

Syntax

DBMS_DBFS_CONTENT.PURGEALL (
   path           IN      VARCHAR2,
   filter         IN      VARCHAR2    DEFAULT NULL,
   store_name     IN      VARCHAR2    DEFAULT NULL,
   principal      IN      VARCHAR2    DEFAULT NULL);

Parameters

PURGEPATH Procedure

This procedure purges any soft-deleted versions of the given path item.

Syntax

DBMS_DBFS_CONTENT.PURGEPATH (
   path           IN      VARCHAR2,
   filter         IN      VARCHAR2    DEFAULT NULL,
   store_name     IN      VARCHAR2    DEFAULT NULL,
   principal      IN      VARCHAR2    DEFAULT NULL);

Parameters

PUTPATH Procedures

This procedure creates a new path item.

Syntax

DBMS_DBFS_CONTENT.PUTPATH (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
   content     IN OUT NOCOPY   BLOB,
   item_type   OUT             INTEGER,
   prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.PUTPATH (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   PROPERTIES_T,
   content     IN OUT NOCOPY   BLOB,
   item_type   OUT             INTEGER,
   prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT +
                                                         PROP_DATA),
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.PUTPATH (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
   amount      IN              NUMBER,
   offset      IN              NUMBER,
   buffer      IN              RAW,
   prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT),
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.PUTPATH (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   PROPERTIES_T,
   amount      IN              NUMBER,
   offset      IN              NUMBER,
   buffer      IN              RAW,
   prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT),
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.PUTPATH (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
   written     OUT             NUMBER,
   offset      IN              NUMBER,
   buffers     IN             DBMS_DBFS_CONTENT_RAW_T,
   prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT),
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.PUTPATH (
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   PROPERTIES_T,
   written     OUT             NUMBER,
   offset      IN              NUMBER,
   buffers     IN              DBMS_DBFS_CONTENT_RAW_T,
   prop_flags  IN              INTEGER     DEFAULT (PROP_STD +
                                                         PROP_OPT),
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

Parameters

REGISTERSTORE Procedure

This procedure registers a new store backed by a provider that uses a store service provider (conforming to the DBMS_DBFS_CONTENT_SPI package signature). This method is to be used primarily by service providers after they have created a new store.

Syntax

DBMS_DBFS_CONTENT.REGISTERSTORE (
   store_name          IN      VARCHAR2,
   provider_name       IN      VARCHAR2,
   provider_package    IN      VARCHAR2);

Parameters

RENAMEPATH Procedures

This procedure renames or moves a path. This operation can be performed across directory hierarchies and mount-points as long as it is within the same store.

Syntax

DBMS_DBFS_CONTENT.RENAMEPATH (
   oldPath     IN              VARCHAR2,
   newPath     IN              VARCHAR2,
   properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.RENAMEPATH (
   oldPath     IN              VARCHAR2,
   newPath     IN              VARCHAR2,
   properties  IN OUT NOCOPY   PROPERTIES_T,
   store_name  IN              VARCHAR2    DEFAULT NULL,
   principal   IN              VARCHAR2    DEFAULT NULL);

Parameters

RESTOREALL Procedure

This procedure restores all soft-deleted path items meeting the path and optional filter criteria.

Syntax

DBMS_DBFS_CONTENT.RESTOREALL (
   path           IN      VARCHAR2,
   filter         IN      VARCHAR2    DEFAULT NULL,
   store_name     IN      VARCHAR2    DEFAULT NULL,
   principal      IN      VARCHAR2    DEFAULT NULL);

Parameters

RESTOREPATH Procedure

This procedure restores all soft-deleted path items that match the given path and optional filter criteria.

Syntax

DBMS_DBFS_CONTENT.RESTOREPATH (
   path           IN      VARCHAR2,
   filter         IN      VARCHAR2    DEFAULT NULL,
   store_name     IN      VARCHAR2    DEFAULT NULL,
   principal      IN      VARCHAR2    DEFAULT NULL);

Parameters

SEARCH Function

This function...

Syntax

DBMS_DBFS_CONTENT.SEARCH (
   path           IN      VARCHAR2,
   filter         IN      VARCHAR2    DEFAULT NULL,
   recurse        IN      INTEGER     DEFAULT 0,
   asof           IN      TIMESTAMP   DEFAULT NULL,
   store_name     IN      VARCHAR2    DEFAULT NULL,
   principal      IN      VARCHAR2    DEFAULT NULL)
 RETURN  DBMS_DBFS_CONTENT_LIST_ITEMS_T PIPELINED;

Parameters

Return Values

DBMS_DBFS_CONTENT_LIST_ITEMS_T [AWAITING INFORMATION]

SETDEFAULTACL Procedure

This procedure sets the ACL parameter of the default context. This information can be inserted explicitly by way of argument into other method calls, allowing for a more fine-grained control.

Syntax

DBMS_DBFS_CONTENT.SETDEFAULTACL (
   acl    IN     VARCHAR2);

Parameters

Usage Notes

• NULL by default, this parameter be can be cleared by setting it to NULL.

• The parameters, once set, remain as a default for the duration of the session, and is inherited by all operations for which the default is not explicitly overridden.

SETDEFAULTASOF Procedure

This procedure sets the "as of" parameter of the default context. This information can be inserted explicitly by way of argument into other method calls, allowing for a more fine-grained control.

Syntax

DBMS_DBFS_CONTENT.SETDEFAULTASOF (
  asof    IN     TIMESTAMP);

Parameters

Usage Notes

• NULL by default, this parameter be can be cleared by setting it to NULL.

• The parameters, once set, remain as a default for the duration of the session, and is inherited by all operations for which the default is not explicitly overridden.

SETDEFAULTCONTEXT Procedure

This procedure sets the default context. The information contained in the context can be inserted explicitly by way of arguments to the various method calls, allowing for fine-grained control over individual operations.

Syntax

DBMS_DBFS_CONTENT.SETDEFAULTCONTEXT (
   principal    IN     VARCHAR2,
   owner        IN     VARCHAR2,
   acl          IN     VARCHAR2,
   asof         IN     TIMESTAMP);

Parameters

Usage Notes

• All of the context parameters are NULL by default, and be can be cleared by setting them to NULL.

• The context parameters, once set, remain as defaults for the duration of the session, and are inherited by all operations for which the defaults are not explicitly overridden.

SETDEFAULTOWNER Procedure

This procedure sets the "owner" parameter of the default context. This information can be inserted explicitly by way of argument into other method calls, allowing for a more fine-grained control.

Syntax

DBMS_DBFS_CONTENT.SETDEFAULTOWNER (
   principal    IN     VARCHAR2);

Parameters

Usage Notes

• NULL by default, this parameter be can be cleared by setting it to NULL.

• The parameters, once set, remain as a default for the duration of the session, and is inherited by all operations for which the default is not explicitly overridden.

SETDEFAULTPRINCIPAL Procedure

This procedure sets the "principal" parameter of the default context. This information contained can be inserted explicitly by way of argument into other method calls, allowing for a more fine-grained control.

Syntax

DBMS_DBFS_CONTENT.SETDEFAULTPRINCIPAL (
   principal    IN     VARCHAR2);

Parameters

Usage Notes

• NULL by default, this parameter be can be cleared by setting it to NULL.

• The parameters, once set, remain as a default for the duration of the session, and is inherited by all operations for which the default is not explicitly overridden.

SETPATH Procedures

This procedure assigns a path name to a path item represented by contentID.

Stores and their providers that support contentID-based access and lazy path name binding also support the SETPATH Procedure that associates an existing contentID with a new path.

Syntax

DBMS_DBFS_CONTENT.SETPATH (
   store_name  IN              VARCHAR2,
   contentID   IN              RAW,
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   DBMS_DBFS_CONTENT_PROPERTIES_T,
   principal   IN              VARCHAR2    DEFAULT NULL);

DBMS_DBFS_CONTENT.SETPATH (
   store_name  IN              VARCHAR2,
   contentID   IN              RAW,
   path        IN              VARCHAR2,
   properties  IN OUT NOCOPY   PROPERTIES_T,
   principal   IN              VARCHAR2    DEFAULT NULL);

Parameters

SETSTATS Procedure

This procedure enables and disables statistics collection. The client can optionally control the flush settings by specifying non-NULL values for the time, count or both parameters.

Syntax

DBMS_DBFS_CONTENT.SETSTATS (
   enable          IN    BOOLEAN,
   flush_time      IN    INTEGER,
   flush_count     IN    INTEGER);

Parameters

Usage Notes

The SETSTATS Procedure buffers statistics in-memory for a maximum of flush_time centiseconds or a maximum of flush_count operations (whichever limit is reached first), or both, at which time the buffers are implicitly flushed to disk.

SETTRACE Procedure

This procedure sets the DBMS_DBFS_CONTENT tracing severity to the given level, 0 being "off".

Syntax

DBMS_DBFS_CONTENT.SETTRACE
     trclvl      IN         INTEGER);

Parameters

SPACEUSAGE Procedure

This procedure queries file system space usage statistics. Providers are expected to support this subprogram 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).

Syntax

DBMS_DBFS_CONTENT.SPACEUSAGE (
   path          IN        VARCHAR2,
   blksize       OUT       INTEGER,
   tbytes        OUT       INTEGER,
   fbytes        OUT       INTEGER,
   nfile         OUT       INTEGER,
   ndir          OUT       INTEGER,
   nlink         OUT       INTEGER,
   nref          OUT       INTEGER,
   store_name    IN        VARCHAR2 DEFAULT NULL);

Parameters

Usage Notes

• 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, is still counted only once).

• Since database objects are dynamically expandable, it is not easy to estimate the division between "free" space and "used" space.

TRACE Procedure

This procedure outputs tracing to the current foreground trace file.

Syntax

DBMS_DBFS_CONTENT.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 '');

Parameters

Usage Notes

• 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 2 components: "severity" and "detail". These can be thought of as additive bitmasks.

  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 trace at any severity they choose, although a good rule of thumb would use severity "1" for top level API entry and exit traces, "2" for internal operations, and "3" or greater for very low-level traces.

  The "detail" controls how much additional information: timestamps, short-stack, etc. is dumped along with each trace record.

TRACEENABLED Function

This function determines if the current trace "severity" set by the SETTRACE Procedure is at least as high as the given trace level.

Syntax

DBMS_DBFS_CONTENT.TRACEENABLED(
   sev         IN              INTEGER)
  RETURN  INTEGER;

Parameters

Return Values

Returns 0 if the requested severity level is lower than the currently set trace severity level; 1 otherwise.

UNLOCKPATH Procedure

This procedure unlocks path items that were previously locked with the LOCKPATH Procedure.

Syntax

DBMS_DBFS_CONTENT.UNLOCKPATH (
   path           IN     VARCHAR2,
   store_name     IN     VARCHAR2    DEFAULT NULL,
   principal      IN     VARCHAR2    DEFAULT NULL);

Parameters

UNMOUNTSTORE Procedure

This procedure unmounts a registered store, either by name or by mount point.

Syntax

DBMS_DBFS_CONTENT.UNMOUNTSTORE (
   store_name       IN      VARCHAR2   DEFAULT NULL,
   store_mount      IN      VARCHAR2   DEFAULT NULL,
   ignore_unknown   IN      BOOLEAN    DEFAULT FALSE);

Parameters

Usage Notes

• Single stores can be unmounted only by store name (since 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) are not guaranteed to work.

• If the ignore_unknown argument is TRUE, attempts to unregister unknown stores or mounts do not raise an exception.

UNREGISTERSTORE Procedure

This procedure unregisters a previously registered store (invalidating all mount points associated with it).

Syntax

DBMS_DBFS_CONTENT.UNREGISTERSTORE (
   store_name          IN      VARCHAR2,
   ignore_unknown      IN      BOOLEAN DEFAULT FALSE);

Parameters

Usage Notes

• Once unregistered all access to the store (and its mount points) are not guaranteed to work

• If the ignore_unknown argument is TRUE, attempts to unregister unknown stores do not raise an exception.