1 package dbms_dbfs_content_admin
2 authid definer
3 as
4
5
6
7 /*
8 * Administrative and query APIs:
9 *
10 * (Administrative) clients and store providers are expected to
11 * register stores with the DBFS API. Additionally, administrative
12 * clients are expected to mount stores into the toplevel namespace
13 * of their choice.
14 *
15 * The registration/unregistration of a store is separated from the
16 * mount/unmount of a store since it is possible for the same store
17 * to be mounted multiple times at different mount-points (and this
18 * is under client control).
19 *
20 *
21 * The administrative methods in "dbms_dbfs_content" are merely
22 * wrappers that delegate to the matching methods in
23 * "dbms_dbfs_content_admin". Clients can use the methods in either
24 * package to perform administrative operations.
25 *
26 */
27
28
29
30 /*
31 * Register a new store "store_name" backed by provider
32 * "provider_name" that uses "provider_package" as the store
33 * provider (conforming to the "dbms_dbfs_content_spi" package
34 * signature).
35 *
36 * This method is to be used primarily by store providers after they
37 * have created a new store.
38 *
39 * Store names must be unique.
40 *
41 */
42
43 procedure registerStore(
44 store_name in varchar2,
45 provider_name in varchar2,
46 provider_package in varchar2);
47
48 /* registerStore_log: INTERNAL USE ONLY */
49 procedure registerStore_log(
50 store_name in varchar2,
51 provider_name in varchar2,
52 provider_package in varchar2,
53 suid in varchar2,
54 ctime in timestamp);
55 pragma supplemental_log_data(
56 registerStore_log,
57 AUTO);
58
59
60
61 /*
62 * Unregister a previously registered store (invalidating all
63 * mount-points associated with it).
64 *
65 * Once unregistered all access to the store (and its mount-points)
66 * are not guaranteed to work (although CR may provide a temporary
67 * illusion of continued access).
68 *
69 *
70 * If the "ignore_unknown" argument is "true", attempts to
71 * unregister unknown stores will not raise an exception.
72 *
73 * If the "store_owner" argument is specified, it implies the
74 * attempt to cleanup ContentAPI orphans of non-existent schemas.
75 *
76 */
77
78 procedure unregisterStore(
79 store_name in varchar2,
80 ignore_unknown in boolean default false,
81 store_owner in varchar2 default null);
82
83 /* unregisterStore_log: INTERNAL USE ONLY */
84 procedure unregisterStore_log(
85 store_name in varchar2,
86 ignore_unknown in boolean,
87 suid in varchar2,
88 ctime in timestamp);
89 pragma supplemental_log_data(
90 unregisterStore_log,
91 AUTO);
92
93
94
95 /*
96 * Mount a registered store "store_name" and bind it to the
97 * "store_mount" mount-point.
98 *
99 * Once mounted, accesses to pathnames of the form
100 * "/<store_mount>/xyz..." will be redirected to <store_name> and
101 * its store provider.
102 *
103 *
104 * Store mount-points must be unique, and a syntactically valid
105 * pathname component (i.e. a "name_t" with no embedded "/").
106 *
107 *
108 * If a mount-point is not specified (i.e. is null), the DBFS API
109 * attempts to use the store name itself as the mount-point name
110 * (subject to the uniqueness and syntactic constraints).
111 *
112 *
113 * A special empty mount-point is available for singleton stores,
114 * i.e. a scenario where the DBFS API manages a single backend
115 * store---in such cases, the client can directly deal with full
116 * pathnames of the form "/xyz..." since there is no ambiguity in
117 * how to redirect these accesses.
118 *
119 * Singleton mount-points are indicated by the "singleton" boolean
120 * argument, and the "store_mount" argument is ignored.
121 *
122 *
123 * The same store can be mounted multiple times, obviously at
124 * different mount-points.
125 *
126 *
127 * Mount properties can be used to specify the DBFS API execution
128 * environment, i.e. default values of the principal, owner, acl,
129 * and asof for a particular mount-point. Mount properties can also
130 * be used to specify a read-only store.
131 *
132 */
133
134 procedure mountStore(
135 store_name in varchar2,
136 store_mount in varchar2 default null,
137 singleton in boolean default false,
138 principal in varchar2 default null,
139 owner in varchar2 default null,
140 acl in varchar2 default null,
141 asof in timestamp default null,
142 read_only in boolean default false,
143 view_name in varchar2 default null);
144
145 /* mountStore_log: INTERNAL USE ONLY */
146 procedure mountStore_log(
147 store_name in varchar2,
148 store_mount in varchar2,
149 singleton in boolean,
150 principal in varchar2,
151 owner in varchar2,
152 acl in varchar2,
153 asof in timestamp,
154 read_only in boolean,
155 view_name in varchar2,
156 suid in varchar2,
157 ctime in timestamp);
158 pragma supplemental_log_data(
159 mountStore_log,
160 AUTO);
161
162
163
164 /*
165 * Unmount a previously mounted store, either by name or by mount
166 * point.
167 *
168 * Singleton stores can be unmounted only by store name (since they
169 * have no mount-points).
170 *
171 * Attempting to unmount a store by name will unmount all
172 * mount-points associated with the store.
173 *
174 * Once unmounted all access to the store (or mount-point) are not
175 * guaranteed to work (although CR may provide a temporary illusion
176 * of continued access).
177 *
178 *
179 * If the "ignore_unknown" argument is "true", attempts to
180 * unregister unknown stores/mounts will not raise an exception.
181 *
182 */
183
184 procedure unmountStore(
185 store_name in varchar2 default null,
186 store_mount in varchar2 default null,
187 ignore_unknown in boolean default false);
188
189 /* unmountStore_log: INTERNAL USE ONLY */
190 procedure unmountStore_log(
191 store_name in varchar2,
192 store_mount in varchar2,
193 ignore_unknown in boolean,
194 suid in varchar2,
195 ctime in timestamp);
196 pragma supplemental_log_data(
197 unmountStore_log,
198 AUTO);
199
200
201
202 /*
203 * Update operation statistics for a store/mount.
204 *
205 * Statistics flushes are invoked by the DBFS API operations, and
206 * update the common metadata tables in a secure manner.
207 *
208 */
209
210 procedure updateStats(
211 store_name in varchar2,
212 store_mount in varchar2,
213 op in integer,
214 cnt in integer,
215 wt in integer,
216 ct in integer);
217
218
219
220 /*
221 * Utility function: check SPI.
222 *
223 *
224 * Given the name of a putative "dbms_dbfs_content_spi" conforming
225 * package, attempt to check that the package really does implement
226 * all of the provider methods (with the proper signatures), and
227 * report on the conformance.
228 *
229 * The result is generated into the "chk" lob that the caller must
230 * manage.
231 *
232 * This is a helper for "dbms_dbfs_content.checkSpi()".
233 *
234 */
235
236 procedure checkSpi(
237 schema_name in varchar2,
238 package_name in varchar2,
239 chk in out nocopy clob);
240
241
242
243 /*
244 * Utility function: update DBFS context.
245 *
246 * Internal helper function that modifies the DBFS context (and
247 * allows sessions to refresh their internal state on subsequent
248 * operations). Invoked by various clients after any significant
249 * changes to persistent state.
250 *
251 */
252
256
253 procedure updateCtx(
254 suid in varchar2 default null);
255
257
258 /*
259 * DBFS export/import procedural actions.
260 *
261 * For internal use only. See project-5464 for details.
262 *
263 */
264
265 function system_info_exp(
266 prepost in pls_integer,
267 connectstring out nocopy varchar2,
268 version in varchar2,
269 new_block out pls_integer)
270 return varchar2;
271
272 function schema_info_exp(
273 schema in varchar2,
274 prepost in pls_integer,
275 isdba in pls_integer,
276 version in varchar2,
277 new_block out pls_integer)
278 return varchar2;
279
280 function instance_info_exp(
281 name in varchar2,
282 schema in varchar2,
283 prepost in pls_integer,
284 isdba in pls_integer,
285 version in varchar2,
286 new_block out pls_integer)
287 return varchar2;
288
289
290
291 /*
292 * DBFS export/import support.
293 *
294 * A one-time action to register the ContentAPI entities with the
295 * procedural action infrastructure.
296 *
297 * The registrations should normally have already occurred
298 * implicitly during catalog initialization; however, invoking this
299 * procedure (one or more times) explicitly is harmless.
300 *
301 *
302 * The procedure executes like a DDL (i.e. auto-commits before and
303 * after its execution).
304 *
305 */
306
307 procedure eximRegisterAll;
308
309
310
311 /*
312 * DBFS export/import support (helper functions).
313 *
314 * These functions are _strictly_ for internal use in the DBFS
315 * export/import infrastructure. Do not even _think_ about using
316 * them explicitly.
317 *
318 */
319
320 procedure exim_store(
321 s_owner in varchar2,
322 s_name in varchar2,
323 p_name in varchar2,
324 p_pkg in varchar2,
325 created in number);
326 pragma supplemental_log_data(
327 exim_store,
328 AUTO);
329
330 procedure exim_mount(
331 s_owner in varchar2,
332 s_name in varchar2,
333 s_mount in varchar2,
334 created in number);
335 pragma supplemental_log_data(
336 exim_mount,
337 AUTO);
338
339 procedure exim_mountp(
340 s_owner in varchar2,
341 s_name in varchar2,
342 s_mount in varchar2,
343 propname in varchar2,
344 propvalue in varchar2,
345 typecode in number);
346 pragma supplemental_log_data(
347 exim_mountp,
348 AUTO);
349
350
351
352 end;