1.10 Managing Session State and User Preferences

A session is a logical construct that establishes persistence (or stateful behavior) across page views. Each session is assigned a unique ID, which the Application Express engine uses to store and retrieve an application's working set of data (or session state) before and after each page view. Sessions persist in the database until purged.

Topics:

See Also:

"Managing Session State" in Oracle Application Express Application Builder User's Guide and "Managing Session State"

1.10.1 Managing Session State

A session establishes persistence (or stateful behavior) across page views. You can review session details for the current session or for recent sessions. You can also purge the current session state or purge sessions based on their age.

Topics:

See Also:

"What Is a Session?" in Oracle Application Express Application Builder User's Guide

1.10.1.1 Removing Session State After Reviewing Session Details

You can determine whether to remove existing sessions by first reviewing session details. From the Session Details page, you can remove the session record or session state.

To view session details and remove session state:

  1. Log in to Oracle Application Express. See "Logging In To Oracle Application Express" in Oracle Application Express Application Builder User's Guide.

    The Workspace home page appears.

  2. Click the Administration icon.

  3. On the Administration page, click Manage Service.

  4. Under Manage Meta Data, click Session State.

  5. Click Recent Sessions with Drill-Down to Session Details.

  6. You can customize the appearance of the page using the Search bar at the top of the page. See "Customizing Interactive Reports" in Oracle Application Express Application Builder User's Guide.

  7. To view session details, select the session ID.

    The Session Details page appears.

  8. Click one of the following buttons:

    • Remove State clears the session data from the session state tables (including collections data) but does not remove the session record. Removing a session is a good approach for developers during debugging.

      This is the equivalent of clearing session state for the current session using the Clear Cache argument value SESSION in the f?p URL. This option might also be used by developers during debugging.

    • Remove Session removes the record of the session from the SESSIONS table along with the session state (including collections data) associated with the session.

      Any user using a session that has removed is no longer able to use the session and is prompted to re-authenticate upon their next page request (in most situations). This option can be used by administrators who must ensure a specific user can no longer access an Oracle Application Express application.

See Also:

"Debugging an Application" in Oracle Application Express Application Builder User's Guide

1.10.1.2 Viewing Session State for the Current Session

To view session state for the current or recent sessions:

  1. Log in to Oracle Application Express. See "Logging In To Oracle Application Express" in Oracle Application Express Application Builder User's Guide.

    The Workspace home page appears.

  2. Click the Administration icon.

  3. On the Administration page, click Manage Service.

  4. Under Manage Meta Data, click Session State.

  5. Click Report Session State for Current Session.

  6. You can customize the appearance of the page using the Search bar at the top of the page. See "Customizing Interactive Reports" in Oracle Application Express Application Builder User's Guide.

See Also:

"Removing Session State After Reviewing Session Details"

1.10.1.3 Purging Sessions by Age

To purge existing sessions by age:

  1. Log in to Oracle Application Express. See "Logging In To Oracle Application Express" in Oracle Application Express Application Builder User's Guide.

    The Workspace home page appears.

  2. Click the Administration icon.

  3. On the Administration page, click Manage Service.

  4. Under Manage Meta Data, click Session State.

  5. Click Purge sessions by Age.

  6. Make a selection from the Sessions older than list.

  7. Click one of the following buttons:

    • Purge Sessions purges existing sessions by the age you selected.

    • Report Sessions generates a report detailing the total number of sessions for the workspace, the number of users, and the number of old sessions.

See Also:

"Viewing Session State" in Oracle Application Express Application Builder User's Guide

1.10.1.4 Purging Session State for the Current Session

To purge session state for the current session:

  1. Log in to Oracle Application Express. See "Logging In To Oracle Application Express" in Oracle Application Express Application Builder User's Guide.

    The Workspace home page appears.

  2. Click the Administration icon.

  3. On the Administration page, click Manage Service.

  4. Under Manage Meta Data, click Session State.

  5. Click Purge Session State for Current Session.

  6. Click one of the following buttons:

    • View Session State - Displays information about the current session.

    • Purge Session State - Resets the session state for the current session.

1.10.2 Managing User Preferences

You can use preferences to store values for a specific Application Express user across distinct sessions. Once set, these preferences can be removed programmatically or manually. You can set user preferences by creating a page process, by the calculation of a preference Item Source Value, or programmatically by using a PL/SQL API.

Topics:

1.10.2.1 Viewing Preferences by User

To view the preferences by user:

  1. Log in to Oracle Application Express. See "Logging In To Oracle Application Express" in Oracle Application Express Application Builder User's Guide.

    The Workspace home page appears.

  2. Click the Administration icon.

  3. On the Administration page, click Manage Service.

  4. Under Manage Meta Data, click Session State.

  5. Click Preferences by User.

    The Preferences by User page appears.

  6. You can customize the appearance of the page using the Search bar at the top of the page. See "Customizing Interactive Reports" in Oracle Application Express Application Builder User's Guide.

1.10.2.2 Viewing Current User Preferences

