1 PACKAGE dbms_epg AUTHID CURRENT_USER IS
2
3 --
4 -- The PL/SQL gateway enables a Web browser to invoke a PL/SQL stored
5 -- procedure through an HTTP listener. It is a platform on which PL/SQL
6 -- users develop and deploy PL/SQL Web applications. The embedded PL/SQL
7 -- gateway is an embedded version of the PL/SQL gateway that runs in the
8 -- XML DB HTTP Server in the Oracle database. It provides the core
9 -- features of mod_plsql in the database but does not require the
10 -- Oracle HTTP Server powered by Apache.
11 --
12
13 ----------------
14 ---- Types -----
15 ----------------
16 type VARCHAR2_TABLE is table of varchar2(4000) INDEX BY BINARY_INTEGER;
17
18 ----------------
19 -- Exceptions --
20 ----------------
21 invalid_dad_name EXCEPTION;
22 dad_not_found EXCEPTION;
23 unknown_attribute EXCEPTION;
24 PRAGMA EXCEPTION_INIT(invalid_dad_name, -24240);
25 PRAGMA EXCEPTION_INIT(dad_not_found, -24231);
26 PRAGMA EXCEPTION_INIT(unknown_attribute, -24232);
27 invalid_dad_name_num constant PLS_INTEGER := -24240;
28 dad_not_found_num constant PLS_INTEGER := -24231;
29 unknown_attribute_num constant PLS_INTEGER := -24232;
30
31 ---------------
32 -- Constants --
33 ---------------
34 -- Log levels for the global attribute "log-level"
35 LOG_EMERG CONSTANT PLS_INTEGER := 0;
36 LOG_ALERT CONSTANT PLS_INTEGER := 1;
37 LOG_CRIT CONSTANT PLS_INTEGER := 2;
38 LOG_ERR CONSTANT PLS_INTEGER := 3;
39 LOG_WARNING CONSTANT PLS_INTEGER := 4;
40 LOG_NOTICE CONSTANT PLS_INTEGER := 5;
41 LOG_INFO CONSTANT PLS_INTEGER := 6;
42 LOG_DEBUG CONSTANT PLS_INTEGER := 7;
43
44 ----------------------------- Configuration API ----------------------------
45 -- The XDBADMIN role is required to modify the embedded gateway
46 -- configuration through the configuration API. Modification of the
47 -- configuration by a user without the role will result in an "access denied"
48 -- exception.
49
50 --------------------------------------------
51 ------ Global Attribute Configuration ------
52 --------------------------------------------
53
54 --
55 -- Sets a global attribute.
56 --
57 -- If the attribute has been set before, the old value will be overwritten
58 -- with the new value. The attribute name is case sensitive. The value
59 -- may or may not be case-sensitive depending on the attribute.
60 --
61 -- PARAMETERS
62 -- attr_name The global attribute to set
63 -- attr_value The attribute value to set
64 -- RETURN
65 -- None
66 -- EXCEPTIONS
67 -- - if the attribute is unknown
68 -- - if the invoker does not have the XDBADMIN role
69 -- EXAMPLES
70 -- dbms_epg.set_global_attribute('max-parameters', '100');
71 --
72 procedure set_global_attribute(attr_name IN varchar2,
73 attr_value IN varchar2);
74
75 --
76 -- Gets the value of a global attribute.
77 --
78 -- PARAMETERS
79 -- attr_name The global attribute to retrieve
80 -- RETURN
81 -- The global attribute value. Returns NULL if the attribute is unknown or
82 -- has not been set.
83 -- EXCEPTIONS
84 -- None
85 --
86 function get_global_attribute(attr_name IN varchar2) return varchar2;
87
88 --
89 -- Deletes a global attribute.
90 --
91 -- PARAMETERS
92 -- attr_name The global attribute to delete
93 -- RETURN
94 -- None
95 -- EXCEPTIONS
96 -- None
97 --
98 procedure delete_global_attribute(attr_name IN varchar2);
99
100 --
101 -- Gets all global attributes/values.
102 --
103 -- The outputs are 2 correlated index-by tables of the name/value pairs.
104 --
105 -- PARAMETERS
106 -- attr_names The global attribute names
107 -- attr_values The values of the global attributes
108 -- RETURN
109 -- None
110 -- EXCEPTIONS
111 -- None
112 -- NOTES
113 -- If no global attribute has been set, "attr_names" and "attr_values"
114 -- will be set to empty arrays.
115 --
116 procedure get_all_global_attributes(attr_names OUT NOCOPY VARCHAR2_TABLE,
117 attr_values OUT NOCOPY VARCHAR2_TABLE);
118
119 ----------------------------------------------------------
120 ----- Database Access Descriptor (DAD) Configuration -----
121 ----------------------------------------------------------
122
123 --
124 -- In order to make a PL/SQL application accessible from the browser via
125 -- HTTP, a Database Access Descriptor (DAD) must be created and mapped to
126 -- a virtual path. A DAD is a set of configuration values used for database
127 -- access and the virtual-path mapping makes the application accessible
128 -- under a virtual path of the XML DB HTTP Server. A DAD is represented
129 -- as a servlet in XML DB HTTP Server.
130 --
131
132 --
133 -- Creates a new DAD. None of its attributes will be set. If a virtual path
134 -- is given, the DAD will be mapped to the virtual path. Otherwise, the DAD
135 -- will not be mapped. If the virtual path exists already, the virtual path
136 -- will be mapped to the new DAD.
137 --
138 -- DAD name is case-sensitive. If a DAD with this name already exists,
139 -- the old DAD's information will be deleted.
140 --
141 -- The embedded gateway handles database authentication differently from
142 -- mod_plsql. In particular, it does not store any database password in a
143 -- DAD. The following explains the database authentication schemes.
144 --
145 -- 1. Static Authentication
146 --
147 -- For mod_plsql users who store database usernames/passwords in the DADs
148 -- so that the browser user will not be required to enter the database
149 -- authentication information, they can utilize the embedded gateway's static
150 -- authentication scheme. To use this scheme, the administrator with the
151 -- XDBADMIN role creates the DAD with the DAD attribute "database-username"
152 -- set, for example,
153 --
154 -- > sqlplus xdb/...
155 -- SQL> begin
156 -- dbms_epg.create_dad('HR', '/hrweb/*');
157 -- dbms_epg.set_dad_attribute('HR', 'database-username', 'SCOTT');
158 -- end;/
159 --
160 -- and the database user authorizes the embedded gateway to use his
161 -- privileges to invoke procedures and access document tables through the
162 -- DAD, for example,
163 --
164 -- > sqlplus scott/...
165 -- SQL> begin
166 -- dbms_epg.authorize_dad('HR');
167 -- end;
168 -- /
169 --
170 -- In order to use this scheme, both the DAD attribute "database-username"
171 -- must be set and the DAD must be authorized to use the user's privileges.
172 -- The DAD attribute "database-username" is case-sensitive. See the
173 -- description of the "set_dad_attribute" procedure for details.
174 --
175 -- Note that in this scheme, the embedded gateway, unlike mod_plsql, logs on
176 -- to the database as the special user "ANONYMOUS" but accesses database
177 -- objects using the user's privileges and default roles. Access will be
178 -- rejected if the browser user attempts to log on explicitly with the HTTP
179 -- "Authorization" header.
180 --
181 -- 2. Dynamic Authentication
182 --
183 -- For mod_plsql users who do not store database usernames/passwords in
184 -- the DADs, they can utilize the embedded gateway's dynamic authentication
185 -- scheme. To use this scheme, the administrator with the XDBADMIN role
186 -- simply creates the DAD. For example,
187 --
188 -- > sqlplus xdb/...
189 -- SQL> begin
190 -- dbms_epg.create_dad('HR', '/hrweb/*');
191 -- end;
192 -- /
193 --
194 -- To access the procedures or document tables through the DAD, browser users
195 -- will be required to supply the database authentication information via the
196 -- HTTP Basic Authentication scheme to log on to the database. If the DAD
197 -- attribute "database-username" is set, logon will be restricted to the
198 -- specified user. Caution: since the passwords sent through the HTTP Basic
199 -- Authentication scheme are not encrypted, the administrator should set up
200 -- the embedded gateway to use the HTTPS protocol to protect the passwords
201 -- sent by the browser users.
202 --
203 -- Note that in this scheme, the embedded gateway logs on to the database as
204 -- the user supplied by the browser user. The database user does not have to
205 -- authorize the embedded gateway to use his privileges to access database
206 -- objects since the browser user provides the database authentication
207 -- information to log on explicitly.
208 --
209 -- 3. Anonymous Authentication
210 --
211 -- For mod_plsql users who create a special DAD database user for database
212 -- logon purpose but store the application procedures and document tables
213 -- in a different schema and grant access to the procedures and document
214 -- tables to PUBLIC, they can utilize the embedded gateway's anonymous
215 -- authentication scheme. To use this scheme, the administrator with the
216 -- XDBADMIN role simply creates the DAD with the DAD attribute
217 -- "database-username" set to "ANONYMOUS" (case-sensitive). For example,
218 --
219 -- > sqlplus xdb/...
220 -- SQL> begin
221 -- dbms_epg.create_dad('HR', '/hrweb/*');
222 -- dbms_epg.set_dad_attribute('HR', 'database-username', 'ANONYMOUS');
223 -- end;
224 -- /
225 --
226 -- In order to use this scheme, the DAD attribute "database-username" must be
227 -- set to "ANONYMOUS" (case-sensitive). There is no need to authorize the
228 -- embedded gateway to use ANONYMOUS' privileges to access database objects
229 -- since ANONYMOUS has no system privileges and owns no database objects.
230 --
231 -- PARAMETERS
232 -- dad_name The name of the DAD to create
233 -- path The virtual path to map the DAD to
234 -- RETURN
235 -- None
236 -- EXCEPTIONS
237 -- - if the invoker does not have the XDBADMIN role
238 --
239 procedure create_dad(dad_name IN varchar2, path IN varchar2 DEFAULT NULL);
240
241 --
242 -- Drops a DAD. All virtual-path mappings of the DAD will be dropped also
243 -- but the authorizations of the DAD will not be dropped.
244 --
245 -- PARAMETERS
246 -- dad_name The DAD to drop
247 -- RETURN
248 -- None
249 -- EXCEPTIONS
250 -- - if the DAD does not exist
251 -- - if the invoker does not have the XDBADMIN role
252 --
253 procedure drop_dad(dad_name IN varchar2);
254
255 --
256 -- Sets an attribute for a DAD.
257 --
258 -- If the attribute has been set before, the old value will be overwritten
259 -- with the new value for single-occurrence attributes. For multi-occurrence
260 -- attributes, the value will be appended instead.
261 --
262 -- The DAD attribute name is case-sensitive. The attribute value may or may
263 -- not be case-sensitive depending on the attribute.
264 --
265 -- DAD attributes are named differently from the DAD attributes of mod_plsql.
266 -- The name mapping is as follows:
267 --
268 -- mod_plsql attributes embedded PL/SQL gateway attributes
269 -- ----------------------------- ----------------------------------
270 -- PlsqlDatabaseUsername database-username
271 -- PlsqlAuthenticationMode authentication-mode
272 -- PlsqlSessionCookieName session-cookie-name
273 -- PlsqlSessionStateManagement session-state-management
274 -- PlsqlMaxRequestsPerSession max-requests-per-session
275 -- PlsqlDefaultPage default-page
276 -- PlsqlDocumentTablename document-table-name
277 -- PlsqlDocumentPath document-path
278 -- PlsqlDocumentProcedure document-procedure
279 -- PlsqlUploadAsLongRaw upload-as-long-raw
280 -- PlsqlPathAlias path-alias
281 -- PlsqlPathAliasProcedure path-alias-procedure
282 -- PlsqlExclusionList exclusion-list
283 -- PlsqlCGIEnvironmentList cgi-environment-list
284 -- PlsqlCompatibilityMode compatibility-mode
285 -- PlsqlNLSLanguage nls-language
286 -- PlsqlFetchBufferSize fetch-buffer-size
287 -- PlsqlErrorStyle error-style
288 -- PlsqlTransferMode transfer-mode
289 -- PlsqlBeforeProcedure before-procedure
290 -- PlsqlAfterProcedure after-procedure
291 -- PlsqlBindBucketLengths bind-bucket-lengths
292 -- PlsqlBindBucketWidths bind-bucket-widths
293 -- PlsqlAlwaysDescribeProcedure always-describe-procedure
294 -- PlsqlInfoLogging info-logging
295 -- PlsqlOWADebugEnable owa-debug-enable
296 -- PlsqlRequestValidationFunction request-validation-function
297 -- PlsqlInputFilterEnable input-filter-enable
298 --
299 -- Note that the embedded gateway DAD attribute "database-username", unlike
300 -- its matching mod_plsql DAD attribute "PlsqlDatabaseUsername", is
301 -- case-sensitive as in the USERNAME column of the ALL_USERS view. The DAD
302 -- attribute "PlsqlDatabasePassword" is not needed. See the explanation of
303 -- the database authentication schemes in the "create_dad" procedure. Also,
304 -- the DAD attribute "PlsqlDatabaseConnectString" is not needed since the
305 -- embedded gateway does not support logon to external databases.
306 --
307 -- PARAMETERS
308 -- dad_name The DAD to set attribute
309 -- attr_name The DAD attribute to set
310 -- attr_value The attribute value to set
311 -- RETURN
312 -- None
313 -- EXCEPTIONS
314 -- - if the DAD does not exist
315 -- - if the attribute is unknown
316 -- - if the invoker does not have the XDBADMIN role
317 -- EXAMPLES
318 -- dbms_epg.set_dad_attribute('HR', 'default-page', 'HRApp.home');
319 --
320 procedure set_dad_attribute(dad_name IN varchar2,
321 attr_name IN varchar2,
322 attr_value IN varchar2);
323
324 --
325 -- Gets the value of a DAD attribute.
326 --
327 -- PARAMETERS
328 -- dad_name The DAD to get attribute
329 -- attr_name The DAD attribute to get
330 -- RETURN
331 -- The DAD attribute value. Returns NULL if the attribute is unknown or
332 -- has not been set.
333 -- EXCEPTIONS
334 -- - if the DAD does not exist
335 --
336 function get_dad_attribute(dad_name IN varchar2,
337 attr_name IN varchar2) return varchar2;
338
339 --
340 -- Gets all attributes of a DAD.
341 --
342 -- The outputs are 2 correlated index-by tables of the name/value pairs.
343 --
344 -- PARAMETERS
345 -- dad_name The DAD to get attributes
346 -- attr_names The DAD attribute names
347 -- attr_values The values of the DAD attributes
348 -- RETURN
349 -- None
350 -- EXCEPTIONS
351 -- - if the DAD does not exist
352 -- NOTE
353 -- If the DAD has no attributes set, "attr_names" and "attr_values"
354 -- will be set to empty arrays.
355 --
356 procedure get_all_dad_attributes(dad_name IN varchar2,
357 attr_names OUT NOCOPY VARCHAR2_TABLE,
358 attr_values OUT NOCOPY VARCHAR2_TABLE);
359
360 --
361 -- Deletes a DAD attribute.
362 --
363 -- PARAMETERS
364 -- dad_name The DAD to delete attribute
365 -- attr_name The DAD attribute to delete
366 -- RETURN
367 -- None
368 -- EXCEPTIONS
369 -- - if the DAD does not exist
370 --
371 procedure delete_dad_attribute(dad_name IN varchar2,
372 attr_name IN varchar2);
373
374 --
375 -- Maps a DAD to a virtual path. If the virtual path exists already, the
376 -- virtual path will be mapped to the new DAD.
377 --
378 -- PARAMETERS
379 -- dad_name The DAD to map
380 -- path The virtual path to map
381 -- RETURN
382 -- None
383 -- EXCEPTIONS
384 -- - if the DAD does not exist
385 --
386 procedure map_dad(dad_name IN varchar2, path IN varchar2);
387
388 --
389 -- Unmaps a DAD from a virtual path. If the virtual path is NULL, unmap the
390 -- DAD from all virtual paths.
391 --
392 -- PARAMETERS
393 -- dad_name The DAD to unmap
394 -- path The virtual path to unmap
395 -- RETURN
396 -- None
397 -- EXCEPTIONS
398 -- - if the DAD does not exist
399 --
400 procedure unmap_dad(dad_name IN varchar2, path IN varchar2 DEFAULT NULL);
401
402 --
403 -- Gets all virtual paths a DAD is mapped to.
404 --
405 -- PARAMETERS
406 -- dad_name The DAD to retrieve virtual-path mappings
407 -- paths The virtual paths mapped to the DAD
408 -- RETURN
409 -- None
410 -- EXCEPTIONS
411 -- - if the DAD does not exist
412 -- NOTE
413 -- If the DAD is not mapped to any virtual path, "paths" will be set
414 -- to an empty array.
415 --
416 procedure get_all_dad_mappings(dad_name IN varchar2,
417 paths OUT NOCOPY VARCHAR2_TABLE);
418
419 --
420 -- Gets the list of all DADs.
421 --
422 -- PARAMETERS
423 -- dad_names The list of all DADs
424 -- RETURN
425 -- None
426 -- EXCEPTIONS
427 -- None
428 -- NOTE
429 -- If no DADs exist, "dad_names" will be set to an empty array.
430 --
431 procedure get_dad_list(dad_names OUT NOCOPY VARCHAR2_TABLE);
432
433 ---------------------------- Authorization API -----------------------------
434 -- Any user can authorize the use of his privileges to the embedded gateway
435 -- through the authorization API in his schema. The XDBADMIN role is not
436 -- required to perform such authorization.
437
438 --
439 -- Authorizes a DAD to use a user's privileges to invoke procedures and
440 -- access document tables. The invoker can always authorize the use of
441 -- his own privileges. To authorize the use of another user's privileges,
442 -- the invoker must have the the ALTER USER system privilege.
443 --
444 -- The DAD authorization may be performed before the DAD is created. The
445 -- DAD attribute "database-username" does not have to be set to user to
446 -- authorize. Multiple users can authorize the same DAD and it is up to
447 -- DAD's "database-username" attribute setting to decide which user's
448 -- privileges to use. To view the DAD authorizations, see the database
449 -- dictionary views USER_EPG_DAD_AUTHORIZATION and DBA_EPG_DAD_AUTHORIZATION.
450 --
451 -- PARAMETERS
452 -- dad_name The DAD to authorize use
453 -- user The user whose privileges to authorize. If the user is NULL,
454 -- the invoker is assumed. The username is case-sensitive as in
455 -- the USERNAME column of the ALL_USERS view.
456
457 -- RETURN
458 -- None
459 -- EXCEPTIONS
460 -- - if the user does not exist
461 -- - if the invoker authorizes for another user but he does not have the
462 -- ALTER USER system privilege
463 -- EXAMPLE
464 -- dbms_epg.authorize_dad('HR');
465 --
466 procedure authorize_dad(dad_name IN varchar2,
467 user IN varchar2 DEFAULT NULL);
468
469 --
470 -- Deauthorizes a DAD's use of a user's privileges to invoke procedures and
471 -- access document tables. The invoker can always deauthorize the use of
472 -- his own privileges. To deauthorize the use of another user's privileges,
473 -- the invoker must have the the ALTER USER system privilege.
474 --
475 -- PARAMETERS
476 -- dad_name The DAD to deauthorize use
477 -- user The user whose privileges to deauthorize. If the user is NULL,
478 -- the invoker is assumed. The username is case-sensitive as in
479 -- the USERNAME column of the ALL_USERS view.
480 -- RETURN
481 -- None
482 -- EXCEPTIONS
483 -- - if the user does not exist
484 -- - if the invoker deauthorizes for another user but he does not have the
485 -- ALTER USER system privilege
486 -- EXAMPLE
487 -- dbms_epg.deauthorize_dad('HR');
488 --
489 procedure deauthorize_dad(dad_name IN varchar2,
490 user IN varchar2 DEFAULT NULL);
491
492 END dbms_epg;
[Home] [Help]