1 package dbms_dbfs_content_spi
2 authid definer
3 as
4
5
6
7 /*
8 * Lookup store features (see dbms_dbfs_content.feature_XXX). Lookup
9 * store id.
10 *
11 * A store ID identifies a provider-specific store, across
12 * registrations and mounts, but independent of changes to the store
13 * contents.
14 *
15 * I.e. changes to the store table(s) should be reflected in the
16 * store ID, but re-initialization of the same store table(s) should
17 * preserve the store ID.
18 *
19 * Providers should also return a "version" (either specific to a
20 * provider package, or to an individual store) based on a standard
21 * <a.b.c> naming convention (for <major>, <minor>, and <patch>
22 * components).
23 *
24 */
25
26 function getFeatures(
27 store_name in varchar2)
28 return integer;
29
30 function getStoreId(
31 store_name in varchar2)
32 return number;
33
34 function getVersion(
35 store_name in varchar2)
36 return varchar2;
37
38
39
40 /*
41 * Lookup pathnames by (store_name, std_guid) or (store_mount,
42 * std_guid) tuples.
43 *
44 * If the underlying "std_guid" is found in the underlying store,
45 * this function returns the store-qualified pathname.
46 *
47 * If the "std_guid" is unknown, a "null" value is returned. Clients
48 * are expected to handle this as appropriate.
49 *
50 */
51
52 function getPathByStoreId(
53 store_name in varchar2,
54 guid in integer)
55 return varchar2;
56
57
58
59 /*
60 * DBFS SPI: space usage.
61 *
62 * Clients can query filesystem space usage statistics via the
63 * "spaceUsage()" method. Store providers, in turn, are expected to
64 * support at least the "spaceUsage()" method for their stores (and
65 * to make a best effort determination of space usage---esp. if the
66 * store consists of multiple tables/indexes/lobs, etc. scattered
67 * across multiple tablespaces/datafiles/disk-groups, etc.).
68 *
69 * See "dbms_dbfs_content_spi" for more details on the
70 * DBFS-API/provider-SPI contract.
71 *
72 *
73 * "blksize" is the natural tablespace blocksize that holds the
74 * store---if multiple tablespaces with different blocksizes are
75 * used, any valid blocksize is acceptable.
76 *
77 * "tbytes" is the total size of the store in bytes, and "fbytes" is
78 * the free/unused size of the store in bytes. These values are
79 * computed over all segments that comprise the store.
80 *
81 * "nfile", "ndir", "nlink", and "nref" count the number of
82 * currently available files, directories, links, and references in
83 * the store.
84 *
85 * Since database objects are dynamically growable, it is not easy
86 * to estimate the division between "free" space and "used" space.
87 *
88 *
89 * The SPI has 2 space usage methods: "spaceUsage()" and
90 * "spaceUsageFull()". The difference between the two is that the
91 * latter function should implement a "bulk" API---i.e. the ability
92 * to query and aggregate space usage information for all stores
93 * specified as the "propvalue" fields of the "store_names" property
94 * list (the other fields of the property list can be ignored).
95 *
96 * If the SPI does not support the "bulk" aggregation API, the DBFS
97 * API will itself do the necessary iteration and aggregation,
98 * however, at the risk of inaccurate data due to potential
99 * double-counting.
100 *
101 *
102 * In all cases, the DBFS API will invoke the SPI's space usage
103 * functions with only those stores that are managed by the provider
104 * package.
105 *
106 *
107 * If "useEstimate" is specified, providers capable of computing
108 * fast-but-approximate space usage information can make use of this
109 * optimization. Otherwise, the default space usage computation will
110 * be used.
111 *
112 */
113
114 procedure spaceUsage(
115 store_name in varchar2,
116 blksize out integer,
117 tbytes out integer,
118 fbytes out integer,
119 nfile out integer,
120 ndir out integer,
121 nlink out integer,
122 nref out integer);
123
124 procedure spaceUsage(
125 store_name in varchar2,
126 blksize out integer,
127 tbytes out integer,
128 fbytes out integer,
129 nfile out integer,
130 ndir out integer,
131 nlink out integer,
132 nref out integer,
133 useEstimate in integer);
134
135 procedure spaceUsageFull(
136 store_names in dbms_dbfs_content_properties_t,
137 blksize out integer,
138 tbytes out integer,
139 fbytes out integer,
140 nfile out integer,
141 ndir out integer,
142 nlink out integer,
143 nref out integer);
144
145 procedure spaceUsageFull(
146 store_names in dbms_dbfs_content_properties_t,
147 blksize out integer,
148 tbytes out integer,
149 fbytes out integer,
150 nfile out integer,
151 ndir out integer,
152 nlink out integer,
153 nref out integer,
154 useEstimate in integer);
155
156
157
158 /*
159 * Fastpath lookup view support.
160 *
161 * Providers that are willing/able to create a fastpath lookup view
162 * (whose structure conforms to the schema of
163 * "dbms_fuse.dir_entry_t") should define "createGetattrView()" and
164 * "dropGetattrView()" methods, and create/drop the underlying view
165 * as needed.
166 *
167 * The view name should be returned to the caller. The provider is
168 * free to invalidate or drop the view at any time, even without
169 * explicit request, based on its own state.
170 *
171 */
172
173 procedure createGetattrView(
174 store_name in varchar2,
175 ctx in dbms_dbfs_content_context_t,
176 view_name out nocopy varchar2);
177
178 procedure dropGetattrView(
179 store_name in varchar2,
180 view_name out nocopy varchar2);
181
182
183
184 /*
185 * DBFS SPI: notes on pathnames.
186 *
187 * All pathnames used in the SPI are store-qualified, i.e. a 2-tuple
188 * of the form (store_name, pathname) (where the pathname is rooted
189 * within the store namespace).
190 *
191 *
192 * Stores/providers that support contentID-based access (see
193 * "feature_content_id") also support a form of addressing that is
194 * not based on pathnames. Items are identified by an explicit store
195 * name, a "null" pathname, and possibly a contentID specified as a
196 * parameter or via the "opt_content_id" property.
197 *
198 * Not all operations are supported with contentID-based access, and
199 * applications should depend only on the simplest create/delete
200 * functionality being available.
201 *
202 */
203
204
205
206 /*
207 * DBFS SPI: creation operations
208 *
209 * The SPI must allow the DBFS API to create directory, file, link,
210 * and reference elements (subject to store feature support).
211 *
212 *
213 * All of the creation methods require a valid pathname (see the
214 * special exemption for contentID-based access below), and can
215 * optionally specify properties to be associated with the pathname
216 * as it is created. It is also possible for clients to fetch-back
217 * item properties after the creation completes (so that
218 * automatically generated properties (e.g. "std_creation_time") are
219 * immediately available to clients (the exact set of properties
220 * fetched back is controlled by the various "prop_xxx" bitmasks in
221 * "prop_flags").
222 *
223 *
224 * Links and references require an additional pathname to associate
225 * with the primary pathname.
226 *
227 * File pathnames can optionally specify a BLOB value to use to
228 * initially populate the underlying file content (the provided BLOB
229 * may be any valid lob: temporary or permanent). On creation, the
230 * underlying lob is returned to the client (if "prop_data" is
231 * specified in "prop_flags").
232 *
233 * Non-directory pathnames require that their parent directory be
234 * created first. Directory pathnames themselves can be recursively
235 * created (i.e. the pathname hierarchy leading up to a directory
236 * can be created in one call).
237 *
238 *
239 * Attempts to create paths that already exist is an error; the one
240 * exception is pathnames that are "soft-deleted" (see below for
241 * delete operations)---in these cases, the soft-deleted item is
242 * implicitly purged, and the new item creation is attempted.
243 *
244 *
245 * Stores/providers that support contentID-based access accept an
246 * explicit store name and a "null" path to create a new element.
247 * The contentID generated for this element is available via the
248 * "opt_content_id" property (contentID-based creation automatically
249 * implies "prop_opt" in "prop_flags").
250 *
251 * The newly created element may also have an internally generated
252 * pathname (if "feature_lazy_path" is not supported) and this path
253 * is available via the "std_canonical_path" property.
254 *
255 * Only file elements are candidates for contentID-based access.
256 *
257 */
258
259 procedure createFile(
260 store_name in varchar2,
261 path in varchar2,
262 properties in out nocopy dbms_dbfs_content_properties_t,
263 content in out nocopy blob,
264 prop_flags in integer,
265 ctx in dbms_dbfs_content_context_t);
266
267 procedure createLink(
268 store_name in varchar2,
269 srcPath in varchar2,
270 dstPath in varchar2,
271 properties in out nocopy dbms_dbfs_content_properties_t,
272 prop_flags in integer,
273 ctx in dbms_dbfs_content_context_t);
274
275 procedure createReference(
276 store_name in varchar2,
277 srcPath in varchar2,
278 dstPath in varchar2,
279 properties in out nocopy dbms_dbfs_content_properties_t,
280 prop_flags in integer,
281 ctx in dbms_dbfs_content_context_t);
282
283 procedure createDirectory(
284 store_name in varchar2,
285 path in varchar2,
286 properties in out nocopy dbms_dbfs_content_properties_t,
287 prop_flags in integer,
288 recurse in integer,
289 ctx in dbms_dbfs_content_context_t);
290
291
292
293 /*
294 * DBFS SPI: deletion operations
295 *
296 * The SPI must allow the DBFS API to delete directory, file, link,
297 * and reference elements (subject to store feature support).
298 *
299 *
300 * By default, the deletions are "permanent" (get rid of the
301 * successfully deleted items on transaction commit), but stores may
302 * also support "soft-delete" features. If requested by the client,
303 * soft-deleted items are retained by the store (but not typically
304 * visible in normal listings or searches).
305 *
306 * Soft-deleted items can be "restore"d, or explicitly purged.
307 *
308 *
309 * Directory pathnames can be recursively deleted (i.e. the pathname
310 * hierarchy below a directory can be deleted in one call).
311 * Non-recursive deletions can be performed only on empty
312 * directories. Recursive soft-deletions apply the soft-delete to
313 * all of the items being deleted.
314 *
315 *
316 * Individual pathnames (or all soft-deleted pathnames under a
317 * directory) can be restored or purged via the restore and purge
318 * methods.
319 *
320 *
321 * Providers that support filtering can use the provider "filter" to
322 * identify subsets of items to delete---this makes most sense for
323 * bulk operations (deleteDirectory, restoreAll, purgeAll), but all
324 * of the deletion-related operations accept a "filter" argument.
325 *
326 *
327 * Stores/providers that support contentID-based access can also
328 * allow file items to be deleted by specifying their contentID.
329 *
330 */
331
332 procedure deleteFile(
333 store_name in varchar2,
334 path in varchar2,
335 filter in varchar2,
336 soft_delete in integer,
337 ctx in dbms_dbfs_content_context_t);
338
339 procedure deleteContent(
340 store_name in varchar2,
341 contentID in raw,
342 filter in varchar2,
343 soft_delete in integer,
344 ctx in dbms_dbfs_content_context_t);
345
346 procedure deleteDirectory(
347 store_name in varchar2,
348 path in varchar2,
349 filter in varchar2,
350 soft_delete in integer,
351 recurse in integer,
352 ctx in dbms_dbfs_content_context_t);
353
354 procedure restorePath(
355 store_name in varchar2,
356 path in varchar2,
357 filter in varchar2,
358 ctx in dbms_dbfs_content_context_t);
359
360 procedure purgePath(
361 store_name in varchar2,
362 path in varchar2,
363 filter in varchar2,
364 ctx in dbms_dbfs_content_context_t);
365
366 procedure restoreAll(
367 store_name in varchar2,
368 path in varchar2,
369 filter in varchar2,
370 ctx in dbms_dbfs_content_context_t);
371
372 procedure purgeAll(
373 store_name in varchar2,
374 path in varchar2,
375 filter in varchar2,
376 ctx in dbms_dbfs_content_context_t);
377
378
379
380 /*
381 * DBFS SPI: path get/put operations.
382 *
383 * Existing path items can be accessed (for query or for update) and
384 * modified via simple get/put methods.
385 *
389 *
386 * All pathnames allow their metadata (i.e. properties) to be
387 * read/modified. On completion of the call, the client can request
388 * (via "prop_flags") specific properties to be fetched as well.
390 * File pathnames allow their data (i.e. content) to be
391 * read/modified. On completion of the call, the client can request
392 * (via the "prop_data" bitmaks in "prop_flags") a new BLOB locator
393 * that can be used to continue data access.
394 *
395 * Files can also be read/written without using BLOB locators, by
396 * explicitly specifying logical offsets/buffer-amounts and a
397 * suitably sized buffer.
398 *
399 *
400 * Update accesses must specify the "forUpdate" flag. Access to link
401 * pathnames can be implicitly and internally deferenced by stores
402 * (subject to feature support) if the "deref" flag is
403 * specified---however, this is dangerous since symbolic links are
404 * not always resolvable.
405 *
406 *
407 * The read methods (i.e. "getPath" where "forUpdate" is "false"
408 * also accepts a valid "asof" timestamp parameter that can be used
409 * by stores to implement "as of" style flashback queries. Mutating
410 * versions of the "getPath" and the "putPath" methods do not
411 * support as-of modes of operation.
412 *
413 *
414 * "getPathNowait" implies a "forUpdate", and, if implemented (see
415 * "feature_nowait"), allows providers to return an exception
416 * (ORA-54) rather than wait for row locks.
417 *
418 */
419
420 procedure getPath(
421 store_name in varchar2,
422 path in varchar2,
423 properties in out nocopy dbms_dbfs_content_properties_t,
424 content out nocopy blob,
425 item_type out integer,
426 prop_flags in integer,
427 forUpdate in integer,
428 deref in integer,
429 ctx in dbms_dbfs_content_context_t);
430
431 procedure getPathNowait(
432 store_name in varchar2,
433 path in varchar2,
434 properties in out nocopy dbms_dbfs_content_properties_t,
435 content out nocopy blob,
436 item_type out integer,
437 prop_flags in integer,
438 deref in integer,
439 ctx in dbms_dbfs_content_context_t);
440
441 procedure getPath(
442 store_name in varchar2,
443 path in varchar2,
444 properties in out nocopy dbms_dbfs_content_properties_t,
445 amount in out number,
446 offset in number,
447 buffer out nocopy raw,
448 prop_flags in integer,
449 ctx in dbms_dbfs_content_context_t);
450
451 procedure getPath(
452 store_name in varchar2,
453 path in varchar2,
454 properties in out nocopy dbms_dbfs_content_properties_t,
455 amount in out number,
456 offset in number,
457 buffers out nocopy dbms_dbfs_content_raw_t,
458 prop_flags in integer,
459 ctx in dbms_dbfs_content_context_t);
460
461 procedure putPath(
462 store_name in varchar2,
463 path in varchar2,
464 properties in out nocopy dbms_dbfs_content_properties_t,
465 content in out nocopy blob,
466 item_type out integer,
467 prop_flags in integer,
468 ctx in dbms_dbfs_content_context_t);
469
470 procedure putPath(
471 store_name in varchar2,
472 path in varchar2,
473 properties in out nocopy dbms_dbfs_content_properties_t,
474 amount in number,
475 offset in number,
476 buffer in raw,
477 prop_flags in integer,
478 ctx in dbms_dbfs_content_context_t);
479
480 procedure putPath(
481 store_name in varchar2,
482 path in varchar2,
483 properties in out nocopy dbms_dbfs_content_properties_t,
484 written out number,
485 offset in number,
486 buffers in dbms_dbfs_content_raw_t,
487 prop_flags in integer,
488 ctx in dbms_dbfs_content_context_t);
489
490
491
492 /*
493 * DBFS SPI: rename/move operations.
494 *
495 * Pathnames can be renamed or moved, possibly across directory
496 * hierarchies and mount-points, but within the same store.
497 *
498 *
499 * Path renaming functions like the POSIX "rename" syscall while
500 * path moving functions like the POSIX "mv" command.
501 *
502 *
503 * The following table summarizes the behavior of "rename" and
504 * "move".
505 *
509 * rename non-directory self noop/success
506 * -------------------------------------------------------------------------------
507 * operation oldPath newPath behavior
508 * -------------------------------------------------------------------------------
510 * rename non-directory non-existent rename/success
511 * rename non-directory non-directory delete "newPath", rename
512 * rename non-directory directory invalid_arguments exception
513 *
514 * rename directory self noop/success
515 * rename directory non-existent rename/success
516 * rename directory non-directory invalid_arguments exception
517 * rename directory empty directory delete "newPath", rename
518 * rename directory non-empty directory invalid_arguments exception
519 * -------------------------------------------------------------------------------
520 * move non-directory self noop/success
521 * move non-directory non-existent rename/success
522 * move non-directory non-directory delete "newPath", rename
523 * move non-directory directory move "oldPath" into "newPath"
524 * (delete existing non-directory, else invalid_arguments exception)
525 *
526 * move directory self noop/success
527 * move directory non-existent rename/success
528 * move directory non-directory invalid_arguments exception
529 * move directory empty directory move "oldPath" into "newPath"
530 * move directory non-empty directory move "oldPath" into "newPath"
531 * (delete existing empty directory, else invalid_arguments exception)
532 * -------------------------------------------------------------------------------
533 *
534 * Since the semantics of rename/move w.r.t. non-existent/existent
535 * and non-directory/directory targets is complex, clients may
536 * choose to implement complex renames and moves as a sequence of
537 * simpler moves or copies.
538 *
539 *
540 * Stores/providers that support contentID-based access and lazy
541 * pathname binding also support the "setPath" method that
542 * associates an existing "contentID" with a new "path".
543 *
544 */
545
546 procedure renamePath(
547 store_name in varchar2,
548 oldPath in varchar2,
549 newPath in varchar2,
550 properties in out nocopy dbms_dbfs_content_properties_t,
551 ctx in dbms_dbfs_content_context_t);
552
553 procedure movePath(
554 store_name in varchar2,
555 oldPath in varchar2,
556 newPath in varchar2,
557 properties in out nocopy dbms_dbfs_content_properties_t,
558 ctx in dbms_dbfs_content_context_t);
559
560 procedure setPath(
561 store_name in varchar2,
562 contentID in raw,
563 path in varchar2,
564 properties in out nocopy dbms_dbfs_content_properties_t,
565 ctx in dbms_dbfs_content_context_t);
566
567
568
569 /*
570 * DBFS SPI: directory navigation and search.
571 *
572 * The DBFS API can list or search the contents of directory
573 * pathnames, optionally recursing into sub-directories, optionally
574 * seeing soft-deleted items, optionally using flashback "as of" a
575 * provided timestamp, and optionally filtering items in/out within
576 * the store based on list/search predicates.
577 *
578 *
579 * "listCursor" is a highly specialized directory enumerator that is
580 * meant for use with "dbms_fuse" and "dbfs_client" as the ultimate
581 * callers, and with "dbms_dbfs_sfs.listCursor" as the callee.
582 *
583 * Other providers are not expected to implement this method
584 * (dbms_fuse can compensate for this by falling back to using the
585 * generic "list()" method).
586 *
587 */
588
589 function list(
590 store_name in varchar2,
591 path in varchar2,
592 filter in varchar2,
593 recurse in integer,
594 ctx in dbms_dbfs_content_context_t)
595 return dbms_dbfs_content_list_items_t
596 pipelined;
597
598 function listCursor(
599 store_name in varchar2,
600 mnt_prefix in varchar2,
601 path in varchar2,
602 withProps in integer,
603 doSort in integer,
604 doFts in integer,
605 doBulk in integer,
606 ctx in dbms_dbfs_content_context_t)
607 return integer;
608
609 function search(
610 store_name in varchar2,
611 path in varchar2,
612 filter in varchar2,
616 pipelined;
613 recurse in integer,
614 ctx in dbms_dbfs_content_context_t)
615 return dbms_dbfs_content_list_items_t
617
618
619
620 /*
621 * DBFS SPI: locking operations.
622 *
623 * Clients of the DBFS API can apply user-level locks to any valid
624 * pathname (subject to store feature support), associate the lock
625 * with user-data, and subsequently unlock these pathnames.
626 *
627 * The status of locked items is available via various optional
628 * properties (see "opt_lock*" above).
629 *
630 *
631 * It is the responsibility of the store (assuming it supports
632 * user-defined lock checking) to ensure that lock/unlock operations
633 * are performed in a consistent manner.
634 *
635 */
636
637 procedure lockPath(
638 store_name in varchar2,
639 path in varchar2,
640 lock_type in integer,
641 lock_data in varchar2,
642 ctx in dbms_dbfs_content_context_t);
643
644 procedure unlockPath(
645 store_name in varchar2,
646 path in varchar2,
647 ctx in dbms_dbfs_content_context_t);
648
649
650
651 /*
652 * DBFS SPI: access checks.
653 *
654 * Check if a given pathname (store_name, path, pathtype) can be
655 * manipulated by "operation (see the various
656 * "dbms_dbfs_content.op_xxx" opcodes) by "principal".
657 *
658 * This is a convenience function for the DBFS API; a store that
659 * supports access control still internally performs these checks to
660 * guarantee security.
661 *
662 */
663
664 function checkAccess(
665 store_name in varchar2,
666 path in varchar2,
667 pathtype in integer,
668 operation in varchar2,
669 principal in varchar2)
670 return integer;
671
672
673
674 end;
[Home] [Help]