1 package dbms_dbfs_content
2 authid current_user
3 as
4
5
6
7 /*
8 * Pathname constants and types:
9 *
10 * PATH_MAX is the maximum length of an absolute pathname visible to
11 * clients. NAME_MAX is the maximum length of any individual
12 * component of an absolute pathname visible to clinets. These
13 * constants are modeled after the POSIX counterparts.
14 *
15 * PL/SQL types "path_t" and "name_t" are portable aliases for
16 * strings that can represent pathnames and component names, rspy.
17 *
18 */
19
20 NAME_MAX constant pls_integer := 256;
21 subtype name_t is varchar2(256); /* NAME_MAX */
22
23 PATH_MAX constant pls_integer := 1024;
24 subtype path_t is varchar2(1024); /* PATH_MAX */
25
26
27
28 /*
29 * ContentID constants and types:
30 *
31 * CONTENT_ID_MAX is the maximum length of a store-specific
32 * provider-generated contentID that identifies a file-type item.
33 *
34 * PL/SQL type "content_id_t" is a portable aliases for raw buffers
35 * that can represent contentID values.
36 *
37 */
38
39 CONTENT_ID_MAX constant pls_integer := 128;
40 subtype content_id_t is raw(128); /* CONTENT_ID_MAX */
41
42
43
44 /*
45 * Path properties: generalized (name, value, typecode) tuples:
46 *
47 * Every pathname in a store is associated with a set of properties.
48 * For simplicity and genericity, each property is identified by a
49 * string "name", has a string "value" (possibly "null" if unset or
50 * undefined or unsupported by a specific store implementation) and
51 * a value "typecode" (a numeric discriminant for the actual type of
52 * value held in the "value" string.
53 *
54 * Coercing property values to strings has the advantage of making
55 * the various interfaces uniform and compact (and can even simplify
56 * implementation of the underlying stores), but has the
57 * disadvantage of the potential for information loss during
58 * conversions to/from strings.
59 *
60 * It is expected that clients and stores use well-defined database
61 * conventions for these conversions, and use the "typecode" field
62 * (explained below) as appropriate.
63 *
64 *
65 * PROPNAME_MAX is the maximum length of a property name, and
66 * PROPVAL_MAX is the maximum length of the string value of a
67 * property.
68 *
69 * PL/SQL types "propname_t" and "propval_t" are portable aliases
70 * for strings that can represent property names and values, rspy.
71 *
72 *
73 * A typecode is a numeric value (see the various constants defined
74 * in "dbms_types") representing the true type of a string-coerced
75 * property value. Not all typecodes defined in "dbms_types" are
76 * necessarily even supportable in stores. Simple scalar types
77 * (numbers, dates, timestamps, etc.) can be depended on by clients
78 * and must be implemented by stores.
79 *
80 * Since standard RDBMS typecodes are positive integers, the DBFS
81 * API allows negative integers to represent client-defined types by
82 * negative typecodes. These typecodes do not conflict with standard
83 * typecodes, and will be persisted and returned to the client as
84 * needed, but need not be interpreted by the DBFS API or any
85 * particular store. Portable client applications should not use
86 * user-defined typecodes as a backdoor way of passing information
87 * to specific stores.
88 *
89 */
90
91 PROPNAME_MAX constant pls_integer := 32;
92 subtype propname_t is varchar2(32); /* PROPNAME_MAX */
93
94 PROPVAL_MAX constant pls_integer := 1024;
95 subtype propval_t is varchar2(1024); /* PROPVAL_MAX */
96
97
98
99 /*
100 * Pathname types:
101 *
102 * Stores can contain and provide access to 4 types of entities:
103 *
104 * type_file:
105 * A regular file storing data (a logically linear sequence of
106 * bytes accessing as a BLOB).
107 *
108 * type_directory:
109 * A container of other pathname types, including file types.
110 *
111 * type_link:
112 * A symbolic link (i.e. an uninterpreted string value associated
113 * with a pathname). Since symbolic links may represent pathnames
114 * that fall outside the scope of any given store (or even the
115 * entire aggregation of stores managed by the DBFS API), or may
116 * not even represent pathnames, clients must be careful in
117 * creating symbolic links, and stores must be careful in trying
118 * to resolve these links internally.
119 *
120 * type_reference:
121 * A hard link (i.e. an always valid pathname alias) to other
122 * paths.
123 *
124 *
125 * Not all stores need to implement all of directories, links, or
126 * references (see "features" below).
127 *
128 */
129
130 type_file constant pls_integer := 1; /* normal file */
131 type_directory constant pls_integer := 2; /* directory */
132 type_link constant pls_integer := 3; /* symbolic link */
133 type_reference constant pls_integer := 4; /* hard link */
134
135
136
137 /*
138 * Store features:
139 *
140 * In order to provide a common programmatic interface to as many
141 * different types of stores as possible, the DBFS API leaves some
142 * of the behavior of various operations to individual store
143 * providers to define and implement.
144 *
145 * However, it is still important to provide client-side programmers
146 * with an API that is sufficiently rich and conducive to portable
147 * applications.
148 *
149 * The DBFS API achieves this by allowing different store providers
150 * (and different stores) to describe themselves via a "feature set"
151 * (a bitmask indicating which features they support and which ones
152 * they do not).
153 *
154 * Using the feature set, it is possible, albeit tricky, for client
155 * applications to compensate for the feature deficiences of
156 * specific stores by implementing additional logic on the
157 * client-side, and deferring complex operations to stores capable
158 * of supporting them.
159 *
160 *
161 * feature_folders:
162 * Set if the store supports folders (or directories) as part of
163 * hierarchical pathnames.
164 *
165 * feature_foiat:
166 * Set if implicit folder operations within the store (performed
167 * as part of a client-requested operation) runs inside autonomous
168 * transactions. In general, the use of autonomous transactions is
169 * a compromise between (a) simplicity in the implementation and
170 * client-controlled transaction scope for all operations, at the
171 * cost of greatly reduced concurrency (feature_foiat not set),
172 * vs. (b) more complex implementation and smaller
173 * client-controlled transaction scope, at the benefit of greatly
174 * increased concurrency (feature_foiat set).
175 *
176 * Access to read-only (or read-mostly) stores should not be
177 * greatly affected by this feature.
178 *
179 * feature_nowait:
180 * Set if the store allows "nowait" gets of path elements. The
181 * default behavior is to wait for row locks; if "nowait" gets are
182 * implemented, the get operation raises an ORA-54 exception if
183 * the path element is already locked by another transaction.
184 *
185 *
186 * feature_acls:
187 * Set if the store supports "access control lists" and internal
188 * authorization/checking based on these acls. Acls are standard
189 * properties (see below), but a store may do nothing more than
190 * store and retrieve the "acls" without interpreting them in any
191 * way.
192 *
193 *
194 * feature_links, feature_link_deref:
195 * Set if the store supports symbolic links, and if certain types
196 * of symbolic links (specifically non-absolute pathnames) can be
197 * internally resolved by the store itself.
198 *
199 * feature_references:
200 * Set if the store supports hard links.
201 *
202 *
203 * feature_locking:
204 * Set if the store supports user-level locks (read-only,
205 * write-only, read-write) that can be applied on various items of
206 * the store, and if the store uses these lock settings to control
207 * various types of accesses to the locked items. User-level locks
208 * are orthogonal to transaction locks and persist beyond the
209 * scope of any specific transaction, session, or
210 * connection---this implies that the store itself may not be able
211 * to clean up after dangling locks, and client-applications need
212 * to perform any garbage collection.
213 *
214 * feature_lock_hierarchy:
215 * Set if the store allows a user-lock to control access to the
216 * entire subtree under the locked pathname. A simpler locking
217 * model would have locking semantics apply only to a specific
218 * pathname, and depend on the locks placed on its parents or
219 * children (unless the requested operation would implicitly need
220 * to modify these parents or children).
221 *
222 * feature_lock_convert:
223 * Set if the store supports upgrade/downgrade of locks from one
224 * mode to another.
225 *
226 *
227 * feature_versioning:
228 * Set if the store supports at least a linear versioning and
229 * version management. Different versions of the same pathname are
230 * idenfied by monotonic version numbers, with a
231 * version-nonqualified pathname representing the latest version.
232 *
233 * feature_version_path:
234 * Set if the store supports a hierarchical namespace for
235 * different versions of a pathname.
236 *
237 * feature_soft_deletes:
238 * Set if the store supports a "soft-delete", i.e. the ability to
239 * delete a pathname and make it invisible to normal operations,
240 * but retain the ability to restore the pathname later (as long
241 * as it has not been overwritten by a new create operation). The
242 * store also supports purging soft-deleted pathnames (making them
243 * truly deleted), and navigation modes that show soft-deleted
244 * items.
245 *
246 *
247 * feature_hashing:
248 * Set if the store automatically computes and maintains some type
249 * of a secure hash of the contents of a pathname (typically a
250 * type_file path).
251 *
252 * feature_hash_lookup:
253 * Set if the store allows "content-based addressing", i.e. the
254 * ability to locate an item based, not on its pathname, but on
255 * its content hash.
256 *
257 *
258 * feature_filtering:
259 * Set if the store allows clients to pass a filter function (a
260 * PL/SQL function conforming to the signature below) that returns
261 * a logical boolean indicating if a given store item satisfies a
262 * selection predicate. Stores that support filtering may be able
263 * to more efficiently perform item listing, directory navigation,
264 * and deletions by embedding the filtering logic inside their
265 * implementation. If filtering is not supported, clients can
266 * retrieve more items than necessary and perform the filtering
267 * checks themselves, albeit less efficiently.
268 *
269 * A filter predicate is a function with the following signature:
270 *
271 * function filterFunction(
272 * path in varchar2,
273 * store_name in varchar2,
274 * opcode in integer,
275 * item_type in integer,
276 * properties in dbms_dbfs_content_properties_t,
277 * content in blob)
278 * return integer;
279 *
280 * Any PL/SQL function conforming to this signature can examine the
281 * contents and properties of a store item, and decide if the item
282 * satisfies the selection criterion for the current operation. A
283 * "true" return value (i.e. non-zero) will result in the DBFS API
284 * processing the item as part of the current operation; a "false"
285 * return value (i.e. zero or null) will result in the item being
286 * skipped entirely from processing.
287 *
288 * feature_searching:
289 * Set if the store allows clients to pass a text-search filter
290 * query to locate type_file pathnames based on their content.
291 * Stores that support searching may use indexes to accelerate
292 * such searches; otherwise, clients need to build their own
293 * indexes, or else search a potentially larger set of items to
294 * locate the ones of interest for the current search.
295 *
296 * feature_asof:
297 * Set if the store allows clients to use a "flashback" timestamp
298 * in query operations (non-mutating getPath, list, search).
299 *
300 * feature_provider_props:
304 *
301 * Set if the store allows per-operation properties (that control
302 * the behavior of the store w.r.t. the current operation, as
303 * opposed to properties associated with individual items).
305 * feature_snapshots:
306 * Set if the store allows the use of named, read-only snapshots
307 * of its contents. It is up to the provider to implement
308 * snapshots using any suitable means (including creating
309 * immediate copies of the content, or using copy-on-write) and
310 * managing dependencies between snapshots and its parent view.
311 *
312 * feature_dot_snapshot:
313 * Set if the store implicitly automounts and allows access to
314 * snapshots via a ".snapshots" (or similar) pseudo-directory,
315 * without the need to explicitly create a new store. Automounting
316 * snapshots can confuse various tools that depend on the
317 * uniqueness of pathname GUIDs within a filesystem.
318 *
319 * feature_clones:
320 * Set if the store allows the use of named, writeable clones of
321 * its contents. It is up to the provider to implement clones
322 * using any suitable means (including creating immediate copies
323 * of the content, or using copy-on-write) and managing
324 * dependencies between clones and its parent view.
325 *
326 * feature_locator:
327 * Set if the store allows direct access to file contents via a
328 * lob locator. Stores that internally manipulate the file
329 * contents, perhaps by shredding/reassembling them in separate
330 * pieces, performing other transformations, etc., cannot
331 * transparently give out a lob locator to clients. The file
332 * contents of these stores should be accessed using the
333 * buffer-based APIs.
334 *
335 * feature_content_id:
336 * Set if the store allows a "pathless", contentID-based access to
337 * files (there is no notion of a directory, link, or reference in
338 * this model).
339 *
340 * feature_lazy_path:
341 * Set if the store allows a "lazy" binding of a pathname to file
342 * elements that are otherwise identified by a contentID; this
343 * feature makes sense only in conjunction with
344 * "feature_content_id".
345 *
346 * feature_no_special:
347 * A mount-specific property that disables special pathname
348 * conventions w.r.t. the "@@" infix/suffix and the ".dbfs"
349 * component name (see "special pathname conventions" below).
350 *
351 * feature_getattr_view:
352 * Set if the provider can create and support a view conforming to
353 * the "dbms_fuse.dir_entry_t" schema and specialized for
354 * "dbms_fuse.fs_getattr()" lookups.
355 *
356 *
357 */
358
359 feature_folders constant pls_integer := 1;
360 feature_foiat constant pls_integer := 2;
361 feature_nowait constant pls_integer := 4;
362
363 feature_acls constant pls_integer := 8;
364
365 feature_links constant pls_integer := 16;
366 feature_link_deref constant pls_integer := 32;
367 feature_references constant pls_integer := 64;
368
369 feature_locking constant pls_integer := 128;
370 feature_lock_hierarchy constant pls_integer := 256;
371 feature_lock_convert constant pls_integer := 512;
372
373 feature_versioning constant pls_integer := 1024;
374 feature_version_path constant pls_integer := 2048;
375 feature_soft_deletes constant pls_integer := 4096;
376
377 feature_hashing constant pls_integer := 8192;
378 feature_hash_lookup constant pls_integer := 16384;
379
380 feature_filtering constant pls_integer := 32768;
381 feature_searching constant pls_integer := 65536;
382
383 feature_asof constant pls_integer := 131072;
384 feature_provider_props constant pls_integer := 262144;
385
386 feature_snapshots constant pls_integer := 524288;
387 feature_dot_snapshot constant pls_integer := 1048576;
388 feature_clones constant pls_integer := 2097152;
389
390 feature_locator constant pls_integer := 4194304;
391
392 feature_content_id constant pls_integer := 8388608;
393 feature_lazy_path constant pls_integer := 16777216;
394 feature_no_special constant pls_integer := 33554432;
395 feature_getattr_view constant pls_integer := 67108864;
396
397
398
399 /*
400 * Lock types:
401 *
402 * Stores that support locking should implement 3 types of locks:
403 * lock_read_only, lock_write_only, and lock_read_write.
404 *
405 * User-locks (of one of these 3 types) can be associated with a
406 * user-supplied "lock_data"---this is not interpreted by the store,
407 * but can be used by client applications for their own purposes
408 * (for example, the user-data could indicate the time at which the
409 * lock was placed, assuming some part of the client application is
410 * interested in later using this information to control its
411 * actions, e.g. garbage collect stale locks or explicitly break
412 * locks).
413 *
414 *
415 * In the simplest locking model, a lock_read_only prevents all
419 * allows implicit reads, and reads to parent/child pathnames). A
416 * explicit modifications to a pathname (but allows implicit
417 * modifications, and changes to parent/child pathnames). A
418 * lock_write_only prevents all explicit reads to the pathname (but
420 * lock_wread_write allows both
421 *
422 *
423 * All locks are associated with a "principal" performing the
424 * locking operation; stores that support locking are expected to
425 * preserve this information, and use it to perform read/write lock
426 * checking (see "opt_locker").
427 *
428 *
429 * More complex lock models: multiple read-locks, lock-scoping
430 * across pathname hierarchies, lock conversions, group-locking,
431 * etc. are possible but currently not defined by the DBFS API.
432 *
433 */
434
435 lock_read_only constant pls_integer := 1;
436 lock_write_only constant pls_integer := 2;
437 lock_read_write constant pls_integer := 3;
438
439
440
441 /*
442 * Standard properties:
443 *
444 * Standard properties are well-defined, mandatory properties
445 * associated with all pathames that all stores should support (in
446 * the manner described by the DBFS API), with some concessions
447 * (e.g. a read-only store need not implement a "modification_time"
448 * or "creation_time"; stores created against tables with a
449 * fixed-schema may choose reasonable defaults for as many of these
450 * properties as needed, etc.).
451 *
452 * All standard properties informally use the "std:" namespace.
453 * Clients and stores should avoid using this namespace to define
454 * their own properties since this can cause conflicts in future.
455 *
456 * The menu of standard properties is expected to be fairly stable
457 * over time.
458 *
459 *
460 * std_access_time (TYPECODE_TIMESTAMP in UTC):
461 * The time of last access of a pathname's contents.
462 *
463 * std_acl (TYPECODE_VARCHAR2):
464 * The access control list (in standard ACL syntax) associated
465 * with the pathname.
466 *
467 * std_canonical_path (TYPECODE_VARCHAR2):
468 * The canonical store-specific pathname of an item, suitably
469 * cleaned up (leading/trailing "/" collapsed/trimmed, etc.)
470 *
471 * std_change_time (TYPECODE_TIMESTAMP in UTC):
472 * The time of last change to the metadata of a pathname.
473 *
474 * std_children (TYPECODE_NUMBER):
475 * The number of child directories/folders a directory/folder path
476 * has (this property should be available in providers that
477 * support the "feature_folders" feature).
478 *
479 * std_content_type (TYPECODE_VARCHAR2):
480 * The client-supplied mime-type(s) (in standard RFC syntax)
481 * describing the (typically type_file) pathname. The content type
482 * is not necessarily interpreted by the store.
483 *
484 * std_creation_time (TYPECODE_TIMESTAMP in UTC):
485 * The time at which the item was created (once set, this value
486 * never changes for the lifetime of the pathname).
487 *
488 * std_deleted (TYPECODE_NUMBER as a boolean):
489 * Set to a non-zero number if the pathname has been
490 * "soft-deleted" (see above for this feature), but not yet
491 * purged.
492 *
493 * std_guid (TYPECODE_NUMBER):
494 * A store-specific unique identifier for a pathname. Clients must
495 * not depend on the GUID being unique across different stores,
496 * but a given (<store-name>, <store-specific-pathname>) has a
497 * stable and unique GUID for its lifetime.
498 *
499 * std_length (TYPECODE_NUMBER):
500 * The length of the content (BLOB) of a type_file/type_reference
501 * path, or the length of the referent of a type_link symbolic
502 * link. Directories do not have a well-defined length and stores
503 * are free to set this property to zero, null, or any other value
504 * they choose.
505 *
506 * std_modification_time (TYPECODE_TIMESTAMP in UTC):
507 * The time of last change to the data associated with a pathname.
508 * Changes to the content of a type_file/type_reference path, the
509 * referent of the type_link path, and addtion/deletion of
510 * immediate children in a type_directory path, all constitute
511 * data changes.
512 *
513 * std_owner (TYPECODE_VARCHAR2):
514 * A client-supplied (or implicit) owner name for the pathname.
515 * The owner name may be used (along with the current "principal")
516 * for access checks by stores that support ACLs and/or locking.
517 *
518 * std_parent_guid (TYPECODE_NUMBER):
519 * A store-specific unique identifier for the parent of a
520 * pathname. Clients must not depend on the GUID being unique
521 * across different stores, but a given (<store-name>,
522 * <store-specific-pathname>) has a stable and unique GUID for its
523 * lifetime.
524 *
525 * std_parent_guid(pathname) == std_guid(parent(pathname))
526 *
527 * std_referent (TYPECODE_VARCHAR2):
528 * The content of the symbolic link of a type_link path; null
529 * otherwise. As mentioned before, the std_referent can be an
530 * arbitrary string and must not necessarily be interpreted as
534 */
531 * pathname by clients (or such interpretation should be done with
532 * great care).
533 *
535
536 std_access_time constant varchar2(32) := 'std:access_time';
537 std_acl constant varchar2(32) := 'std:acl';
538 std_canonical_path constant varchar2(32) := 'std:canonical_path';
539 std_change_time constant varchar2(32) := 'std:change_time';
540 std_children constant varchar2(32) := 'std:children';
541 std_content_type constant varchar2(32) := 'std:content_type';
542 std_creation_time constant varchar2(32) := 'std:creation_time';
543 std_deleted constant varchar2(32) := 'std:deleted';
544 std_guid constant varchar2(32) := 'std:guid';
545 std_length constant varchar2(32) := 'std:length';
546 std_modification_time constant varchar2(32) := 'std:modification_time';
547 std_owner constant varchar2(32) := 'std:owner';
548 std_parent_guid constant varchar2(32) := 'std:parent_guid';
549 std_referent constant varchar2(32) := 'std:referent';
550
551
552
553 /*
554 * Optional properties:
555 *
556 * Optional properties are well-defined but non-mandatory properties
557 * associated with all pathames that all stores are free to support
558 * (but only in the manner described by the DBFS API). Clients
559 * should be prepared to deal with stores that support none of the
560 * optional properties.
561 *
562 * All optional properties informally use the "opt:" namespace.
563 * Clients and stores should avoid using this namespace to define
564 * their own properties since this can cause conflicts in future.
565 *
566 * The menu of optional properties is expected to be expand over
567 * time.
568 *
569 *
570 * opt_hash_type (TYPECODE_NUMBER):
571 * The type of hash provided in the "opt_hash_value" property; see
572 * "dbms_crypto" for possible options.
573 *
574 * opt_hash_value (TYPECODE_RAW):
575 * The hash value of type "opt_hash_type" describing the content
576 * of the pathname.
577 *
578 *
579 * opt_lock_count (TYPECODE_NUMBER):
580 * The number of (compatible) locks placed on a pathname. If
581 * different principals are allowed to place compatible (read)
582 * locks on a path, the "opt_locker" must specify all lockers
583 * (with repeats so that lock counts can be correctly maintained).
584 *
585 * opt_lock_data (TYPECODE_VARCHAR2):
586 * The client-supplied user-data associated with a user-lock,
587 * uninterpreted by the store.
588 *
589 * opt_locker (TYPECODE_VARCHAR2):
590 * The implicit or client-specified principal(s) that applied a
591 * user-lock on a pathname.
592 *
593 * opt_lock_status (TYPECODE_NUMBER):
594 * One of the "lock_read_only", "lock_write_only",
595 * "lock_read_write" values describing the type of lock currently
596 * applied on a pathname.
597 *
598 *
599 * opt_version (TYPECODE_NUMBER):
600 * A sequence number for linear versioning of a pathname.
601 *
602 * opt_version_path (TYPECODE_VARCHAR2):
603 * A version-pathname for hierarchical versioning of a pathname.
604 *
605 * opt_content_id (TYPECODE_RAW):
606 * A stringified provider-generated store-specific unique
607 * contentID for a file element (that may optionally not be
608 * associated with a path; see "feature_content_id" and
609 * "feature_lazy_path").
610 *
611 */
612
613 opt_hash_type constant varchar2(32) := 'opt:hash_type';
614 opt_hash_value constant varchar2(32) := 'opt:hash_value';
615 opt_lock_count constant varchar2(32) := 'opt:lock_count';
616 opt_lock_data constant varchar2(32) := 'opt:lock_data';
617 opt_locker constant varchar2(32) := 'opt:locker';
618 opt_lock_status constant varchar2(32) := 'opt:lock_status';
619 opt_version constant varchar2(32) := 'opt:version';
620 opt_version_path constant varchar2(32) := 'opt:version_path';
621 opt_content_id constant varchar2(32) := 'opt:content_id';
622
623
624
625 /*
626 * Property access flags:
627 *
628 * DBFS API methods to get/set properties can use combinations of
629 * property access flags to fetch properties from different
630 * namespaces in a single API call.
631 *
632 *
633 * prop_none:
634 * Used when the client is not interested in any properties, and
635 * is invoking the content access method for other reasons
636 * (pathname existence/lockability validation, data access, etc.)
637 *
638 * prop_std:
639 * Used when the client is interested in the standard properties;
640 * all standard properties are retrieved if this flag is
641 * specified.
642 *
643 * prop_opt:
644 * Used when the client is interested in the optional properties;
645 * all optional properties are retrieved if this flag is
646 * specified.
647 *
648 * prop_usr:
649 * Used when the client is interested in the user-defined
650 * properties; all user-defined properties are retrieved if this
654 * An alias for the combination of all standard, optional, and
651 * flag is specified.
652 *
653 * prop_all:
655 * user-defined properties.
656 *
657 * prop_data:
658 * Used when the client is interested only in data access, and
659 * does not care about properties.
660 *
661 * prop_spc:
662 * Used when the client is interested in a mix-and-match of
663 * different subsets of various property namespaces; the names of
664 * the specific properties to fetch are passed into the DBFS API
665 * method call as arguments, and only these property values are
666 * fetched and returned to the client. This is useful in cases
667 * where there are a very large number of properties potentially
668 * accessible, but the client is interested in only a small number
669 * of them (and knows the names of these "interesting" properties
670 * beforehand).
671 *
672 * "prop_spc" is applicable only to the various "getPath"
673 * operations. Other operations that specify properties will
674 * simply ignore "prop_spc" specifications.
675 *
676 */
677
678 prop_none constant pls_integer := 0; /* none */
679 prop_std constant pls_integer := 1; /* mandatory */
680 prop_opt constant pls_integer := 2; /* optional */
681 prop_usr constant pls_integer := 4; /* user-defined */
682 prop_all constant pls_integer := prop_std +
683 prop_opt +
684 prop_usr; /* all */
685 prop_data constant pls_integer := 8; /* content */
686 prop_spc constant pls_integer := 16; /* specific */
687
688
689
690 /*
691 * Exceptions:
692 *
693 * DBFS API operations can raise any one of the following top-level
694 * exceptions.
695 *
696 * Clients can program against these specific exceptions in their
697 * error handlers without worrying about the specific store
698 * implementations of the underlying error signally code.
699 *
700 * Store providers, for their part, should do their best to
701 * trap/wrap any internal exceptions into one of the following
702 * exception types, as appropriate.
703 *
704 */
705
706 /* a specified pathname, e.g. create, already exists */
707 path_exists exception;
708 pragma exception_init(path_exists,
709 -64000);
710
711 /* the parent of a specified pathname does not exist */
712 invalid_parent exception;
713 pragma exception_init(invalid_parent,
714 -64001);
715
716 /* the specified pathname does not exist, or is not valid */
717 invalid_path exception;
718 pragma exception_init(invalid_path,
719 -64002);
720
721 /* an operation unsupported by a store was invoked */
722 unsupported_operation exception;
723 pragma exception_init(unsupported_operation,
724 -64003);
725
726 /* an operation was invoked with invalid arguments */
727 invalid_arguments exception;
728 pragma exception_init(invalid_arguments,
729 -64004);
730
731 /* access control checks failed for the current operation */
732 invalid_access exception;
733 pragma exception_init(invalid_access,
734 -64005);
735
736 /* the current operation failed lock conflict checks */
737 lock_conflict exception;
738 pragma exception_init(lock_conflict,
739 -64006);
740
741 /* an invalid store name was specified */
742 invalid_store exception;
743 pragma exception_init(invalid_store,
744 -64007);
745
746 /* an invalid mount-point was specified */
747 invalid_mount exception;
748 pragma exception_init(invalid_mount,
749 -64008);
750
751 /* an invalid provider-package was specified */
752 invalid_provider exception;
753 pragma exception_init(invalid_provider,
754 -64009);
755
756 /* a mutating operation was invoked on a read-only mount/store */
757 readonly_path exception;
758 pragma exception_init(readonly_path,
759 -64010);
760
761 /* an operation spanning 2 or more distinct stores was invoked */
762 cross_store_operation exception;
763 pragma exception_init(cross_store_operation,
764 -64011);
765
766 /* specified path is a directory */
767 path_is_directory exception;
768 pragma exception_init(path_is_directory,
769 -64012);
770
771 /* specified path is not a directory */
772 path_not_directory exception;
773 pragma exception_init(path_not_directory,
774 -64013);
775
776 /* specified directory is not empty */
780
777 directory_not_empty exception;
778 pragma exception_init(directory_not_empty,
779 -64014);
781
782
783 /*
784 * Property bundles:
785 *
786 * The "property_t" record type describes a single (value, typecode)
787 * property value tuple; the property name is implied (see
788 * "properties_t" below).
789 *
790 * "properties_t" is a name-indexed hash table of property tuples.
791 * The implicit hash-table association between the index and the
792 * value allows the client to build up the full
793 * "dbms_dbfs_content_property_t" tuples for a "properties_t".
794 *
795 *
796 * There is an approximate correspondence between
797 * "dbms_dbfs_content_property_t" and "property_t"---the former is a
798 * SQL object type that describes the full property tuple, while the
799 * latter is a PL/SQL record type that describes only the property
800 * value component.
801 *
802 * Likewise, there is an approximate correspondence between
803 * "dbms_dbfs_content_properties_t" and "properties_t"---the former
804 * is a SQL nested table type, while the latter is a PL/SQL hash
805 * table type.
806 *
807 *
808 * Dynamic SQL calling conventions force the use of SQL types, but
809 * PL/SQL code may be implemented more conveniently in terms of the
810 * hash-table types.
811 *
812 * The DBFS API provides convenient utility functions to convert
813 * between "dbms_dbfs_content_properties_t" and "properties_t" (see
814 * "propertiesT2H" and "propertiesH2T" below).
815 *
816 */
817
818 type property_t is record (
819 propvalue propval_t,
820 typecode integer
821 );
822 type properties_t is table of property_t
823 index by propname_t;
824
825 /* properties table to hash */
826 /* convert a dbms_dbfs_content_properties_t to a property_t */
827 function propertiesT2H(
828 sprops in dbms_dbfs_content_properties_t)
829 return properties_t;
830
831 /* properties hash to table */
832 /* convert a properties_t into a dbms_dbfs_content_properties_t */
833 function propertiesH2T(
834 pprops in properties_t)
835 return dbms_dbfs_content_properties_t;
836
837
838
839 /*
840 * Simple property constructors.
841 *
842 */
843
844 function propAny(
845 val in number)
846 return property_t;
847 function propAny(
848 val in varchar2)
849 return property_t;
850 function propAny(
851 val in timestamp)
852 return property_t;
853 function propAny(
854 val in raw)
855 return property_t;
856
857 function propNumber(
858 val in number)
859 return property_t;
860 function propVarchar2(
861 val in varchar2)
862 return property_t;
863 function propTimestamp(
864 val in timestamp)
865 return property_t;
866 function propRaw(
867 val in raw)
868 return property_t;
869
870
871
872 /*
873 * Store descriptors:
874 *
875 * A "store_t" is a record that describes a store registered with
876 * and managed by the DBFS API (see the Administrative APIs below).
877 *
878 * A "mount_t" is a record that describes a store mount point and
879 * its properties.
880 *
881 * Clients can query the DBFS API for the list of available stores,
882 * determine which store will handle accesses to a given pathname,
883 * and determine the feature set for the store.
884 *
885 */
886
887 type store_t is record (
888 store_name varchar2(32),
889 store_id number,
890 provider_name varchar2(32),
891 provider_pkg varchar2(32),
892 provider_id number,
893 provider_version varchar2(32),
894 created timestamp,
895 store_features integer,
896 store_guid number
897 );
898 type stores_t is table of store_t;
899
900
901 type mount_t is record (
902 store_name varchar2(32),
903 store_id number,
904 provider_name varchar2(32),
905 provider_pkg varchar2(32),
906 provider_id number,
907 provider_version varchar2(32),
908 store_features integer,
909 store_guid number,
910 store_mount name_t,
911 created timestamp,
912 mount_properties dbms_dbfs_content_properties_t
913 );
914 type mounts_t is table of mount_t;
915
916
917
918 /*
919 * Administrative and query APIs:
920 *
924 * of their choice.
921 * (Administrative) clients and store providers are expected to
922 * register stores with the DBFS API. Additionally, administrative
923 * clients are expected to mount stores into the toplevel namespace
925 *
926 * The registration/unregistration of a store is separated from the
927 * mount/unmount of a store since it is possible for the same store
928 * to be mounted multiple times at different mount-points (and this
929 * is under client control).
930 *
931 *
932 * The administrative methods in "dbms_dbfs_content" are merely
933 * wrappers that delegate to the matching methods in
934 * "dbms_dbfs_content_admin". Clients can use the methods in either
935 * package to perform administrative operations.
936 *
937 */
938
939
940
941 /*
942 * Register a new store "store_name" backed by provider
943 * "provider_name" that uses "provider_package" as the store
944 * provider (conforming to the "dbms_dbfs_content_spi" package
945 * signature).
946 *
947 * This method is to be used primarily by store providers after they
948 * have created a new store.
949 *
950 * Store names must be unique.
951 *
952 *
953 * The procedure executes like a DDL (i.e. auto-commits before and
954 * after its execution).
955 *
956 */
957
958 procedure registerStore(
959 store_name in varchar2,
960 provider_name in varchar2,
961 provider_package in varchar2);
962
963
964 /*
965 * Unregister a previously registered store (invalidating all
966 * mount-points associated with it).
967 *
968 * Once unregistered all access to the store (and its mount-points)
969 * are not guaranteed to work (although CR may provide a temporary
970 * illusion of continued access).
971 *
972 *
973 * If the "ignore_unknown" argument is "true", attempts to
974 * unregister unknown stores will not raise an exception.
975 *
976 *
977 * The procedure executes like a DDL (i.e. auto-commits before and
978 * after its execution).
979 *
980 */
981
982 procedure unregisterStore(
983 store_name in varchar2,
984 ignore_unknown in boolean default false);
985
986
987 /*
988 * Mount a registered store "store_name" and bind it to the
989 * "store_mount" mount-point.
990 *
991 * Once mounted, accesses to pathnames of the form
992 * "/<store_mount>/xyz..." will be redirected to <store_name> and
993 * its store provider.
994 *
995 *
996 * Store mount-points must be unique, and a syntactically valid
997 * pathname component (i.e. a "name_t" with no embedded "/").
998 *
999 *
1000 * If a mount-point is not specified (i.e. is null), the DBFS API
1001 * attempts to use the store name itself as the mount-point name
1002 * (subject to the uniqueness and syntactic constraints).
1003 *
1004 *
1005 * A special empty mount-point is available for singleton stores,
1006 * i.e. a scenario where the DBFS API manages a single backend
1007 * store---in such cases, the client can directly deal with full
1008 * pathnames of the form "/xyz..." since there is no ambiguity in
1009 * how to redirect these accesses.
1010 *
1011 * Singleton mount-points are indicated by the "singleton" boolean
1012 * argument, and the "store_mount" argument is ignored.
1013 *
1014 *
1015 * The same store can be mounted multiple times, obviously at
1016 * different mount-points.
1017 *
1018 *
1019 * Mount properties can be used to specify the DBFS API execution
1020 * environment, i.e. default values of the principal, owner, acl,
1021 * and asof for a particular mount-point. Mount properties can also
1022 * be used to specify a read-only mount. If a flashback mount is
1023 * specified (via "asof"), it implies a read-only mount.
1024 *
1025 *
1026 * The procedure executes like a DDL (i.e. auto-commits before and
1027 * after its execution).
1028 *
1029 */
1030
1031 procedure mountStore(
1032 store_name in varchar2,
1033 store_mount in varchar2 default null,
1034 singleton in boolean default false,
1035 principal in varchar2 default null,
1036 owner in varchar2 default null,
1037 acl in varchar2 default null,
1038 asof in timestamp default null,
1039 read_only in boolean default false);
1040
1041
1042 /*
1043 * Remount a previously mounted store, either by name or by mount
1044 * point, or remount all known mounts.
1045 *
1046 *
1047 * A remount of an existing mount-point preserves the properties of
1048 * the underlying store/mount, but re-executes the implicit
1049 * side-effect actions of dropping and creating the mount.
1050 *
1051 * An example of such a side-effect is the recreation of attribute
1052 * views.
1053 *
1057 * with the store.
1054 *
1055 * Remounting a store by name (i.e. "store_name" is not null,
1056 * "store_mount" is null) will remount all mount-points associated
1058 *
1059 * Remounting a store by mount point (i.e. "store_mount" is not
1060 * null) will remount only the specified mount---the "store_name"
1061 * can be specified as "null". If "store_name" is also specified, it
1062 * is used for validation (i.e. an invalid store_name/store_mount
1063 * combination will fail).
1064 *
1065 * Singleton mounts can be remounted by specifying either the
1066 * store_name (first option above), or by specifying both
1067 * "store_name" and "store_mount" as null.
1068 *
1069 *
1070 * If the "ignore_unknown" argument is "true", attempts to remount
1071 * unknown or invalid combinations of stores/mounts will not raise
1072 * an exception.
1073 *
1074 *
1075 * The procedure executes like a DDL (i.e. auto-commits before and
1076 * after its execution).
1077 *
1078 */
1079
1080 procedure remountStore(
1081 store_name in varchar2 default null,
1082 store_mount in varchar2 default null,
1083 ignore_unknown in boolean default false);
1084
1085 procedure remountAll;
1086
1087
1088 /*
1089 * Unmount a previously mounted store, either by name or by mount
1090 * point, or unmount all known mounts.
1091 *
1092 *
1093 * Unmounting a store by name (i.e. "store_name" is not null,
1094 * "store_mount" is null) will unmount all mount-points associated
1095 * with the store.
1096 *
1097 * Unmounting a store by mount point (i.e. "store_mount" is not
1098 * null) will unmount only the specified mount---the "store_name"
1099 * can be specified as "null". If "store_name" is also specified, it
1100 * is used for validation (i.e. an invalid store_name/store_mount
1101 * combination will fail).
1102 *
1103 * Singleton mounts can be unmounted by specifying either the
1104 * store_name (first option above), or by specifying both
1105 * "store_name" and "store_mount" as null.
1106 *
1107 * Once unmounted all access to the store (or mount-point) are not
1108 * guaranteed to work (although CR may provide a temporary illusion
1109 * of continued access).
1110 *
1111 *
1112 * If the "ignore_unknown" argument is "true", attempts to unmount
1113 * unknown or invalid combinations of stores/mounts will not raise
1114 * an exception.
1115 *
1116 *
1117 * The procedure executes like a DDL (i.e. auto-commits before and
1118 * after its execution).
1119 *
1120 */
1121
1122 procedure unmountStore(
1123 store_name in varchar2 default null,
1124 store_mount in varchar2 default null,
1125 ignore_unknown in boolean default false);
1126
1127 procedure unmountAll;
1128
1129
1130 /*
1131 * List all available stores and their features.
1132 *
1133 * The "store_mount" field of the returned records is set to "null"
1134 * (since mount-points are separate from stores themselves).
1135 *
1136 */
1137
1138 function listStores
1139 return stores_t
1140 pipelined;
1141
1142
1143 /*
1144 * List all available mount-points, their backing stores, and the
1145 * store features.
1146 *
1147 * A singleton mount results in a single returned row, with its
1148 * "store_mount" field set to "null".
1149 *
1150 */
1151
1152 function listMounts
1153 return mounts_t
1154 pipelined;
1155
1156
1157 /*
1158 * Lookup specific stores and their features by: pathname, store
1159 * name, or mount-point.
1160 *
1161 */
1162
1163 type feature_t is record (
1164 feature_name varchar2(32),
1165 feature_mask integer,
1166 feature_state varchar2(3)
1167 );
1168 type features_t is table of feature_t;
1169
1170 function getStoreByPath(
1171 path in path_t)
1172 return store_t;
1173
1174 function getStoreByName(
1175 store_name in varchar2)
1176 return store_t;
1177
1178 function getStoreByMount(
1179 store_mount in varchar2)
1180 return store_t;
1181
1182 function getFeaturesByPath(
1183 path in path_t)
1184 return integer;
1185
1186 function getFeaturesByName(
1187 store_name in varchar2)
1188 return integer;
1189
1190 function getFeaturesByMount(
1191 store_mount in varchar2)
1192 return integer;
1193
1194 function decodeFeatures(
1195 featureSet in integer)
1196 return features_t
1197 deterministic
1198 pipelined;
1199
1200 function featureName(
1204
1201 featureBit in integer)
1202 return varchar2
1203 deterministic;
1205
1206
1207 /*
1208 * Lookup pathnames by (store_name, std_guid) or (store_mount,
1209 * std_guid) tuples.
1210 *
1211 * If the underlying "std_guid" is found in the underlying store,
1212 * these functions return the store-qualified pathname, or the full
1213 * absolute pathname, rspy.
1214 *
1215 * If the "std_guid" is unknown, a "null" value is returned. Clients
1216 * are expected to handle this as appropriate.
1217 *
1218 */
1219
1220 function getPathByStoreId(
1221 store_name in varchar2,
1222 guid in integer)
1223 return varchar2;
1224
1225 function getPathByMountId(
1226 store_mount in varchar2,
1227 guid in integer)
1228 return varchar2;
1229
1230
1231
1232 /*
1233 * DBFS API: space usage.
1234 *
1235 * Clients can query filesystem space usage statistics via the
1236 * "spaceUsage()" method. Store providers, in turn, are expected to
1237 * support at least the equivalent "spaceUsage()" method for their
1238 * stores (and to make a best effort determination of space
1239 * usage---esp. if the store consists of multiple
1240 * tables/indexes/lobs, etc. scattered across multiple
1241 * tablespaces/datafiles/disk-groups, etc.).
1242 *
1243 * See "dbms_dbfs_content_spi" for more details on the
1244 * DBFS-API/provider-SPI contract.
1245 *
1246 *
1247 * "blksize" is the natural tablespace blocksize that holds the
1248 * store---if multiple tablespaces with different blocksizes are
1249 * used, any valid blocksize is acceptable.
1250 *
1251 * "tbytes" is the total size of the store in bytes, and "fbytes" is
1252 * the free/unused size of the store in bytes. These values are
1253 * computed over all segments that comprise the store.
1254 *
1255 * "nfile", "ndir", "nlink", and "nref" count the number of
1256 * currently available files, directories, links, and references in
1257 * the store.
1258 *
1259 * Since database objects are dynamically growable, it is not easy
1260 * to estimate the division between "free" space and "used" space.
1261 *
1262 *
1263 * The SPI has 2 space usage methods: "spaceUsage()" and
1264 * "spaceUsageFull()". The difference between the two is that the
1265 * latter function should implement a "bulk" API---i.e. the ability
1266 * to query and aggregate space usage information for all stores
1267 * specified as the "propvalue" fields of the "store_names" property
1268 * list (the other fields of the property list can be ignored).
1269 *
1270 * If the SPI does not support the "bulk" aggregation API, the DBFS
1271 * API will itself do the necessary iteration and aggregation,
1272 * however, at the risk of inaccurate data due to potential
1273 * double-counting.
1274 *
1275 *
1276 * In all cases, the DBFS API will invoke the SPI's space usage
1277 * functions with only those stores that are managed by the provider
1278 * package.
1279 *
1280 *
1281 * A space usage query on the toplevel root directory will return a
1282 * combined summary of the space usage of all available distinct
1283 * stores under it (if the same store is mounted multiple times, it
1284 * will still be counted only once).
1285 *
1286 *
1287 * If "useEstimate" is specified, providers capable of computing
1288 * fast-but-approximate space usage information can make use of this
1289 * optimization. Otherwise, the default space usage computation will
1290 * be used.
1291 *
1292 */
1293
1294 procedure spaceUsage(
1295 path in varchar2,
1296 blksize out integer,
1297 tbytes out integer,
1298 fbytes out integer,
1299 nfile out integer,
1300 ndir out integer,
1301 nlink out integer,
1302 nref out integer,
1303 store_name in varchar2 default null,
1304 useEstimate in boolean default false);
1305
1306
1307
1308 /*
1309 * DBFS API session defaults.
1310 *
1311 * Normal client access to the DBFS API executes with an implicit
1312 * context that consists of:
1313 *
1314 * -> the "principal" invoking the current operation,
1315 *
1316 * -> the "owner" for all new elements created (implicitly or
1317 * explicitly) by the current operation,
1318 *
1319 * -> the "acl" for all new elements created (implicitly or
1320 * explicitly) by the current operation,
1321 *
1322 * and
1323 *
1324 * -> the "asof" timestamp at which the underlying read-only
1325 * operation (or its read-only sub-components) execute.
1326 *
1327 *
1328 * All of this information can be passed in explicitly via arguments
1329 * to the various DBFS API method calls, allowing the client
1333 * for the context that is automatically inherited by all operations
1330 * fine-grained control over individual operations.
1331 *
1332 * The DBFS API also allows clients to set session-duration defaults
1334 * for which the defaults are not explicitly overridden.
1335 *
1336 *
1337 * All of the context defaults start out as "null", and can be
1338 * cleared by setting them to "null".
1339 *
1340 */
1341
1342 procedure setDefaultContext(
1343 principal in varchar2,
1344 owner in varchar2,
1345 acl in varchar2,
1346 asof in timestamp);
1347 procedure setDefaultPrincipal(
1348 principal in varchar2);
1349 procedure setDefaultOwner(
1350 owner in varchar2);
1351 procedure setDefaultACL(
1352 acl in varchar2);
1353 procedure setDefaultAsOf(
1354 asof in timestamp);
1355
1356 procedure getDefaultContext(
1357 principal out nocopy varchar2,
1358 owner out nocopy varchar2,
1359 acl out nocopy varchar2,
1360 asof out timestamp);
1361 function getDefaultPrincipal
1362 return varchar2;
1363 function getDefaultOwner
1364 return varchar2;
1365 function getDefaultACL
1366 return varchar2;
1367 function getDefaultAsOf
1368 return timestamp;
1369
1370
1371
1372 /*
1373 * DBFS API: interface versioning.
1374 *
1375 * To allow for the DBFS API itself to evolve, an internal API
1376 * version will count up with each change to the public API.
1377 *
1378 * A standard naming convention will be followed in the version
1379 * string: <a.b.c> corresponding to <major>, <minor>, and <patch>
1380 * components.
1381 *
1382 */
1383
1384 function getVersion
1385 return varchar2;
1386
1387
1388
1389 /*
1390 * DBFS API: notes on pathnames.
1391 *
1392 * Clients of the DBFS API refer to store items via absolute
1393 * pathnames (but see the special exemptions for contentID-based
1394 * access below).
1395 *
1396 * These pathnames can be "full", i.e. a single string of the form
1397 * "/mount-point/pathname", or store-qualified, i.e. a 2-tuple of
1398 * the form (store_name, pathname) (where the pathname is rooted
1399 * within the store namespace).
1400 *
1401 * Clients may use either naming scheme as it suits them, and can
1402 * mix-and-match the naming within their programs.
1403 *
1404 * If pathnames are returned by DBFS API calls, the exact values
1405 * being returned depend on the naming scheme used by the client in
1406 * the call---for example, a listing or search on a full-absolute
1407 * directory name returns items with their full-absolute pathnames,
1408 * while a listing or search on a store-qualified directory name
1409 * returns items whose pathnames are store-specific (i.e. the
1410 * store-qualification is implied).
1411 *
1412 * The implementation of the DBFS API internally manages the
1413 * normalization and inter-conversion between these 2 naming
1414 * schemes.
1415 *
1416 *
1417 * Stores/providers that support contentID-based access (see
1418 * "feature_content_id") also support a form of addressing that is
1419 * not based on pathnames. Items are identified by an explicit store
1420 * name, a "null" pathname, and possibly a contentID specified as a
1421 * parameter or via the "opt_content_id" property.
1422 *
1423 * Not all operations are supported with contentID-based access, and
1424 * applications should depend only on the simplest create/delete
1425 * functionality being available.
1426 *
1427 */
1428
1429
1430
1431 /*
1432 * DBFS API: special pathname conventions.
1433 *
1434 * The DBFS, by default, reserves the path component name ".dbfs"
1435 * and the "@@" infix/suffix sequence for special semantics.
1436 *
1437 *
1438 * The "@@" sequence is used to access extended attributes via
1439 * special pathnames. For example, if a pathname element "/a/b/c/d"
1440 * has extended attributes "a1" and "a2" with values "v1" and "v2",
1441 * the following pathnames will have special meaning:
1442 *
1443 *
1444 * /a/b/c/d the original pathname
1445 * /a/b/c/d@@ a pseudo-directory containing "a1" and "a2"
1446 * /a/b/c/d@@a1 a pseudo-file containing "v1"
1447 * /a/b/c/d@@a2 a pseudo-file containing "v2"
1448 *
1449 * Client applications can use these pathnames, especially the last
1450 * 3 pathnames as if they were real pathnames, and seamlessly get
1451 * access to extended attributes using the same access methods that
1452 * would be used for normal directories and files.
1453 *
1454 * However, this implies that the "@@" sequence cannot occur as a
1458 * The "@@" special pathnames do not show up in normal directory
1455 * suffix (conflicts with the attribute pseudo-directory) or as an
1456 * infix (conflicts with attribute pseudo-files).
1457 *
1459 * listings; they need to be explicitly specified by the client.
1460 *
1461 * Creation, deletion, modification operations are allowed on the
1462 * "@@" infix qualified pathnames---these are internally implemented
1463 * as the creation, deletion, and modification of user-defined
1464 * attributes of the element. The "@@" qualified pathnames cannot be
1465 * renamed or otherwise manipulated.
1466 *
1467 *
1468 * Additionally, the ".dbfs" component name is reserved for future
1469 * use by the DBFS API, and is currently not allowed inside any
1470 * user-supplied pathname.
1471 *
1472 *
1473 * By default, the DBFS API will enforce the above constraints and
1474 * special semantics on pathnames. These constraints and special
1475 * semantics can be disabled via the mount-specific
1476 * "feature_no_special"; mounts created with this feature will not
1477 * enforce any special constraints or semantics on pathnames, and
1478 * will simply pass through the user-supplied pathnames,
1479 * uninterpreted, to the underlying store providers.
1480 *
1481 */
1482
1483
1484
1485 /*
1486 * DBFS API: creation operations
1487 *
1488 * The DBFS API allows clients to create directory, file, link, and
1489 * reference elements (subject to store feature support).
1490 *
1491 *
1492 * All of the creation methods require a valid pathname (see the
1493 * special exemption for contentID-based access below), and can
1494 * optionally specify properties to be associated with the pathname
1495 * as it is created. It is also possible for clients to fetch-back
1496 * item properties after the creation completes (so that
1497 * automatically generated properties (e.g. "std_creation_time") are
1498 * immediately available to clients (the exact set of properties
1499 * fetched back is controlled by the various "prop_xxx" bitmasks in
1500 * "prop_flags").
1501 *
1502 *
1503 * Links and references require an additional pathname to associate
1504 * with the primary pathname.
1505 *
1506 * File pathnames can optionally specify a BLOB value to use to
1507 * initially populate the underlying file content (the provided BLOB
1508 * may be any valid lob: temporary or permanent). On creation, the
1509 * underlying lob is returned to the client (if "prop_data" is
1510 * specified in "prop_flags").
1511 *
1512 * Non-directory pathnames require that their parent directory be
1513 * created first. Directory pathnames themselves can be recursively
1514 * created (i.e. the pathname hierarchy leading up to a directory
1515 * can be created in one call).
1516 *
1517 *
1518 * Attempts to create paths that already exist is an error; the one
1519 * exception is pathnames that are "soft-deleted" (see below for
1520 * delete operations)---in these cases, the soft-deleted item is
1521 * implicitly purged, and the new item creation is attempted.
1522 *
1523 *
1524 * Stores/providers that support contentID-based access accept an
1525 * explicit store name and a "null" path to create a new element.
1526 * The contentID generated for this element is available via the
1527 * "opt_content_id" property (contentID-based creation automatically
1528 * implies "prop_opt" in "prop_flags").
1529 *
1530 * The newly created element may also have an internally generated
1531 * pathname (if "feature_lazy_path" is not supported) and this path
1532 * is available via the "std_canonical_path" property.
1533 *
1534 * Only file elements are candidates for contentID-based access.
1535 *
1536 */
1537
1538 procedure createFile(
1539 path in varchar2,
1540 properties in out nocopy dbms_dbfs_content_properties_t,
1541 content in out nocopy blob,
1542 prop_flags in integer default (prop_std +
1543 prop_data),
1544 store_name in varchar2 default null,
1545 principal in varchar2 default null);
1546
1547 procedure createFile(
1548 path in varchar2,
1549 properties in out nocopy properties_t,
1550 content in out nocopy blob,
1551 prop_flags in integer default (prop_std +
1552 prop_data),
1553 store_name in varchar2 default null,
1554 principal in varchar2 default null);
1555
1556 procedure createLink(
1557 srcPath in varchar2,
1558 dstPath in varchar2,
1559 properties in out nocopy dbms_dbfs_content_properties_t,
1560 prop_flags in integer default prop_std,
1561 store_name in varchar2 default null,
1562 principal in varchar2 default null);
1563
1564 procedure createLink(
1565 srcPath in varchar2,
1566 dstPath in varchar2,
1570 principal in varchar2 default null);
1567 properties in out nocopy properties_t,
1568 prop_flags in integer default prop_std,
1569 store_name in varchar2 default null,
1571
1572 procedure createReference(
1573 srcPath in varchar2,
1574 dstPath in varchar2,
1575 properties in out nocopy dbms_dbfs_content_properties_t,
1576 prop_flags in integer default prop_std,
1577 store_name in varchar2 default null,
1578 principal in varchar2 default null);
1579
1580 procedure createReference(
1581 srcPath in varchar2,
1582 dstPath in varchar2,
1583 properties in out nocopy properties_t,
1584 prop_flags in integer default prop_std,
1585 store_name in varchar2 default null,
1586 principal in varchar2 default null);
1587
1588 procedure createDirectory(
1589 path in varchar2,
1590 properties in out nocopy dbms_dbfs_content_properties_t,
1591 prop_flags in integer default prop_std,
1592 recurse in boolean default false,
1593 store_name in varchar2 default null,
1594 principal in varchar2 default null);
1595
1596 procedure createDirectory(
1597 path in varchar2,
1598 properties in out nocopy properties_t,
1599 prop_flags in integer default prop_std,
1600 recurse in boolean default false,
1601 store_name in varchar2 default null,
1602 principal in varchar2 default null);
1603
1604
1605
1606 /*
1607 * DBFS API: deletion operations
1608 *
1609 * The DBFS API allows clients to delete directory, file, link, and
1610 * reference elements (subject to store feature support).
1611 *
1612 *
1613 * By default, the deletions are "permanent" (get rid of the
1614 * successfully deleted items on transaction commit), but stores may
1615 * also support "soft-delete" features. If requested by the client,
1616 * soft-deleted items are retained by the store (but not typically
1617 * visible in normal listings or searches).
1618 *
1619 * Soft-deleted items can be "restore"d, or explicitly purged.
1620 *
1621 *
1622 * Directory pathnames can be recursively deleted (i.e. the pathname
1623 * hierarchy below a directory can be deleted in one call).
1624 * Non-recursive deletions can be performed only on empty
1625 * directories. Recursive soft-deletions apply the soft-delete to
1626 * all of the items being deleted.
1627 *
1628 *
1629 * Individual pathnames (or all soft-deleted pathnames under a
1630 * directory) can be restored or purged via the restore and purge
1631 * methods.
1632 *
1633 *
1634 * Providers that support filtering can use the provider "filter" to
1635 * identify subsets of items to delete---this makes most sense for
1636 * bulk operations (deleteDirectory, restoreAll, purgeAll), but all
1637 * of the deletion-related operations accept a "filter" argument.
1638 *
1639 *
1640 * Stores/providers that support contentID-based access can also
1641 * allow file items to be deleted by specifying their contentID.
1642 *
1643 */
1644
1645 procedure deleteFile(
1646 path in varchar2,
1647 filter in varchar2 default null,
1648 soft_delete in boolean default null,
1649 store_name in varchar2 default null,
1650 principal in varchar2 default null);
1651
1652 procedure deleteContent(
1653 store_name in varchar2,
1654 contentID in raw,
1655 filter in varchar2 default null,
1656 soft_delete in boolean default null,
1657 principal in varchar2 default null);
1658
1659 procedure deleteDirectory(
1660 path in varchar2,
1661 filter in varchar2 default null,
1662 soft_delete in boolean default null,
1663 recurse in boolean default false,
1664 store_name in varchar2 default null,
1665 principal in varchar2 default null);
1666
1667 procedure restorePath(
1668 path in varchar2,
1669 filter in varchar2 default null,
1670 store_name in varchar2 default null,
1671 principal in varchar2 default null);
1672
1673 procedure purgePath(
1674 path in varchar2,
1675 filter in varchar2 default null,
1676 store_name in varchar2 default null,
1677 principal in varchar2 default null);
1678
1679 procedure restoreAll(
1680 path in varchar2,
1684
1681 filter in varchar2 default null,
1682 store_name in varchar2 default null,
1683 principal in varchar2 default null);
1685 procedure purgeAll(
1686 path in varchar2,
1687 filter in varchar2 default null,
1688 store_name in varchar2 default null,
1689 principal in varchar2 default null);
1690
1691
1692
1693 /*
1694 * DBFS API: path get/put operations.
1695 *
1696 * Existing path items can be accessed (for query or for update) and
1697 * modified via simple get/put methods.
1698 *
1699 * All pathnames allow their metadata (i.e. properties) to be
1700 * read/modified. On completion of the call, the client can request
1701 * (via "prop_flags") specific properties to be fetched as well.
1702 *
1703 * File pathnames allow their data (i.e. content) to be
1704 * read/modified. On completion of the call, the client can request
1705 * (via the "prop_data" bitmaks in "prop_flags") a new BLOB locator
1706 * that can be used to continue data access.
1707 *
1708 * Files can also be read/written without using BLOB locators, by
1709 * explicitly specifying logical offsets/buffer-amounts and a
1710 * suitably sized buffer.
1711 *
1712 *
1713 * Update accesses must specify the "forUpdate" flag. Access to link
1714 * pathnames can be implicitly and internally deferenced by stores
1715 * (subject to feature support) if the "deref" flag is
1716 * specified---however, this is dangerous since symbolic links are
1717 * not always resolvable.
1718 *
1719 *
1720 * The read methods (i.e. "getPath" where "forUpdate" is "false"
1721 * also accepts a valid "asof" timestamp parameter that can be used
1722 * by stores to implement "as of" style flashback queries. Mutating
1723 * versions of the "getPath" and the "putPath" methods do not
1724 * support as-of modes of operation.
1725 *
1726 *
1727 * The DBFS API does not have an explicit copy operation since a
1728 * copy is easily implemented as a combination of a "getPath"
1729 * followed by a "createXXX" with appropriate data/metadata transfer
1730 * across the calls. This allows copies _across_ stores (while an
1731 * internalized copy operation cannot provide this facility).
1732 *
1733 *
1734 * "getPathNowait" implies a "forUpdate", and, if implemented (see
1735 * "feature_nowait"), allows providers to return an exception
1736 * (ORA-54) rather than wait for row locks.
1737 *
1738 */
1739
1740 procedure getPath(
1741 path in varchar2,
1742 properties in out nocopy dbms_dbfs_content_properties_t,
1743 content out nocopy blob,
1744 item_type out integer,
1745 prop_flags in integer default (prop_std +
1746 prop_opt +
1747 prop_data),
1748 asof in timestamp default null,
1749 forUpdate in boolean default false,
1750 deref in boolean default false,
1751 store_name in varchar2 default null,
1752 principal in varchar2 default null);
1753
1754 procedure getPath(
1755 path in varchar2,
1756 properties in out nocopy properties_t,
1757 content out nocopy blob,
1758 item_type out integer,
1759 prop_flags in integer default (prop_std +
1760 prop_opt +
1761 prop_data),
1762 asof in timestamp default null,
1763 forUpdate in boolean default false,
1764 deref in boolean default false,
1765 store_name in varchar2 default null,
1766 principal in varchar2 default null);
1767
1768 procedure getPathNowait(
1769 path in varchar2,
1770 properties in out nocopy dbms_dbfs_content_properties_t,
1771 content out nocopy blob,
1772 item_type out integer,
1773 prop_flags in integer default (prop_std +
1774 prop_opt +
1775 prop_data),
1776 deref in boolean default false,
1777 store_name in varchar2 default null,
1778 principal in varchar2 default null);
1779
1780 procedure getPathNowait(
1781 path in varchar2,
1782 properties in out nocopy properties_t,
1783 content out nocopy blob,
1784 item_type out integer,
1785 prop_flags in integer default (prop_std +
1786 prop_opt +
1787 prop_data),
1788 deref in boolean default false,
1792 procedure getPath(
1789 store_name in varchar2 default null,
1790 principal in varchar2 default null);
1791
1793 path in varchar2,
1794 properties in out nocopy dbms_dbfs_content_properties_t,
1795 amount in out number,
1796 offset in number,
1797 buffer out nocopy raw,
1798 prop_flags in integer default (prop_std +
1799 prop_opt),
1800 asof in timestamp default null,
1801 store_name in varchar2 default null,
1802 principal in varchar2 default null);
1803
1804 procedure getPath(
1805 path in varchar2,
1806 properties in out nocopy properties_t,
1807 amount in out number,
1808 offset in number,
1809 buffer out nocopy raw,
1810 prop_flags in integer default (prop_std +
1811 prop_opt),
1812 asof in timestamp default null,
1813 store_name in varchar2 default null,
1814 principal in varchar2 default null);
1815
1816 procedure getPath(
1817 path in varchar2,
1818 properties in out nocopy dbms_dbfs_content_properties_t,
1819 amount in out number,
1820 offset in number,
1821 buffers out nocopy dbms_dbfs_content_raw_t,
1822 prop_flags in integer default (prop_std +
1823 prop_opt),
1824 asof in timestamp default null,
1825 store_name in varchar2 default null,
1826 principal in varchar2 default null);
1827
1828 procedure getPath(
1829 path in varchar2,
1830 properties in out nocopy properties_t,
1831 amount in out number,
1832 offset in number,
1833 buffers out nocopy dbms_dbfs_content_raw_t,
1834 prop_flags in integer default (prop_std +
1835 prop_opt),
1836 asof in timestamp default null,
1837 store_name in varchar2 default null,
1838 principal in varchar2 default null);
1839
1840 procedure putPath(
1841 path in varchar2,
1842 properties in out nocopy dbms_dbfs_content_properties_t,
1843 content in out nocopy blob,
1844 item_type out integer,
1845 prop_flags in integer default (prop_std +
1846 prop_opt +
1847 prop_data),
1848 store_name in varchar2 default null,
1849 principal in varchar2 default null);
1850
1851 procedure putPath(
1852 path in varchar2,
1853 properties in out nocopy properties_t,
1854 content in out nocopy blob,
1855 item_type out integer,
1856 prop_flags in integer default (prop_std +
1857 prop_opt +
1858 prop_data),
1859 store_name in varchar2 default null,
1860 principal in varchar2 default null);
1861
1862 procedure putPath(
1863 path in varchar2,
1864 properties in out nocopy dbms_dbfs_content_properties_t,
1865 amount in number,
1866 offset in number,
1867 buffer in raw,
1868 prop_flags in integer default (prop_std +
1869 prop_opt),
1870 store_name in varchar2 default null,
1871 principal in varchar2 default null);
1872
1873 procedure putPath(
1874 path in varchar2,
1875 properties in out nocopy properties_t,
1876 amount in number,
1877 offset in number,
1878 buffer in raw,
1879 prop_flags in integer default (prop_std +
1880 prop_opt),
1881 store_name in varchar2 default null,
1882 principal in varchar2 default null);
1883
1884 procedure putPath(
1885 path in varchar2,
1886 properties in out nocopy dbms_dbfs_content_properties_t,
1887 written out number,
1888 offset in number,
1889 buffers in dbms_dbfs_content_raw_t,
1890 prop_flags in integer default (prop_std +
1891 prop_opt),
1892 store_name in varchar2 default null,
1893 principal in varchar2 default null);
1894
1898 written out number,
1895 procedure putPath(
1896 path in varchar2,
1897 properties in out nocopy properties_t,
1899 offset in number,
1900 buffers in dbms_dbfs_content_raw_t,
1901 prop_flags in integer default (prop_std +
1902 prop_opt),
1903 store_name in varchar2 default null,
1904 principal in varchar2 default null);
1905
1906
1907
1908 /*
1909 * DBFS API: rename/move operations.
1910 *
1911 * Pathnames can be renamed or moved, possibly across directory
1912 * hierarchies and mount-points, but within the same store.
1913 *
1914 *
1915 * Path renaming functions like the POSIX "rename" syscall while
1916 * path moving functions like the POSIX "mv" command.
1917 *
1918 *
1919 * The following table summarizes the behavior of "rename" and
1920 * "move".
1921 *
1922 * -------------------------------------------------------------------------------
1923 * operation oldPath newPath behavior
1924 * -------------------------------------------------------------------------------
1925 * rename non-directory self noop/success
1926 * rename non-directory non-existent rename/success
1927 * rename non-directory non-directory delete "newPath", rename
1928 * rename non-directory directory invalid_arguments exception
1929 *
1930 * rename directory self noop/success
1931 * rename directory non-existent rename/success
1932 * rename directory non-directory invalid_arguments exception
1933 * rename directory empty directory delete "newPath", rename
1934 * rename directory non-empty directory invalid_arguments exception
1935 * -------------------------------------------------------------------------------
1936 * move non-directory self noop/success
1937 * move non-directory non-existent rename/success
1938 * move non-directory non-directory delete "newPath", rename
1939 * move non-directory directory move "oldPath" into "newPath"
1940 * (delete existing non-directory, else invalid_arguments exception)
1941 *
1942 * move directory self noop/success
1943 * move directory non-existent rename/success
1944 * move directory non-directory invalid_arguments exception
1945 * move directory empty directory move "oldPath" into "newPath"
1946 * move directory non-empty directory move "oldPath" into "newPath"
1947 * (delete existing empty directory, else invalid_arguments exception)
1948 * -------------------------------------------------------------------------------
1949 *
1950 * Since the semantics of rename/move w.r.t. non-existent/existent
1951 * and non-directory/directory targets is complex, clients may
1952 * choose to implement complex renames and moves as a sequence of
1953 * simpler moves or copies.
1954 *
1955 *
1956 * Stores/providers that support contentID-based access and lazy
1957 * pathname binding also support the "setPath" method that
1958 * associates an existing "contentID" with a new "path".
1959 *
1960 */
1961
1962 procedure renamePath(
1963 oldPath in varchar2,
1964 newPath in varchar2,
1965 properties in out nocopy dbms_dbfs_content_properties_t,
1966 store_name in varchar2 default null,
1967 principal in varchar2 default null);
1968
1969 procedure renamePath(
1970 oldPath in varchar2,
1971 newPath in varchar2,
1972 properties in out nocopy properties_t,
1973 store_name in varchar2 default null,
1974 principal in varchar2 default null);
1975
1976 procedure movePath(
1977 oldPath in varchar2,
1978 newPath in varchar2,
1979 properties in out nocopy dbms_dbfs_content_properties_t,
1980 store_name in varchar2 default null,
1981 principal in varchar2 default null);
1982
1983 procedure movePath(
1984 oldPath in varchar2,
1985 newPath in varchar2,
1986 properties in out nocopy properties_t,
1987 store_name in varchar2 default null,
1988 principal in varchar2 default null);
1989
1990 procedure setPath(
1991 store_name in varchar2,
1992 contentID in raw,
1993 path in varchar2,
1994 properties in out nocopy dbms_dbfs_content_properties_t,
1995 principal in varchar2 default null);
1996
1997 procedure setPath(
1998 store_name in varchar2,
1999 contentID in raw,
2000 path in varchar2,
2001 properties in out nocopy properties_t,
2005
2002 principal in varchar2 default null);
2003
2004
2006 /*
2007 * Directory listings.
2008 *
2009 * A "path_item_t" is a tuple describing a (store, mount) qualified
2010 * path in a store, with all standard and optional properties
2011 * associated with it.
2012 *
2013 * A "prop_item_t" is a tuple describing a (store, mount) qualified
2014 * path in a store, with all user-defined properties associated with
2015 * it, expanded out into individual (name, value, type) tuples.
2016 *
2017 */
2018
2019 type path_item_t is record (
2020 store name_t,
2021 mount name_t,
2022 pathname path_t,
2023 pathtype varchar2(32),
2024 filedata blob,
2025 std_access_time timestamp,
2026 std_acl varchar2(1024),
2027 std_change_time timestamp,
2028 std_children number,
2029 std_content_type varchar2(1024),
2030 std_creation_time timestamp,
2031 std_deleted integer,
2032 std_guid integer,
2033 std_modification_time timestamp,
2034 std_owner varchar2(32),
2035 std_parent_guid integer,
2036 std_referent varchar2(1024),
2037 opt_hash_type varchar2(32),
2038 opt_hash_value varchar2(128),
2039 opt_lock_count integer,
2040 opt_lock_data varchar2(128),
2041 opt_locker varchar2(128),
2042 opt_lock_status integer,
2043 opt_version integer,
2044 opt_version_path path_t,
2045 opt_content_id content_id_t
2046 );
2047 type path_items_t is table of path_item_t;
2048
2049 type prop_item_t is record (
2050 store name_t,
2051 mount name_t,
2052 pathname path_t,
2053 property_name propname_t,
2054 property_value propval_t,
2055 property_type integer
2056 );
2057 type prop_items_t is table of prop_item_t;
2058
2059
2060
2061 /*
2062 * DBFS API: directory navigation and search.
2063 *
2064 * Clients of the DBFS API can list or search the contents of
2065 * directory pathnames, optionally recursing into sub-directories,
2066 * optionally seeing soft-deleted items, optionally using flashback
2067 * "as of" a provided timestamp, and optionally filtering items
2068 * in/out within the store based on list/search predicates.
2069 *
2070 * The DBFS API currently returns only list items; the client is
2071 * expected to explicitly use one of the "getPath" methods to access
2072 * the properties or content associated with an item, as
2073 * appropriate.
2074 *
2075 *
2076 * "listCursor" is a highly specialized directory enumerator that is
2077 * meant for use with "dbms_fuse" and "dbfs_client" as callers, and
2078 * with "dbms_dbfs_sfs.listCursor" as the callee.
2079 *
2080 * Other users are not expected to invoke this method, and other
2081 * providers are not expected to implement this method (dbms_fuse
2082 * can compensate for this by falling back to using the generic
2083 * "list()" method).
2084 *
2085 */
2086
2087 function list(
2088 path in varchar2,
2089 filter in varchar2 default null,
2090 recurse in integer default 0,
2091 asof in timestamp default null,
2092 store_name in varchar2 default null,
2093 principal in varchar2 default null)
2094 return dbms_dbfs_content_list_items_t
2095 pipelined;
2096
2097 function listCursor(
2098 path in varchar2,
2099 withProps in integer default 0,
2100 doSort in integer default 0,
2101 doFts in integer default 0,
2102 doBulk in integer default 0)
2103 return integer;
2104
2105 function search(
2106 path in varchar2,
2107 filter in varchar2 default null,
2108 recurse in integer default 0,
2109 asof in timestamp default null,
2110 store_name in varchar2 default null,
2111 principal in varchar2 default null)
2112 return dbms_dbfs_content_list_items_t
2113 pipelined;
2114
2115
2116
2117 /*
2118 * DBFS API: locking operations.
2119 *
2120 * Clients of the DBFS API can apply user-level locks to any valid
2121 * pathname (subject to store feature support), associate the lock
2122 * with user-data, and subsequently unlock these pathnames.
2123 *
2124 * The status of locked items is available via various optional
2125 * properties (see "opt_lock*" above).
2126 *
2127 *
2128 * It is the responsibility of the store (assuming it supports
2132 */
2129 * user-defined lock checking) to ensure that lock/unlock operations
2130 * are performed in a consistent manner.
2131 *
2133
2134 procedure lockPath(
2135 path in varchar2,
2136 lock_type in integer default lock_read_only,
2137 lock_data in varchar2 default null,
2138 store_name in varchar2 default null,
2139 principal in varchar2 default null);
2140
2141 procedure unlockPath(
2142 path in varchar2,
2143 store_name in varchar2 default null,
2144 principal in varchar2 default null);
2145
2146
2147
2148 /*
2149 * DBFS API: abstract operations.
2150 *
2151 * All of the operations in the DBFS API are represented as abstract
2152 * opcodes.
2153 *
2154 * Clients can use these opcodes to directly and explicitly invoke
2155 * the "checkAccess" method (see below) to verify if a particular
2156 * operation can be invoked by a given principal on a particular
2157 * pathname.
2158 *
2159 *
2160 * All of the operations listed below should have an obvious
2161 * meaning, with the following clarifications.
2162 *
2163 * An "op_acl" is an implicit operation invoked during an
2164 * "op_create" or "op_put" that specifies a "std_acl" property---the
2165 * operation tests to see if the principal is allowed to set or
2166 * change the ACL of a store item.
2167 *
2168 * Soft-deletion, purge, and restore operations are all represented
2169 * by "op_delete".
2170 *
2171 * The source and destination operations of a rename/move are
2172 * separated out, although stores are free to unify these opcodes
2173 * (and to also treat a rename as a combination of delete+create).
2174 *
2175 * "op_store" is a catch-all category for miscellaneous store
2176 * operations that do not fall under any of the other operational
2177 * APIs.
2178 *
2179 */
2180
2181 op_create constant pls_integer := 1;
2182 op_createFile constant pls_integer := op_create;
2183 op_createLink constant pls_integer := op_create;
2184 op_createReference constant pls_integer := op_create;
2185 op_createDirectory constant pls_integer := op_create;
2186
2187 op_delete constant pls_integer := 2;
2188 op_deleteFile constant pls_integer := op_delete;
2189 op_deleteDirectory constant pls_integer := op_delete;
2190 op_restore constant pls_integer := op_delete;
2191 op_purge constant pls_integer := op_delete;
2192
2193 op_read constant pls_integer := 3;
2194 op_get constant pls_integer := op_read;
2195
2196 op_write constant pls_integer := 4;
2197 op_put constant pls_integer := op_write;
2198
2199 op_rename constant pls_integer := 5;
2200 op_renameFrom constant pls_integer := op_rename;
2201 op_renameTo constant pls_integer := op_rename;
2202 op_move constant pls_integer := 6;
2203 op_moveFrom constant pls_integer := op_move;
2204 op_moveTo constant pls_integer := op_move;
2205 op_setPath constant pls_integer := 7;
2206
2207 op_list constant pls_integer := 8;
2208 op_search constant pls_integer := 9;
2209
2210 op_lock constant pls_integer := 10;
2211 op_unlock constant pls_integer := 11;
2212
2213 op_acl constant pls_integer := 12;
2214 op_store constant pls_integer := 13;
2215
2216
2217
2218 /*
2219 * DBFS API: access checks.
2220 *
2221 * Check if a given pathname (path, pathtype, store_name) can be
2222 * manipulated by "operation (see the various "op_xxx" opcode above)
2223 * by "principal".
2224 *
2225 * This is a convenience function for the client; a store that
2226 * supports access control still internally performs these checks to
2227 * guarantee security.
2228 *
2229 */
2230
2231 function checkAccess(
2232 path in varchar2,
2233 pathtype in integer,
2234 operation in varchar2,
2235 principal in varchar2,
2236 store_name in varchar2 default null)
2237 return boolean;
2238
2239
2240
2241 /*
2242 * DBFS API: path normalization.
2243 *
2244 * Convert a store-specific or full-absolute pathname into
2245 * normalized form:
2246 *
2247 * -> verifies that the pathname is absolute, i.e. starts with a
2248 * "/".
2249 *
2250 * -> collapses multiple consecutive "/" into a single "/".
2251 *
2252 * -> strips trailing "/".
2253 *
2254 * -> breaks up a store-specific normalized pathname into 2
2255 * components: (parent pathname, trailing component name).
2256 *
2257 * -> breaks up a full-absolute normalized pathname into 3
2261 * The root path "/" is special: its parent pathname is also "/",
2258 * components: (store name, parent pathname, trailing component
2259 * name).
2260 *
2262 * and its component name is "null", and, in full-absolute mode, has
2263 * a "null" store name (unless a singleton mount has been created,
2264 * in which name the appropriate store name is returned).
2265 *
2266 *
2267 * The return value is always the completely normalized
2268 * store-specific or full-absolute pathname.
2269 *
2270 */
2271
2272 function normalizePath(
2273 path in varchar2,
2274 parent out nocopy varchar2,
2275 tpath out nocopy varchar2)
2276 return varchar2;
2277
2278 function normalizePath(
2279 path in varchar2,
2280 store_name out nocopy varchar2,
2281 parent out nocopy varchar2,
2282 tpath out nocopy varchar2)
2283 return varchar2;
2284
2285 function normalizePath(
2286 path in varchar2,
2287 forWrite in integer,
2288 store_name out nocopy varchar2,
2289 parent out nocopy varchar2,
2290 tpath out nocopy varchar2,
2291 provider out nocopy varchar2,
2292 ctx out nocopy dbms_dbfs_content_context_t)
2293 return varchar2;
2294
2295
2296
2297 /*
2298 * DBFS API: statistics support.
2299 *
2300 * Enable or disable DBFS API statistics.
2301 *
2302 * DBFS API statistics are expensive to collect and maintain
2303 * persistently. The implementation has support for buffering
2304 * statistics in-memory for a maximum of "flush_time" centiseconds
2305 * and/or a maximum of "flush_count" operations (whichever limit is
2306 * reached first), at which time the buffers are implicitly flushed
2307 * to disk.
2308 *
2309 * Clients can also explicitly invoke a flush via "flushStats". An
2310 * implicit flush also occurs when statistics collection is
2311 * disabled.
2312 *
2313 * "setStats" is used to enable/disable statisics collection; the
2314 * client can optionally control the flush settings (by specifying
2315 * non-null values for the time and/or count parameters).
2316 *
2317 */
2318
2319 procedure getStats(
2320 enabled out boolean,
2321 flush_time out integer,
2322 flush_count out integer);
2323
2324 procedure setStats(
2325 enable in boolean,
2326 flush_time in integer default null,
2327 flush_count in integer default null);
2328
2329 procedure flushStats;
2330
2331
2332
2333 /*
2334 * DBFS API: tracing support.
2335 *
2336 * Enable or disable DBFS API tracing.
2337 *
2338 * This is a generic tracing facility that can be used by any DBFS
2339 * API user (i.e. both clients and providers). The DBFS API
2340 * dispatcher itself uses the tracing facility.
2341 *
2342 * Trace information is written to the foreground tracefile, with
2343 * varying levels of detail as specified by the trace
2344 * level/arguments.
2345 *
2346 *
2347 * The global trace level consists of 2 components: "severity" and
2348 * "detail". These can be thought of as additive bitmasks.
2349 *
2350 * The "severity" allows the separation of toplevel vs. low-level
2351 * tracing of different components, and allows the amount of tracing
2352 * to be increased as needed. There are no semantics associated with
2353 * different levels, and users are free to set/trace at any severity
2354 * they choose, although a good rule of thumb would use severity "1"
2355 * for toplevel API entry/exit traces, "2" for internal operations,
2356 * and "3" or greater for very low-level traces.
2357 *
2358 * The "detail" controls how much additional information:
2359 * timestamps, short-stack, etc. is dumped along with each trace
2360 * record.
2361 *
2362 */
2363
2364 function getTrace
2365 return integer;
2366
2367 procedure setTrace(
2368 trclvl in integer);
2369
2370 function traceEnabled(
2371 sev in integer)
2372 return integer;
2373
2374 procedure trace(
2375 sev in integer,
2376 msg0 in varchar2,
2377 msg1 in varchar default '',
2378 msg2 in varchar default '',
2379 msg3 in varchar default '',
2380 msg4 in varchar default '',
2381 msg5 in varchar default '',
2382 msg6 in varchar default '',
2383 msg7 in varchar default '',
2384 msg8 in varchar default '',
2385 msg9 in varchar default '',
2386 msg10 in varchar default '');
2387
2388
2389
2390 /*
2394
2391 * Content/property view support.
2392 *
2393 */
2395 function listAllContent
2396 return path_items_t
2397 pipelined;
2398
2399 function listAllProperties
2400 return prop_items_t
2401 pipelined;
2402
2403
2404
2405 /*
2406 * Utility function: check SPI.
2407 *
2408 *
2409 * Given the name of a putative "dbms_dbfs_content_spi" conforming
2410 * package, attempt to check that the package really does implement
2411 * all of the provider methods (with the proper signatures), and
2412 * report on the conformance.
2413 *
2414 * The functional form returns a (cache) temporary lob (of session
2415 * duration) with the results of the analysis. The caller is
2416 * expected to manage the lifetime of this lob, as needed.
2417 *
2418 * The procedural form generates the results of the analysis into
2419 * the "chk" lob parameter (if the value passed in is "null", the
2420 * results are written to the foreground tracefile if DBFS API
2421 * tracing is enabled). If neither tracing is enabled nor a valid
2422 * lob passed in, the checker does not provide any useful indication
2423 * of the analysis (other than raise exceptions if it encounters a
2424 * serious error).
2425 *
2426 * If "schema_name" is "null", standard name resolution rules
2427 * (current schema, private synonym, public synonym) are used to try
2428 * and locate a suitable package to analyze.
2429 *
2430 * This is a helper wrapper around
2431 * "dbms_dbfs_content_admin.checkSpi()".
2432 *
2433 */
2434
2435 function checkSpi(
2436 package_name in varchar2)
2437 return clob;
2438
2439 function checkSpi(
2440 schema_name in varchar2,
2441 package_name in varchar2)
2442 return clob;
2443
2444 procedure checkSpi(
2445 package_name in varchar2,
2446 chk in out nocopy clob);
2447
2448 procedure checkSpi(
2449 schema_name in varchar2,
2450 package_name in varchar2,
2451 chk in out nocopy clob);
2452
2453
2454
2455 /*
2456 * Fastpath lookup acceleration view.
2457 *
2458 * For a given path, return the (optional) path prefix and view_name
2459 * that may be used to directly query the "getattr" values.
2460 *
2461 * For example, if "path" is of the form "/a/b/c", and the return
2462 * values are "a" (prefix) and "v" (view_name), it should be
2463 * possible to query view "v" with column "pathname" bound to values
2464 * like "/b/c" or "/e" or "/f/g".
2465 *
2466 * Paths on singleton mounts would return a null (prefix) and a
2467 * view_name, and the client must not strip out any leading
2468 * components of the path when querying the view.
2469 *
2470 * The procedure can raise exceptions under various circumstances:
2471 *
2472 * . No stores are currently mounted (invalid_path).
2473 * . A "/" path is used for non-singleton mounts (invalid_path).
2474 * . The underlying provider does not support lookup views
2475 * (unsupported_operation).
2476 *
2477 * The view name returned by this procedure can become invalid or
2478 * disappear at any time becaue of a change in the DBFS state.
2479 * Clients must treat errors during view access as a signal to
2480 * refresh their own state (perhaps, re-invoking this method to
2481 * figure out the new view names, etc.) before proceeding, or else
2482 * fall back to using standard DBFS methods for their lookup
2483 * operations.
2484 *
2485 *
2486 * Also note that the getattr view need not (and will most likely
2487 * not) return pseudo-filesystem entries like "." and ".."---it is
2488 * up to the client to regenerate entries of this form if needed
2489 * (for example, if the getattr view is used to generate
2490 * full/partial recursive filesystem listings instead of point
2491 * lookups).
2492 *
2493 */
2494
2495 procedure getattr_view(
2496 path in varchar2,
2497 prefix out nocopy varchar2,
2498 view_name out nocopy varchar2);
2499
2500
2501
2502 end;
[Home] [Help]