About Manipulating the Application Session State

This section contains:

About Using Namespace Templates to Create Namespaces

An application uses a namespace to store application defined attribute-value pairs. Often, an application needs to use the same namespace across different application sessions. A namespace template provides a way to define and initialize a namespace.

A namespace template defines the namespace and its properties. It is used to initialize the namespace in an application session. The namespace name must be the same as the template that defines it.

This section contains:

Components of a Namespace Template

A namespace template includes the following:

Name of the namespace

The name of the application namespace uniquely identifies the namespace. This name is used when creating the namespace in an application session.
Namespace handler

The namespace handler is called when an attribute value is set or retrieved. Specifying a handler is optional.

Namespaces can be associated with an event handling function. The server invokes this function whenever an operation on an attribute registered for event handling is performed. The event handling function is provided with the attribute name, attribute value, and the event code as arguments. For example:
```
FUNCTION event_handling_function_name(
         session_id IN RAW,
         namespace  IN VARCHAR2,
         attribute  IN VARCHAR2,
         old_value  IN VARCHAR2,
         new_value  IN VARCHAR2,
         event_code IN PLS_INTEGER)
RETURNS PLS_INTEGER;
```
Attribute List

The attribute list includes the attributes defined for the namespace. These attributes are created in the session when the namespace is created.

You can specify the following optional data for attributes:
- The default value
  
  The attribute is initialized with the default value when the namespace is created in the application session. The default value and the event types FIRSTREAD_EVENT and FIRSTREAD_PLUS_UPDATE_EVENT cannot exist at the same time.
- Event types
  
  You can specify the following event types for an attribute:
  - FIRSTREAD_EVENT
    
    Specify this event type to call the namespace handler when an attribute whose value has not been set is read for the first time. You can specify this event type only if a default value has not been set for the attribute.
  - UPDATE_EVENT
    
    Specify this event type to call the namespace handler when the attribute value is updated.
  - FIRSTREAD_PLUS_UPDATE_EVENT
    
    Specify this event type to call the namespace handler when an attribute whose value has not been set is read for the first time, or when its value is updated. You can specify this event type only if a default value has not been set for the attribute.
Namespace ACL

The privilege model for namespace operations. Namespace operations are protected by the ACL set on the template. By default, NS_UNRESTRICTED_ACL is set on a template, which allows unrestricted operation on namespaces created from the templates.

About Namespace Views

You can find information about namespace templates, namespace template attributes, and namespace attributes in current and all application sessions by querying these data dictionary views:

Creating a Namespace Template for an Application Session

You can create a namespace template using the XS_NAMESPACE.CREATE_TEMPLATE procedure in PL/SQL or the createNamespace method of the Session interface in Java.

Example: Creating a Namespace Template shows how to create the namespace template ns1 for an application session. It defines the attributes for this namespace using the list of attributes attrs. Because this namespace template has NS_UNRESTRICTED_ACL set on the template, this allows unrestricted operation on namespaces created from the template.

The calling user must have the ADMIN_ANY_SEC_POLICY application privilege, which allows it to administer namespace templates and attributes.

In this example, the function FN1 will be called with event type XS_NAMESPACE.UPDATE_EVENT whenever the attr1 is updated. Similarly, the function FN1 will be called with event type XS_NAMESPACE.FIRSTREAD_PLUS_UPDATE_EVENT when the attribute attr2 is read for the first time or its value is updated. The template does not specify event handling for the attribute attr3.

Example: Creating a Namespace Template

DECLARE
  attrs XS$NS_ATTRIBUTE_LIST;
BEGIN
  attrs := XS$NS_ATTRIBUTE_LIST();
  attrs.extend(3);

  attrs(1) := XS$NS_ATTRIBUTE('attr1','value1',
    XS_NAMESPACE.UPDATE_EVENT);
  attrs(2) := XS$NS_ATTRIBUTE('attr2',null,
    XS_NAMESPACE.FIRSTREAD_PLUS_UPDATE_EVENT);
  attrs(3) := XS$NS_ATTRIBUTE('attr3','value3');

  SYS.XS_NAMESPACE.CREATE_TEMPLATE(name=>'ns1',
                               description=>'namespace template 1',
                               attr_list=>attrs,
                               schema=>'SCOTT',
                               package=>'PKG1',
                               function=>'FN1',
                               acl=>'SYS.NS_UNRESTRICTED_ACL');
END;
/

See Also:

CREATE_TEMPLATE Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java createNamespace method (in Javadoc format)
Example: How to Create a Namespace in Java for information about a Java example of this task

Initializing a Namespace in an Application Session

A namespace can be initialized, using a namespace template, during any of the following events, as described in this section:

