1 package dbms_dbfs_hs
2 authid current_user
3 as
4
5 -- DBMS_DBFS_HS package is a service provider, underneath
6 -- DBMS_DBFS_CONTENT that enables use of tape or Amazon S3 web service
7 -- as store for data. The data on tape (or Amazon S3 web service) is part
8 -- of the Oracle Database and can be accessed through all standard APIs, but
9 -- only via the database.
10 -- DBMS_DBFS_HS package provides users the ability to use tape
11 -- (or Amazon S3 web service) as a storage tier when doing Information
12 -- Lifecycle Management of their content.
13
14 -- Following are the types of storage supported by this package.
15 -- They are the only valid values for the store_type parameter in the
16 -- createStore method of this package.
17 STORETYPE_TAPE CONSTANT VARCHAR2(50) := 'HS_TAPE';
18 STORETYPE_AMAZONS3 CONSTANT VARCHAR2(50) := 'HS_S3';
19
20 -- Following are the properties used by this package.
21 -- All the properties should be set using setStoreProperty method.
22 PROPNAME_SBTLIBRARY CONSTANT VARCHAR2(50) := 'SBT_LIBRARY';
23 PROPNAME_MEDIAPOOL CONSTANT VARCHAR2(50) := 'MEDIA_POOL';
24 PROPNAME_OPTTARBALLSIZE CONSTANT VARCHAR2(50) := 'OPTIMAL_TARBALL_SIZE';
25 PROPNAME_READCHUNKSIZE CONSTANT VARCHAR2(50) := 'READ_CHUNK_SIZE';
26 PROPNAME_WRITECHUNKSIZE CONSTANT VARCHAR2(50) := 'WRITE_CHUNK_SIZE';
27 PROPNAME_S3HOST CONSTANT VARCHAR2(50) := 'S3_HOST';
28 PROPNAME_HTTPPROXY CONSTANT VARCHAR2(50) := 'HTTP_PROXY';
29 PROPNAME_WALLET CONSTANT VARCHAR2(50) := 'WALLET';
30 PROPNAME_BUCKET CONSTANT VARCHAR2(50) := 'BUCKET';
31 PROPNAME_ALIAS CONSTANT VARCHAR2(50) := 'WALLET_ALIAS';
32 PROPNAME_LICENSEID CONSTANT VARCHAR2(50) := 'LICENSE_ID';
33 PROPNAME_CACHESIZE CONSTANT VARCHAR2(50) := 'CACHE_SIZE';
34 PROPNAME_LOBCACHE_QUOTA CONSTANT VARCHAR2(50) := 'LOBCACHE_QUOTA';
35 PROPNAME_COMPRESSLEVEL CONSTANT VARCHAR2(50) := 'COMPRESSION_LEVEL';
36 PROPVAL_COMPLVL_NONE CONSTANT VARCHAR2(50) := 'NONE';
37 PROPVAL_COMPLVL_LOW CONSTANT VARCHAR2(50) := 'LOW';
38 PROPVAL_COMPLVL_MEDIUM CONSTANT VARCHAR2(50) := 'MEDIUM';
39 PROPVAL_COMPLVL_HIGH CONSTANT VARCHAR2(50) := 'HIGH';
40
41 --LRU timestamp update frequency
42 PROPNAME_LRUTS_UPD_FREQ CONSTANT VARCHAR2(50) := 'LRUTS_UPD_FREQ';
43
44 PROPVAL_MAXBF_S3 CONSTANT NUMBER := 3154728;
45 PROPVAL_CHUNKSIZE CONSTANT VARCHAR2(50) := '1048576';
46
47 -- Valid values for STREAMABLE property are 'TRUE' and 'FALSE'
48 -- The default value of this property is 'TRUE'.
49 PROPNAME_STREAMABLE CONSTANT VARCHAR2(50) := 'STREAMABLE';
50
51 -- Valid values for this property are 'TRUE' and 'FALSE'.
52 -- Default value is 'TRUE' for S3 and 'FALSE' for tape.
53 PROPNAME_ENABLECLEANUPONDELETE CONSTANT VARCHAR2(50) :=
54 'ENABLE_CLEANUP_ON_DELETE';
55
56 PROPNAME_MAX_BACKUPFILE_SIZE CONSTANT VARCHAR2(50) :=
57 'MAX_BACKUPFILE_SIZE';
58
59 PROPNAME_STORE_TYPE CONSTANT VARCHAR2(50) := 'STORE_TYPE';
60
61 -- The following EXCEPTIONS are raised by this package. In addition,
62 -- this package also raises the exceptions defined by DBMS_DBFS_CONTENT.
63 storenf exception;
64 PRAGMA EXCEPTION_INIT(storenf, -20200);
65 storenf_msg constant varchar2(256) :=
66 ' STORE NOT FOUND';
67 storenf_err constant pls_integer := -20200;
68 -- ORA-20200: Store not found
69 -- *Cause: Store with the given name was not found
70 -- *Action: Check the name and Create the Store
71
72 propertynf exception;
73 PRAGMA EXCEPTION_INIT(propertynf, -20201);
74 propertynf_msg constant varchar2(256) :=
75 ' STORE PROPERTY NOT FOUND';
76 propertynf_err constant pls_integer := -20201;
77 -- ORA-20201: Store Property not found
78 -- *Cause: A required store property was not found
79 -- *Action: populate the store property
80
81
82 tbsnotfound exception;
83 PRAGMA EXCEPTION_INIT(tbsnotfound, -20202);
84 tbsnotfound_msg constant varchar2(256) :=
85 ' Specified Tablespace for staging area does not exist';
86 tbsnotfound_err constant pls_integer := -20202;
87 -- ORA-20122: Specified staging area tablespace not found
88 -- *Cause: Invalid tablespace name
89 -- *Action: Pass a valid tablespace name
90
91 change_stagingarea exception;
92 PRAGMA EXCEPTION_INIT(change_stagingarea, -20203);
93 change_stagingarea_msg constant varchar2(256) :=
94 'CHANGE STAGINGAREA FAILED';
95 change_stagingarea_err constant pls_integer := -20203;
96 -- ORA-20203: CHANGE STAGINGAREA FAILED
97 -- *Cause: StagingArea is in use.
98 -- *Action: Make sure that stagingarea is clean by calling
99 -- DBMS_DBFS_HS.STOREPUSH
100
101 invalidpctx exception;
102 PRAGMA EXCEPTION_INIT(invalidpctx, -20204);
103 invalidpctx_msg constant varchar2(256) :=
104 ' INVALID POLICY CONTEXT';
105 invalidpctx_err constant pls_integer := -20204;
106 -- ORA-20204: Invalid PolicyCtx passed in
107 -- *Cause: The Policy Context passed in is invalid
108 -- *Action: Pass a valid policy context
109
110 storetype exception;
111 PRAGMA EXCEPTION_INIT(storetype, -20205);
112 storetype_msg constant varchar2(50) := 'STORETYPE IS INVALID';
113 storetype_err constant pls_integer := -20205;
114 -- ORA-20205: STORETYPE IS INVALID
115 -- *Cause: STORETYPE is not one of the types defined by
116 -- DBMS_DBFS_HS
117 -- *Action: change STORETYPE to one of the types defined by
118 -- DBMS_DBFS_HS
119
120 insufficient_cache exception;
121 PRAGMA EXCEPTION_INIT(insufficient_cache, -20206);
122 insufficient_cache_msg constant varchar2(50) := 'CACHESIZE IS INSUFFICIENT';
123 insufficient_cache_err constant pls_integer := -20206;
124 -- ORA-20206: CACHESIZE IS INSUFFICIENT
125 -- *Cause : CACHESIZE provided to DBMS_DBFS_HS store
126 -- is insufficient
127 -- *Action : increase CACHESIZE provided to create DBMS_DBFS_HS
128 -- store
129
130 string_overflow exception;
131 PRAGMA EXCEPTION_INIT(string_overflow, -20207);
132 string_overflow_msg constant varchar2(50) := 'string overflow';
133 string_overflow_err constant pls_integer := -20207;
134 -- ORA-20207: string overflow
135 -- *Cause : String is longer than allowed length
136 -- *Action : Contact Oracle Support
137
138 invalid_lobCacheQuota exception;
139 PRAGMA EXCEPTION_INIT(invalid_lobCacheQuota, -20208);
140 invalid_lobCacheQuota_msg constant varchar2(50) := 'Invalid lob Cache quota specified';
141 invalid_lobCacheQuota_err constant pls_integer := -20208;
142 -- ORA-20208: Invalid lobCache Quota.
143 -- *Cause : condition 0 < lobCacheQuota < 1 violated
144 -- *Action : either use default value of lobcachequota or provide
145 -- a suitable positive fraction less than 1.
146
147 invalidcompression exception;
148 PRAGMA EXCEPTION_INIT(invalidcompression, -20209);
149 invalidcompression_msg constant varchar2(256) :=
150 ' INVALID COMPRESSION LEVEL';
151 invalidcompression_err constant pls_integer := -20209;
152 -- ORA-20209: Invalid Compression Level
153 -- *Cause: COMPRESSION_LEVEL StoreProperty has an invalid value
154 -- *Action: Set COMPRESSION_LEVEL To a valid value
155
156 filesizemismatch exception;
157 PRAGMA EXCEPTION_INIT(filesizemismatch, -20210);
158 filesizemismatch_msg constant varchar2(256) :=
159 ' FILE SIZE MISMATCH';
160 filesizemismatch_err constant pls_integer := -20210;
161 -- ORA-20210: File Size mismatch
162 -- *Cause: Data has been corrupted
163 -- *Action: Contact Oracle Customer Support
164
165 thrashing exception;
166 PRAGMA EXCEPTION_INIT(thrashing, -20211);
167 thrashing_msg constant varchar2(256) :=
168 ' THRASHING IN LOBCACHE';
169 thrashing_err constant pls_integer := -20211;
170 -- ORA-20211: Thrahing in lobcache
171 -- *Cause: Small lob cache for bigger working set
172 -- *Action: Increase cache size to accomodate working set
173 -- to minimize thrashing and improve performance
174
175 filenotfound exception;
176 PRAGMA EXCEPTION_INIT(filenotfound, -20212);
177 filenotfound_msg constant varchar2(256) :=
178 ' FILE NOT FOUND';
179 filenotfound_err constant pls_integer := -20212;
180 -- ORA-20212: File not found
181 -- *Cause: File not found
182 -- *Action: Contact Oracle Customer Support
183
184 dropstore_runningjob exception;
185 PRAGMA EXCEPTION_INIT(dropstore_runningjob, -20213);
186 dropstore_runningjob_msg constant varchar2(256) :=
187 ' JOB STILL RUNNING.STORE NOT DROPPED. TRY AGAIN.';
188 dropstore_runningjob_err constant pls_integer := -20213;
189 -- ORA-20213: JOB STILL RUNNING.STORE NOT DROPPED. TRY AGAIN
190 -- *Cause: Store cannot be dropped because associated job is still running.
191 -- *Action: Try dropStore procedure again.
192
193 FAIL CONSTANT NUMBER := 0;
194 SUCCESS CONSTANT NUMBER := 1;
195 ERROR CONSTANT NUMBER := 2;
196
197
198
199 function getFeatures(
200 store_name in varchar2)
201 return integer;
202
203 function getStoreId(
204 store_name in varchar2)
205 return number;
206
207 function getVersion(
208 store_name in varchar2)
209 return varchar2;
210
211 procedure spaceUsage(
212 store_name in varchar2,
213 blksize out integer,
214 tbytes out integer,
215 fbytes out integer,
216 nfile out integer,
217 ndir out integer,
218 nlink out integer,
219 nref out integer);
220
221
222 procedure createFile(
223 store_name in varchar2,
224 path in varchar2,
225 properties in out nocopy dbms_dbfs_content_properties_t,
226 content in out nocopy blob,
227 prop_flags in integer,
228 ctx in dbms_dbfs_content_context_t);
229
230 procedure createLink(
231 store_name in varchar2,
232 srcPath in varchar2,
233 dstPath in varchar2,
234 properties in out nocopy dbms_dbfs_content_properties_t,
235 prop_flags in integer,
236 ctx in dbms_dbfs_content_context_t);
237
238 procedure createReference(
239 store_name in varchar2,
240 srcPath in varchar2,
241 dstPath in varchar2,
242 properties in out nocopy dbms_dbfs_content_properties_t,
243 prop_flags in integer,
244 ctx in dbms_dbfs_content_context_t);
245
246 procedure createDirectory(
247 store_name in varchar2,
248 path in varchar2,
249 properties in out nocopy dbms_dbfs_content_properties_t,
250 prop_flags in integer,
251 recurse in integer,
252 ctx in dbms_dbfs_content_context_t);
253
254
255 procedure deleteFile(
256 store_name in varchar2,
257 path in varchar2,
258 filter in varchar2,
259 soft_delete in integer,
260 ctx in dbms_dbfs_content_context_t);
261
262 procedure deleteContent(
263 store_name in varchar2,
264 contentID in raw,
265 filter in varchar2,
266 soft_delete in integer,
267 ctx in dbms_dbfs_content_context_t);
268
269 procedure deleteDirectory(
270 store_name in varchar2,
271 path in varchar2,
272 filter in varchar2,
273 soft_delete in integer,
274 recurse in integer,
275 ctx in dbms_dbfs_content_context_t);
276
277 procedure restorePath(
278 store_name in varchar2,
279 path in varchar2,
280 filter in varchar2,
281 ctx in dbms_dbfs_content_context_t);
282
283 procedure purgePath(
284 store_name in varchar2,
285 path in varchar2,
286 filter in varchar2,
287 ctx in dbms_dbfs_content_context_t);
288
289 procedure restoreAll(
290 store_name in varchar2,
291 path in varchar2,
292 filter in varchar2,
293 ctx in dbms_dbfs_content_context_t);
294
295 procedure purgeAll(
296 store_name in varchar2,
297 path in varchar2,
298 filter in varchar2,
299 ctx in dbms_dbfs_content_context_t);
300
301
302 procedure getPath(
303 store_name in varchar2,
304 path in varchar2,
305 properties in out nocopy dbms_dbfs_content_properties_t,
306 content out blob,
307 item_type out integer,
308 prop_flags in integer,
309 forUpdate in integer,
310 deref in integer,
311 ctx in dbms_dbfs_content_context_t);
312
313 procedure getPathNowait(
314 store_name in varchar2,
315 path in varchar2,
316 properties in out nocopy dbms_dbfs_content_properties_t,
317 content out nocopy blob,
318 item_type out integer,
319 prop_flags in integer,
320 deref in integer,
321 ctx in dbms_dbfs_content_context_t);
322
323 procedure getPath(
324 store_name in varchar2,
325 path in varchar2,
326 properties in out nocopy dbms_dbfs_content_properties_t,
327 amount in out number,
328 offset in number,
329 buffer out raw,
330 prop_flags in integer,
331 ctx in dbms_dbfs_content_context_t);
332
333 procedure getPath(
334 store_name in varchar2,
335 path in varchar2,
336 properties in out nocopy dbms_dbfs_content_properties_t,
337 amount in out number,
338 offset in number,
339 buffers out dbms_dbfs_content_raw_t,
340 prop_flags in integer,
341 ctx in dbms_dbfs_content_context_t);
342
343 procedure putPath(
344 store_name in varchar2,
345 path in varchar2,
346 properties in out nocopy dbms_dbfs_content_properties_t,
347 content in out nocopy blob,
348 item_type out integer,
349 prop_flags in integer,
350 ctx in dbms_dbfs_content_context_t);
351
352 procedure putPath(
353 store_name in varchar2,
354 path in varchar2,
355 properties in out nocopy dbms_dbfs_content_properties_t,
356 amount in number,
357 offset in number,
358 buffer in raw,
359 prop_flags in integer,
360 ctx in dbms_dbfs_content_context_t);
361
362 procedure putPath(
363 store_name in varchar2,
364 path in varchar2,
368 buffers in dbms_dbfs_content_raw_t,
365 properties in out nocopy dbms_dbfs_content_properties_t,
366 written out number,
367 offset in number,
369 prop_flags in integer,
370 ctx in dbms_dbfs_content_context_t);
371
372
373 procedure renamePath(
374 store_name in varchar2,
375 oldPath in varchar2,
376 newPath in varchar2,
377 properties in out nocopy dbms_dbfs_content_properties_t,
378 ctx in dbms_dbfs_content_context_t);
379
380 procedure setPath(
381 store_name in varchar2,
382 contentID in raw,
383 path in varchar2,
384 properties in out nocopy dbms_dbfs_content_properties_t,
385 ctx in dbms_dbfs_content_context_t);
386
387 function list(
388 store_name in varchar2,
389 path in varchar2,
390 filter in varchar2,
391 recurse in integer,
392 ctx in dbms_dbfs_content_context_t)
393 return dbms_dbfs_content_list_items_t
394 pipelined;
395
396 function search(
397 store_name in varchar2,
398 path in varchar2,
399 filter in varchar2,
400 recurse in integer,
401 ctx in dbms_dbfs_content_context_t)
402 return dbms_dbfs_content_list_items_t
403 pipelined;
404
405
406 procedure lockPath(
407 store_name in varchar2,
408 path in varchar2,
409 lock_type in integer,
410 lock_data in varchar2,
411 ctx in dbms_dbfs_content_context_t);
412
413 procedure unlockPath(
414 store_name in varchar2,
415 path in varchar2,
416 ctx in dbms_dbfs_content_context_t);
417
418
419 function checkAccess(
420 store_name in varchar2,
421 path in varchar2,
422 pathtype in integer,
423 operation in varchar2,
424 principal in varchar2)
425 return integer;
426
427
428 function getPathByStoreId(
429 store_name in varchar2,
430 guid in integer)
431 return varchar2;
432
433 -- Create a new HS Store.
434 --
435 -- Creates a new HS store "store_name" of type
436 -- "store_type" ( STORETYPE_TAPE or STORETYPE_AMAZONS3" )
437 -- in schema "schema_name" ( defaulting to current schema )
438 -- under the ownership of invoking session user.
439 -- "tbl_name" in tablespace "tbs_space" is a placeholder of the
440 -- store content cached in database.
441 --
442 -- "cache_size" worth of space will be used by the store
443 -- to cache content in given table space "tbs_name".
444 --
445 --
446 procedure createStore(
447 store_name in varchar2,
448 store_type in varchar2,
449 tbl_name in varchar2,
450 tbs_name in varchar2,
451 cache_size in number ,
452 lob_cache_quota in number default null,
453 optimal_tarball_size in number default null,
454 schema_name in varchar2 default null);
455
456 -- Drop HS Store
457 --
458 -- Drops previously created "store_name" under the ownership of the
459 -- invoking session_user.
460 --
461 -- The store will be un-registered from DBFS.
462 -- All files within given store will be deleted from backend,
463 -- (Tape/S3). Caching table , placeholder for store's
464 -- content cached in database, will be dropped.
465 --
466 -- The procedure executes like a DDL (ie auto-commits before
467 -- and after its execution)
468 --
469 -- User can specify optional flags for dropStore.
470 -- If 'DISABLE_CLEANUPBACKUPFILES' ( HS DropStore FLags)
471 -- is specified as one of the optional flags,
472 -- cleanUpBackupFiles will not be issued as a part of dropStore.
473 --
474 -- By default, when this flag is not set , dropStore implicitly
475 -- cleans up all unused backupfiles.
476 --
477 -- dropStore purges all the dictionary information associated with
478 -- the store. If cleanupbackupFiles is disabled during dropstore,
479 -- user will have to resort to out-of-band techniques to remove unused
480 -- backup files. No further invocations of cleanupbackfiles for a dropped
481 -- store are possible through HS
482
483 DISABLE_CLEANUPBACKUPFILES constant integer := 1;
484 procedure dropStore(
485 store_name in varchar2,
486 opt_flags in integer default 0);
487
488
489 -- Push locally staged data to remote store
493 -- Cleanup unused backup files
490 procedure storePush(store_name in varchar2, path in varchar2 default null);
491
492
494 procedure cleanupUnusedBackupfiles(store_name in varchar2);
495
496 -- Send an explicit store command
497 procedure sendCommand(store_name in varchar2, message in varchar2);
498
499
500 -- This method saves properties ( = name, value pairs) of
501 -- a store in the database
502 procedure setStoreProperty(store_name in varchar2,
503 property_name in varchar2,
504 property_value in varchar2);
505 -- This method retrieves the values of a property, identified
506 -- by PropertyName, of a store from the database.
507 -- If NoExcp is set to false, then exception is raised if the
508 -- property does not exist in the database.
509 -- If noexcp is set to true, then null is returned if the
510 -- property does not exist in the database
511 function getStoreProperty(store_name in varchar2,
512 property_name in varchar2,
513 noexcp in boolean default false)
514 return varchar2;
515
516 -- When we try to push data to or get data from external store,
517 -- we will begin an API session (to talk to the store), and after beginning
518 -- the session, we will send all registered messages to the store
519 -- before writing any data.
520 -- Following are the valid values for the parameter FLAGS in
521 -- REGISTERSTORECOMMAND method.
522 BEFORE_PUT CONSTANT NUMBER := 1;
523 BEFORE_GET CONSTANT NUMBER := 2;
524 procedure registerStoreCommand(store_name in varchar2, message in varchar2,
525 flags in number);
526
527 -- Deregister a store message.
528 procedure deregStoreCommand(store_name in varchar2, message in varchar2);
529
530 -- The AWS bucket, associated with a store of type
531 -- STORETYPE_AMAZONS3 , should already exist when the HS
532 -- tries to move data into that bucket. One way of creating S3 bucket is to
533 -- use the DBMS_DBFS_HS.CREATEBUCKET method.
534 -- The PROPNAME_BUCKET property of the store should be set
535 -- before this method is called.
536 procedure createBucket(store_name in varchar2);
537
538 -- listcontentFilename lists all the content file names across all
539 -- the storeitories owned by the current session user.
540 function listcontentfilename
541 return dbms_dbfs_hs_litems_t
542 pipelined;
543
544 -- Flushes out dirty contents from level-1 cache.
545 -- And truncates all the lockable content from cache.
546 procedure flushCache( store_name in varchar2);
547
548 procedure reconfigCache( store_name in varchar2,
549 cache_size in number default null,
550 lob_cache_quota in number default null,
551 optimal_tarball_size in number default null);
552 end;
[Home] [Help]