To view current user preferences:

  1. Log in to Oracle Application Express. See "Logging In To Oracle Application Express" in Oracle Application Express Application Builder User's Guide.

    The Workspace home page appears.

  2. Click the Administration icon.

  3. On the Administration page, click Manage Service.

  4. Under Manage Meta Data, click Session State.

  5. Click Report Current User Preferences.

    The Current user Preferences page appears.

  6. You can customize the appearance of the page using the Search bar at the top of the page. See "Customizing Interactive Reports" in Oracle Application Express Application Builder User's Guide.

1.10.2.3 Purging Preferences for a Specific User

You can purge preferences for a specific user on the Purge Preferences page.

To purge preferences for a specific user:

  1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition" in Oracle Application Express Application Builder User's Guide.

  2. Click the Administration icon.

  3. On the Administration page, click Manage Service.

  4. Under Manage Meta Data, click Session State.

  5. Click Purge preferences by User.

    The Purge Preferences page appears.

  6. Select a specific user and click Report.

    A report appears at the bottom of the page.

  7. To purge the displayed user preferences, click Purge User Preferences.

1.10.2.4 Purging Current User Preferences

To purge preferences for the current user:

  1. Log in to Oracle Application Express. See "Logging In To Oracle Application Express" in Oracle Application Express Application Builder User's Guide.

    The Workspace home page appears.

  2. Click the Administration icon.

  3. On the Administration page, click Manage Service.

  4. Under Manage Meta Data, click Session State.

  5. Click Purge Preferences for Current User.

    The Purge Preferences page appears.

  6. Select a user and click Report.

  7. To purge preferences, click Purge User Preferences.

1.10.2.5 Setting User Preferences

You can set user preferences within your application through the creation of a page process, by creating a preference item, or programmatically.

Topics:

1.10.2.5.1 Setting User Preferences Using a Page Process

To set user preference values by creating a page process:

  1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition" in Oracle Application Express Application Builder User's Guide.

  2. Access the Create Page Process Wizard:

    • Tree view- Under the appropriate event, locate Processes. Right-click and select Create.

    • Component view - Under Processes, click the Create icon.

  3. For process category, select Session State and click Next.

  4. For the process type, select Reset Preferences (remove all preferences for current user) and click Next.

  5. Specify a name, sequence, and processing point and click Next.

  6. Follow the on-screen instructions and click Create Process.

1.10.2.5.2 Setting the Source of an Item Based on a User Preference

You can set the source of an item based on a user preference by defining the item source type as Preference.

To define the source of item based on a user preference:

  1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition" in Oracle Application Express Application Builder User's Guide.

  2. Access the Create Page Item Wizard:

    • Tree view- Under Page Rending, expand Regions, right-click Items, and select Create Page Item.

    • Component view - Component view - Under Items, click the Create icon.

  3. For the item type, select Hidden and click Next.

  4. For Hidden Item Type, select one of the following and click Next:

    • Hidden - A hidden item is exposed in the HTML form but not displayed.

    • Hidden and Protected - A hidden and protected item is also exposed in the HTML form but not displayed. However, its value cannot be changed when the page is posted.

  5. Specify the item name, sequence, and region and click Next.

  6. For Source, select Source Type of Preference, enter the appropriate Source Value, and click Next. If the item source is null the default value is used.

    To learn more about a specific field, see item Help.

  7. Click Create Item.

1.10.2.5.3 Setting User Preferences Programmatically

To set or reference user preferences programmatically, you must use a PL/SQL API. User-level caching is available programmatically. You can use the SET_PREFERENCE procedure to set a user level preference called NAMED_PREFERENCE. For example:

APEX_UTIL.SET_PREFERENCE(
 p_preference=>'NAMED_PREFERENCE',
 p_value =>:ITEM_NAME);

You can reference the value of a user preference using the function GET_PREFERENCE. For example:

NVL(APEX_UTIL.GET_PREFERENCE('NAMED_PREFERENCE'),15)

In the previous example, the preference would default to the value 15 if the preference contained no value.

See Also:

GET_PREFERENCE Function and SET_PREFERENCE Procedure in Oracle Application Express API Reference

1.10.2.6 Removing User Preferences Programmatically

To remove user preferences programmatically, you must use a PL/SQL API. You can use the REMOVE_PREFERENCE procedure to remove a user level preference called NAMED_PREFERENCE. For example:

APEX_UTIL.REMOVE_PREFERENCE(
p_preference=>'NAMED_PREFERENCE');

1.10.2.7 Resetting User Preferences Using a Page Process

You can reset user preferences by creating a page process and selecting the Reset Preferences process type.

To reset user preferences using a page process:

  1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition" in Oracle Application Express Application Builder User's Guide.

  2. Access the Create Page Process Wizard:

    1. Tree view- Under the appropriate event, locate Processes. Right-click and select Create Process.

    2. Component view - Under Processes, click the Create icon.

  3. For the process category, select Session State and click Next.

  4. For the process type, select Reset Preferences (remove all preferences for current user) and click Next.

  5. Specify a name, sequence, and processing point and click Next.

  6. Follow the on-screen instructions.

  7. Click Create Process.