This section contains:

Initializing a Namespace When the Session Is Created

When you create an application session using the DBMS_XS_SESSIONS.CREATE_SESSION procedure in PL/SQL or the createSession method of the XSSessionManager class in Java, you can specify a list of namespaces to initialize.

Example: Initializing Namespaces When Creating an Application Session shows how to initialize two namespaces, ns1 and ns2, while creating an application session.

If you specify namespaces during creation of the session, the caller is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or be granted the ADMIN_NAMESPACE system privilege.

Note: The namespaces used in Example: Initializing Namespaces When Creating an Application Session must already have corresponding namespace templates defined.

Example: Initializing Namespaces When Creating an Application Session

DECLARE
  nsList DBMS_XS_NSATTRLIST;
  sessionid RAW(16);
BEGIN
    nsList := DBMS_XS_NSATTRLIST(DBMS_XS_NSATTR('ns1'),DBMS_XS_NSATTR('ns2'));
    SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid, FALSE, FALSE, nsList);
END;
/

See Also:

CREATE_SESSION Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java createSession method (in Javadoc format)
Example: How to Create a Real Application Security Session in Java for information about a Java example of this task

Initializing a Namespace When the Session Is Attached

When you attach the session using the DBMS_XS_SESSIONS.ATTACH_SESSION procedure in PL/SQL or using the attachSession method of the XSSessionManager class in Java, you can specify a list of namespaces to initialize.

Example: Initializing Namespaces When Attaching an Application Session shows how to initialize two namespaces, ns1 and ns2, while attaching an application session.

If you specify namespaces, then the user is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or the ADMIN_NAMESPACE system privilege.

Note: The namespaces used in Example: Initializing Namespaces When Attaching an Application Session must already have corresponding namespace templates defined.

Example: Initializing Namespaces When Attaching an Application Session

DECLARE
  nsList DBMS_XS_NSATTRLIST;
  sessionid RAW(16);
BEGIN
    nsList := DBMS_XS_NSATTRLIST(DBMS_XS_NSATTR('ns1'),DBMS_XS_NSATTR('ns2'));
    SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
    SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid, NULL, NULL, NULL, NULL, nsList);
END;
/

See Also:

ATTACH_SESSION Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java attachSession method (in Javadoc format)
Example: How to Attach a Real Application Security Session in Java for information about a Java example of this task

Initializing a Namespace When a Named Application User Is Assigned to an Anonymous Application Session

When you assign an application user to an application session using the DBMS_XS_SESSIONS.ASSIGN_USER procedure in PL/SQL or the assignUser method of the XSSessionManager class in Java, you can specify a list of namespaces to initialize.

If you specify namespaces, then the user is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or ADMIN_NAMESPACE system privilege.

Example: Initializing Namespaces When Assigning an Application User to an Application Session shows how to initialize two namespaces, ns1 and ns2, while assigning an application user to an application session.

Note: The namespaces used in Example: Initializing Namespaces When Assigning an Application User to an Application Session must already have corresponding namespace templates defined.

Example: Initializing Namespaces When Assigning an Application User to an Application Session

DECLARE
  sessionid RAW(30);
  nsList DBMS_XS_NSATTRLIST;
BEGIN
  nsList := DBMS_XS_NSATTRLIST(DBMS_XS_NSATTR('ns1'),DBMS_XS_NSATTR('ns2'));
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('XSGUEST', sessionid);
  SYS.DBMS_XS_SESSIONS.ASSIGN_USER(username => 'lwuser2',
                               sessionid => sessionid,
                               namespaces => nsList);
END;
/

See Also:

ASSIGN_USER Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java assignUser method (in Javadoc format)
Example: How to Assign an Application User to a Session in Java for information about a Java example of this task

Initializing a Namespace When the Application User Is Switched in an Application Session

When you switch an application user in an application session using the DBMS_XS_SESSIONS.SWITCH_USER procedure in PL/SQL or using the switchUser method of the Session interface in Java, you can specify a list of namespaces to initialize.

If you specify namespaces, then the user is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or the ADMIN_NAMESPACE system privilege.

Note:

To enable the switch from lwuser1 to lwuser2 after attaching the session, you must first define lwuser2 as the target user for lwuser1, as follows:

exec XS_PRINCIPAL.ADD_PROXY_USER('lwuser2', 'lwuser1');

Example: Initializing Namespaces When Switching an Application User in an Application Session shows how to initialize two namespaces, ns1 and ns2, while switching an application user in an application session.

Note: The namespaces used in Example: Initializing Namespaces When Switching an Application User in an Application Session must already have corresponding namespace templates defined.

