1 PACKAGE DBMS_XS_SESSIONS AUTHID CURRENT_USER AS
2
3 -- The following constants define operation codes passed into namespace
4 -- event handling functions.
5 attribute_first_read_operation CONSTANT PLS_INTEGER := 1;
6 modify_attribute_operation CONSTANT PLS_INTEGER := 2;
7
8 -- The following constants represent bit values that identify events of
9 -- interest for a particular attribute in a namespace that has an event
10 -- handling function.
11 attribute_first_read_event CONSTANT PLS_INTEGER := 1;
12 modify_attribute_event CONSTANT PLS_INTEGER := 2;
13
14 -- The following constants define return codes that can be returned by a
15 -- namespace event handling function.
16 event_handling_succeeded CONSTANT PLS_INTEGER := 0;
17 event_handling_failed CONSTANT PLS_INTEGER := 1;
18
19 -- The following constants are used as input into the
20 -- add/delete/enable_global_callback procedure.
21 create_session_event CONSTANT PLS_INTEGER := 1;
22 attach_session_event CONSTANT PLS_INTEGER := 2;
23 guest_to_user_event CONSTANT PLS_INTEGER := 3;
24 proxy_to_user_event CONSTANT PLS_INTEGER := 4;
25 revert_to_user_event CONSTANT PLS_INTEGER := 5;
26 enable_role_event CONSTANT PLS_INTEGER := 6;
27 disable_role_event CONSTANT PLS_INTEGER := 7;
28 enable_dynamic_role_event CONSTANT PLS_INTEGER := 8;
29 disable_dynamic_role_event CONSTANT PLS_INTEGER := 9;
30 detach_session_event CONSTANT PLS_INTEGER := 10;
31 terminate_session_event CONSTANT PLS_INTEGER := 11;
32 direct_login_event CONSTANT PLS_INTEGER := 12;
33 direct_logoff_event CONSTANT PLS_INTEGER := 13;
34
35 -- Create a Triton session with specified username. username is 128 char
36 -- case sensitive string. It is mandatory parameter. Unique identifier of
37 -- the session is returned in sessionid parameter. This can be used to
38 -- refer to the session in future calls. To create an anonymous session,
39 -- 'XSGUEST' username is specified. is_external parameter specifies
40 -- whether the session is to be created as external principal session. It
41 -- is an optional parameter and default value of this parameter is false,
42 -- indicating by default regular Triton session will be created. NULL value
43 -- for this parameter is taken as false. is_trusted specifies if session is
44 -- to be created in trusted mode or secure mode. In trusted mode, data
45 -- security checks are bypassed; in secure mode, they are enforced. It is an
46 -- optional parameter and default value is false, indicating secure mode.
47 -- NULL value is taken as false. The combination regular session in trusted
48 -- mode is not supported. Other combinations, regular session in secure mode,
49 -- external session in trusted mode, external session in secure mode are
50 -- supported. namespaces parameter is a list of triplet namespace to be
51 -- created, attribute to be created, attribute value to be set. This is
52 -- optional parameter with default value NULL. XS$GLOBAL_VAR and XS$SESSION
53 -- namespace and their attributes are always available to the session.
54 -- cookie parameter specifies the server cookie to be set for Triton
55 -- session. This is optional parameter with default value NULL. Maximum
56 -- allowed length of cookie is 1024. For creating a Triton session executing
57 -- user need to have CREATE_SESSION privilege. If namespaces are specified,
58 -- during creation of session appropriate privilege (MODIFY_NAMESPACE,
59 -- MODIFY_ATTRIBUTE) on the namespaces or ADMIN_ANY_NAMESPACE system
60 -- privilege is required.
61
62 PROCEDURE create_session (username IN VARCHAR2,
63 sessionid OUT NOCOPY RAW,
64 is_external IN BOOLEAN DEFAULT FALSE,
65 is_trusted IN BOOLEAN DEFAULT FALSE,
66 namespaces IN DBMS_XS_NSATTRLIST DEFAULT NULL,
67 cookie IN VARCHAR2 DEFAULT NULL);
68
69 -- Attach to an already created Triton session specified by the sessionid.
70 -- The attached session will have the following roles enabled - the roles
71 -- granted (directly or indirectly) to the Triton user with which the
72 -- session was created, the session scope roles that were enabled till the
73 -- last detach of this session. In addition, optional parameters
74 -- enable_dynamic_roles, disable_dynamic_roles specify the lists of dynamic
75 -- role to be enabled and disabled. If any of the dynamic roles specified
76 -- does not exist, attach session will fail. If the session is external
77 -- principal session, a list of external roles can be specified for enabling.
78 -- These roles will remain enabled till detach and won't be enabled in next
79 -- attach by default. A list of triplet - namespace, attribute, attribute
80 -- value can be specified during attach. The namespaces and attributes will
81 -- be created and attribute value will be set. This is in addition to the
82 -- namespaces and attributes that were present in the session till last
83 -- detach. Optional parameter authentication_time updates the authentication
84 -- time of the session. For attaching to a Triton session, the executing user
85 -- requires ATTACH_SESSION privilege. If dynamic roles are specified
86 -- ADMINISTER_SESSION privilege is required. If namespaces are specified,
87 -- appropriate privilege (MODIFY_NAMESPACE, MODIFY_ATTRIBUTE) on the
88 -- namespaces or ADMIN_ANY_NAMESPACE system privilege is required.
89
90 PROCEDURE attach_session
91 (sessionid IN RAW,
92 enable_dynamic_roles IN XS$NAME_LIST DEFAULT NULL,
93 disable_dynamic_roles IN XS$NAME_LIST DEFAULT NULL,
94 external_roles IN XS$NAME_LIST DEFAULT NULL,
95 authentication_time IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
96 namespaces IN DBMS_XS_NSATTRLIST DEFAULT NULL);
97
98 -- Switch / proxy from current user to another user in currently assigned
99 -- Triton session. This operation changes the security context of
100 -- the current lightweight user session to a newly initialized security
101 -- context based on the user identified by username. Switch cannot be
102 -- performed from a external user or to a external user. It cannot be
103 -- performed if already in a proxy session unless the switch operation
104 -- means to revert back to old username. username is 128 char case-sensitive
105 -- string. sessionid is optional and if not specified current session is
106 -- taken. If keep_state is set to true, all session state shall be retained,
107 -- otherwise all previous state in the session is cleared. If the target
108 -- user of the proxy operation has a list of filtering roles (proxy roles)
109 -- set up, they are enabled in the session. A list of triplet - namespace,
110 -- attribute, attribute value can be specified during switch. The namespaces
111 -- and attributes will be created and attribute value will be set. This is
112 -- in addition to the namespaces and attributes that were already available
113 -- to the session before this operation (provided keep_state is true). If
114 -- namespaces are specified, appropriate privilege (MODIFY_NAMESPACE,
115 -- MODIFY_ATTRIBUTE) on the namespaces or ADMIN_ANY_NAMESPACE system
116 -- privilege is required.
117
118 PROCEDURE switch_user (username IN VARCHAR2,
119 keep_state IN BOOLEAN DEFAULT FALSE,
120 namespaces IN DBMS_XS_NSATTRLIST DEFAULT NULL) ;
121
122 -- Assign a named user to currently attached anonymous Triton session
123 -- sessionid. username is 128 char case-sensitive string. Error is thrown, if
124 -- an attempt is made to assign user to a session not created by XSGUEST user.
125 -- Roles enabled in current session are retained after this operation.
126 -- Optional parameters enable_dynamic_roles, disable_dynamic_roles specify
127 -- the lists of dynamic role to be enabled and disabled. If any of the
128 -- dynamic roles specified, error is thrown. If the assigned user is
129 -- external, a list of external roles can be supplied for enabling. A list
130 -- of triplet - namespace, attribute, attribute value can be specified
131 -- during assign. The namespaces and attributes will be created and
132 -- attribute value will be set. This is in addition to the namespaces
133 -- and attributes that were already available to the session before this
134 -- operation. Optional parameter authentication_time updates the
135 -- authentication time of the session. Assign user operation requires
136 -- ASSIGN_USER privilege. If namespaces are specified, appropriate
137 -- privilege (MODIFY_NAMESPACE, MODIFY_ATTRIBUTE) on the namespaces or
138 -- ADMIN_ANY_NAMESPACE system privilege is required.
139
140 PROCEDURE assign_user(username IN VARCHAR2,
141 is_external IN BOOLEAN DEFAULT FALSE,
142 enable_dynamic_roles IN XS$NAME_LIST DEFAULT NULL,
143 disable_dynamic_roles IN XS$NAME_LIST DEFAULT NULL,
144 external_roles IN XS$NAME_LIST DEFAULT NULL,
145 authentication_time IN TIMESTAMP WITH TIME ZONE
146 DEFAULT NULL,
147 namespaces IN DBMS_XS_NSATTRLIST
148 DEFAULT NULL);
149
150 -- Detaches the current Database session from the Triton session it is
151 -- currently attached to. If abort flag is set true, it olls back the
152 -- changes done in current session. Otherwise, all changes done in the
153 -- Triton session are persisted. Default value for abort is false. If
154 -- NULL value is supplied for this parameter it is treated as false.
155 -- This operation does not require any privilege. It can only be
156 -- performed from an attached session and after this operation database
157 -- session goes back to the context it was in prior to attaching to the
158 -- Triton session.
159
160 PROCEDURE detach_session(abort IN BOOLEAN DEFAULT FALSE);
161
162 -- Save / persist the changes done in currently attached Triton session to
163 -- metadata table. It can only be performed from an attached session. It
164 -- does not require any privilege. Database session remains attached to the
165 -- Triton session after this operation as it was before this operation.
166
167 PROCEDURE save_session;
168
169 -- Destroy / terminate the session specified by the sessionid. If force is
170 -- true, this operation implicitly detaches all database session from the
171 -- Triton session. Otherwise, if there are attached session, an error is
172 -- thrown. force is an optional parameter and default value for this
173 -- parameter is false. After session is destroyed no further attaches can
174 -- be made to the session. destroy session operation cannot destroy Triton
175 -- sessions created through direct logon of Triton user. destriy session
176 -- operation requires TERMINATE_SESSION privilege.
177
178 PROCEDURE destroy_session (sessionid IN RAW,
179 force IN BOOLEAN DEFAULT FALSE);
180
181 -- Enable the specified regular Triton role in the currently attached Triton
182 -- session. role is 128 char case sensitive string. If the role does not
183 -- exist an error will be thrown. If role is already enabled, the procedure
184 -- does nothing. This operation can only be used to enable directly granted
185 -- (to the Triton session user) regular Triton role. For external principal
186 -- session this API will throw error. This operation requires
187 -- ADMINISTER_SESSION privilege.
188
189 PROCEDURE enable_role (role IN VARCHAR2);
190
191 -- Disable the specified regular Triton role in the currently attached
192 -- Triton session. role is 128 char case sensitive string. If the role does
193 -- not exist an error will be thrown. If role is already enabled, the
194 -- procedure does nothing. This operation can only be used to disable
195 -- directly granted (to the Triton session user) regular Triton role. For
196 -- external principal session this API will throw error. This operation
197 -- requires ADMINISTER_SESSION privilege. It can only be performed when
198 -- attached to a Triton session.
199
200 PROCEDURE disable_role (role IN VARCHAR2);
201
202 -- Create the specified namespace in the currently attached Triton session.
203 -- namespace is 128 char case sensitive string. The namespace template
204 -- corresponding to the namespace need to exist in the system, else this
205 -- operation will throw error. After this operation, the namespace along
206 -- with its attributes are available to the session. This operation
207 -- requires MODIFY_NAMESPACE privilege. It can only be performed when
208 -- attached to a Triton session.
209
210 PROCEDURE create_namespace (namespace IN VARCHAR2);
211
212 -- Delete the specified namespace from the currently attached Triton
213 -- session. namespace is 128 char case sensitive string. If the namespace
214 -- is not there in the session or already deleted error is thrown. This
215 -- operation requires MODIFY_NAMESPACE privilege. It can only be performed
216 -- when attached to a Triton session.
217
218 PROCEDURE delete_namespace (namespace IN VARCHAR2);
219
220 -- Create an attribute in the application namespace specified in currently
221 -- attached Triton session. If namespace is not already available in the
222 -- session or no such namespace templates exist error is thrown. namespace
223 -- is 128 char case-sensitive string while attribute can be 4000 char long.
224 -- Value for attribute is optional and if specified the value is set. value
225 -- can be 4000 char long at maximum. Optional parameter eventreg specifies
226 -- an event for which handler is executed for the attribute. Events can be
227 -- registered only the namespace has an event handler, else error is thrown.
228 -- Allowed value for eventreg are 0 (no event), 1 (first read event),
229 -- 2 (update event), 3 (first read plus update event). If the attribute is
230 -- registered for first read event, then handler will be executed if the
231 -- attribute is uninitialized, before returning the value. If update event is
232 -- registered the handler gets called whenever the attribute is modified.
233 -- This operation requires MODIFY_ATTRIBUTE privilege. It can only be
237 attribute IN VARCHAR2,
234 -- performed if attached to a Triton session.
235
236 PROCEDURE create_attribute (namespace IN VARCHAR2,
238 value IN VARCHAR2 DEFAULT NULL,
239 eventreg IN PLS_INTEGER DEFAULT NULL);
240
241 -- Resets the value for the specified attribute to default value (if present)
242 -- or NULL in the namespace in currently attached session. Valid namespace
243 -- name is 128 char case-sensitive string. attribute can be 4000 char long.
244 -- If the specified attribute does not exist, it is a no-op. This
245 -- operation requires MODIFY_ATTRIBUTE privilege. It can only be performed
246 -- when attached to a Triton session.
247
248 PROCEDURE reset_attribute (namespace IN VARCHAR2,
249 attribute IN VARCHAR2);
250
251 -- Sets the value for the specified attribute to the specified value in the
252 -- namespace in the currently attached session. Valid namespace name is 128
253 -- char case-sensitive string. If the namespace does not exist or mark for
254 -- deletion, an error is thrown. If no template corresponding to the
255 -- namespace exist an error is thrown. attribute and value can be 4000 char
256 -- long. If the specified attribute does not exist, error is thrown. This
257 -- operation requires MODIFY_ATTRIBUTE privilege. It can only be performed
258 -- when attached to a Triton session.
259
260 PROCEDURE set_attribute (namespace IN VARCHAR2,
261 attribute IN VARCHAR2,
262 value IN VARCHAR2);
263
264 -- Gets the value for the specified attribute in the namespace in currently
265 -- attached session. Valid namespace name is 128 char case-sensitive
266 -- string. If the namespace does not exist, return empty string.
267 -- namespace. If no template corresponding to the namespace exist an error
268 -- is thrown. attribute can be 4000 char long. If the specified attribute
269 -- does not exist, return empty string. This operation does not require any
270 -- privilege. It can only be performed if attached to a Triton session.
271
272 PROCEDURE get_attribute (namespace IN VARCHAR2,
273 attribute IN VARCHAR2,
274 value OUT NOCOPY VARCHAR2);
275
276 -- Deletes the specified attribute and its associated value from the
277 -- namespace in currently attached session. Valid namespace name is 128 char
278 -- case-sensitive string. If sessionid is NULL, then the session is assumed
279 -- to be the currently attached Triton session. If the specified attribute
280 -- does not exist, error is thrown. This operation requires MODIFY_ATTRIBUTE
281 -- privilege. It can only be performed if attached to a Triton session.
282
283 PROCEDURE delete_attribute (namespace IN VARCHAR2,
284 attribute IN VARCHAR2);
285
286 -- This operation updates the last authentication time for the session as
287 -- the current time. If sessionid is NULL, it is assumed to be the session
288 -- identifier of the currently attached Triton session. sessionid parameter
289 -- is optional and default value of this parameter is NULL. This operation
290 -- requires MODIFY_SESSION privilege.
291
292 PROCEDURE reauth_session (sessionid IN RAW DEFAULT NULL);
293
294 -- Sets the inactivity timeout (in minutes) for the session specified by
295 -- sessionid. Inactivity timeout value represent the maximum period of
296 -- inactivity allowed before the session can be terminated and resource
297 -- be reclaimed. If session has exceeded more time than inactivity timeout
298 -- since last update it is available for termination. Trying to set
299 -- negative value will throw error. If invalid session is specified or
300 -- the session does not exist, error is thrown. Default value for sessionid
301 -- is NULL, meaning currently attached Triton session. O value for the
302 -- timeout means infinite, i.e session will never expire due to inactivity.
303 -- This operation requires MODIFY_SESSION privilege.
304
305 PROCEDURE set_inactivity_timeout (time IN NUMBER,
306 sessionid IN RAW DEFAULT NULL);
307
308 -- Set the cookie for the session specified by sessionid. The cookie has
309 -- to be unique string. Maximum allowed length for cookie is 1024 char. If
310 -- a cookie already exists for the session, the new cookie value replaces
311 -- the old value. If the specified session does not exist or the cookie is
312 -- not unique among all the Triton sessions, then error is thrown. Default
313 -- value for sessionid is NULL, meaning currently attached Triton session.
314 -- This operation requires MODIFY_SESSION privilege.
315
316 PROCEDURE set_session_cookie (cookie IN VARCHAR2,
317 sessionid IN RAW DEFAULT NULL);
318
319 -- Get SID for the specified cookie. This operation does not require any
320 -- additional privilege. If no session with specified cookie exist, error
321 -- is thrown.
322 PROCEDURE get_sessionid_from_cookie (cookie IN VARCHAR2,
323 sessionid OUT NOCOPY RAW);
324
325 -- Adds the global callback procedure for the session event specified by
326 -- event_type. The schema of the callback procedure needs to be specified.
327 -- callback_package is optional parameter and needs to be specified only
328 -- if the callback procedure is in a package. Existance check for the
329 -- procedure is done for this operation. If the callback procedure does not
330 -- exist error is thrown. If invalid event type is specified error is thrown.
331 -- Adding the global callback, enables the callback procedure for execution.
332 -- More than one callback procedure can be added for same session event.
333 -- If more than one callback is added for the same session event, they are
334 -- executed in according to their registartion sequence, i.e. the callback
335 -- proecdure that was registered first, is executed first.
336
337 PROCEDURE add_global_callback (event_type IN PLS_INTEGER,
338 callback_schema IN VARCHAR2,
339 callback_package IN VARCHAR2,
340 callback_procedure IN VARCHAR2);
341
342 -- Deletes the global callback procedure for the session event specified by
343 -- event_type. If callback procedure is not specified, all callback
344 -- procedures associated with this global callback are deleted. If invalid
345 -- event type is specified error is thrown.
346
347 PROCEDURE delete_global_callback(event_type IN PLS_INTEGER,
348 callback_schema IN VARCHAR2 DEFAULT NULL,
349 callback_package IN VARCHAR2 DEFAULT NULL,
350 callback_procedure IN VARCHAR2 DEFAULT NULL);
351
352 -- Enables or disables the global callback for the session event specified by
353 -- event_type. enable specifies if the global callback is to be enabled or
354 -- disabled. Default value is true, meaning enable. If no callback procedure
355 -- is specified all callback procedures associated with the global calbback
356 -- are enabled. If invalid even type is specified error is thrown.
357
358 PROCEDURE enable_global_callback(event_type IN PLS_INTEGER,
359 enable IN BOOLEAN DEFAULT TRUE,
360 callback_schema IN VARCHAR2 DEFAULT NULL,
361 callback_package IN VARCHAR2 DEFAULT NULL,
362 callback_procedure IN VARCHAR2 DEFAULT NULL);
363
364 END DBMS_XS_SESSIONS;
[Home] [Help]