Example: Initializing Namespaces When Switching an Application User in an Application Session

DECLARE
  sessionid RAW(30);
  nsList DBMS_XS_NSATTRLIST;
BEGIN
  nsList := DBMS_XS_NSATTRLIST(DBMS_XS_NSATTR('ns1'),DBMS_XS_NSATTR('ns2'));
 SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
 SYS. DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.SWITCH_USER(username => 'lwuser2',
                               namespaces => nsList);
END;
/

See Also:

SWITCH_USER Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java switchUser method (in Javadoc format)
Example: How to Switch an Application User in a Session in Java for information about a Java example of this task

Initializing a Namespace Explicitly

You can explicitly initialize a namespace in an application session using the DBMS_XS_SESSIONS.CREATE_NAMESPACE procedure in PL/SQL or the createNamespace method of the Session interface in Java.

To execute the DBMS_XS_SESSIONS.CREATE_NAMESPACE procedure, the calling user must have the MODIFY_NAMESPACE application privilege on the namespace or the ADMIN_NAMESPACE system privilege.

Example: Initializing a Namespace Explicitly in an Application Session shows how to explicitly initialize a namespace, ns1, in an application session.

Note: The namespace used in Example: Initializing a Namespace Explicitly in an Application Session must already have a corresponding namespace template defined.

Example: Initializing a Namespace Explicitly in an Application Session

DECLARE
  sessionid RAW(30);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.CREATE_NAMESPACE('ns1');
END;
/

See Also:

CREATE_NAMESPACE Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java createNamespace method (in Javadoc format)
Example: How to Create a Namespace in Java for information about a Java example of this task

Setting Session Attributes in an Application Session

You can set the value of a specific session attribute using the DBMS_XS_SESSIONS.SET_ATTRIBUTE procedure in PL/SQL or the setAttribute method of the SessionNamespace interface method in Java.

The calling user is required to be granted the MODIFY_ATTRIBUTE application privilege on the namespace or the ADMIN_NAMESPACE system privilege.

Note: An attribute can store a string value up to 4000 characters long.

Example: Setting a Namespace Attribute for an Application Session shows how to set a value, val1, for an attribute, attr1, of the application session.

Example: Setting a Namespace Attribute for an Application Session

DECLARE
  sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBS_XS_SESSIONS.CREATE_NAMESPACE('ns1');
  SYS.DBMS_XS_SESSIONS.SET_ATTRIBUTE('ns1', 'attr1', 'val1');
  SYS.DBMS_XS_SESSIONS.DETACH_SESSION;
  SYS.DBMS_XS_SESSIONS.DESTROY_SESSION(sessionid);
END;
/

See Also:

SET_ATTRIBUTE Procedure for more information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java setAttribute method (in Javadoc format)
About Setting a Session Namespace Attribute for information about this task in Java

Getting Session Attributes in an Application Session

You can retrieve the value of a specific session attribute using the DBMS_XS_SESSIONS.GET_ATTRIBUTE procedure in PL/SQL or using the getAttribute method of the SessionNamespace interface method in Java.

The calling user is not required to be granted any privileges to get attributes using the DBMS_XS_SESSIONS.GET_ATTRIBUTE procedure.

Note: If an attribute value has not been set, and the FIRSTREAD_EVENT has been specified for the attribute, then an attempt to read the the attribute value triggers a call to the namespace event handler. The namespace event handler procedure typically sets a value for the attribute, and performs other application-specific processing tasks.

Example: Getting a Namespace Attribute for an Application Session shows how to retrieve an attribute, attr1, of the application session.

Example: Getting a Namespace Attribute for an Application Session

DECLARE
  sessionid RAW(16);
  attrib_out_val VARCHAR2(4000);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.CREATE_NAMESPACE('ns1');
  SYS.DBMS_XS_SESSIONS.SET_ATTRIBUTE('ns1', 'attr1', 'val1');
  SYS.DBMS_XS_SESSIONS.GET_ATTRIBUTE('ns1', 'attr1', attrib_out_val);
  SYS.DBMS_XS_SESSIONS.DETACH_SESSION;
  SYS.DBMS_XS_SESSIONS.DESTROY_SESSION(sessionid);
END;
/

See Also:

GET_ATTRIBUTE Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java getAttribute method (in Javadoc format)
Getting a Session Namespace Attribute for information about this task in Java

Creating Custom Attributes in an Application Session

You can create custom attributes in a namespace using the DBMS_XS_SESSIONS.CREATE_ATTRIBUTE procedure in PL/SQL or the createAttribute method of the SessionNamespace interface method in Java.

Custom attributes differ from template attributes. Template attributes are part of the namespace template, and are automatically created in the session when the namespace is created. Custom attributes are programmatically created in a namespace, using the CREATE_ATTRIBUTE procedure.

The calling application is required to be granted the MODIFY_ATTRIBUTE application privilege on the namespace or the ADMIN_NAMESPACE system privilege.

Example: Creating a Custom Namespace Attribute for an Application Session shows how to create a custom attribute, customattr, in a namespace of the application session.

Example: Creating a Custom Namespace Attribute for an Application Session

DECLARE
  sessionid RAW(16);
  attrib_out_val VARCHAR2(4000);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.CREATE_NAMESPACE('ns1');
  SYS.DBMS_XS_SESSIONS.CREATE_ATTRIBUTE('ns1','customattr','default_value_custom',NULL);
  SYS.DBMS_XS_SESSIONS.SET_ATTRIBUTE('ns1','customattr','newvalue');
  SYS.DBMS_XS_SESSIONS.GET_ATTRIBUTE('ns1', 'customattr', attrib_out_val);
  SYS.DBMS_XS_SESSIONS.DETACH_SESSION;
  SYS.DBMS_XS_SESSIONS.DESTROY_SESSION(sessionid);
END;
/

See Also:

CREATE_ATTRIBUTE Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java createAttribute method (in Javadoc format)
Example: How to Create a Session Namespace Attribute in Java for information about a Java example of this task

Deleting a Namespace in an Application Session

You can delete a namespace and all attributes identified by it from an application session using the DBMS_XS_SESSIONS.DELETE_NAMESPACE procedure in PL/SQL or the deleteAttribute method of the SessionNamespace interface method in Java.

The calling user must have the MODIFY_NAMESPACE application privilege on the namespace or the ADMIN_NAMESPACE system privilege.

Example: Deleting a Namespace in an Application Session shows how to delete a namespace ns1 from an application session.

Example: Deleting a Namespace in an Application Session

DECLARE
  sessionid RAW(16);
  out_value VARCHAR2(4000);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.CREATE_NAMESPACE('ns1');
  SYS.DBMS_XS_SESSIONS.SET_ATTRIBUTE('ns1', 'attr1', 'val1');
  SYS.DBMS_XS_SESSIONS.GET_ATTRIBUTE('ns1', 'attr1', out_value);
  SYS.DBMS_XS_SESSIONS.DELETE_NAMESPACE('ns1');
  SYS.DBMS_XS_SESSIONS.DETACH_SESSION;
  SYS.DBMS_XS_SESSIONS.DESTROY_SESSION(sessionid);
END;
/

See Also:

DELETE_NAMESPACE Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java deleteNamespace method (in Javadoc format)
Example: How to Delete a Namespace in Java for information about a Java example of this task

Enabling Application Roles for a Session

You can enable only directly granted regular application roles of an application session user using the DBMS_XS_SESSIONS.ENABLE_ROLE procedure in PL/SQL or the enableRole method of the Session interface in Java.

The DBA_XS_SESSION_ROLES dynamic data dictionary view lists application roles enabled in all application sessions. The V$XS_SESSION_ROLES dynamic data dictionary view lists application roles enabled in the currently attached application session.

Example: Enabling a Role in an Application Session shows how to enable a role in an application session.

Example: Enabling a Role in an Application Session

DECLARE
  sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.ENABLE_ROLE('auth1_role');
  SYS.DBMS_XS_SESSIONS.DETACH_SESSION;
  SYS.DBMS_XS_SESSIONS.DESTROY_SESSION(sessionid);
END;
/

See Also:

ENABLE_ROLE Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java enableRole method (in Javadoc format)
Example: How to Enable a Real Application Security Application Role in Java for information about a Java example of this task

Disabling Application Roles for a Session

You can disable application roles for a specific session using the DBMS_XS_SESSIONS.DISABLE_ROLE procedure in PL/SQL or the disableRole method of the Session interface in Java.

Example: Disabling a Role in an Application Session shows how to disable a role in an application session.

Example: Disabling a Role in an Application Session

DECLARE
  sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.ENABLE_ROLE('auth1_role');
  SYS.DBMS_XS_SESSIONS.DISABLE_ROLE('auth1_role');
  SYS.DBMS_XS_SESSIONS.DETACH_SESSION;
  SYS.DBMS_XS_SESSIONS.DESTROY_SESSION(sessionid);
END;
/

See Also:

DISABLE_ROLE Procedure for information about the syntax of this PL/SQL procedure
Oracle AI Database Real Application Security Java API Reference for information about the syntax of the Java disableRole method (in Javadoc format)
Example: How to Disable a Real Application Security Application Role in Java for information about a Java example of this task