Understanding Oracle APEX Session State Part 2

As promised I am presenting you with part 2 of APEX Sessions State. In part 1 we saw we can use session state to pass values within our application from one page to another or to the database. We can also manage this session state. We can reference, set, clear and even clone session state values.

Referencing Session State

We can reference item values stored in session state in regions, computations, processes, validations, and branches. An item can be a field, a text area, a password, a select list, or a checkbox.

The following table describes the supported syntax for referencing item values.

Setting Session State

We can set the session state in various ways, the most obvious one is submit (page). But we can also use bind variables, computations or setting through the url (f?p syntax).

• Form submission: when we submit a form, the APEX engine automatically stores the values of the fields on the page (we saw this in Part 1).

• Bind variables: we can use this in SQL or PL/SQL to reference the session state of a specified item: select * from employees where last_name like ‘%’ || :P1_LAST_NAME || ‘%’

• Computations: we can use computations to set the value of an item: Set up a computation with for instance a PL/SQL function body: begin :last_page := nvl(:current_page,:app_page_id); :current_page := :app_page_id; return :last_page; end;

• Use f?p syntax to link to pages and set item values: We can create links to other pages and by using the f?p syntax we can set values for items on the target page. First remember the syntax: f?p=App:Page:Session:Request:Debug:ClearCache:itemNames:itemValues:PrinterFriendly

  We can see the 2 references itemNames and itemValues. By setting these we can set the values of the items. itemNames is a comma delimited list of item names and the itemValues represents the corresponding values.

One thing more to mention, we can also control how items write the session state:

• Per Request (Memory only): Do not save session state in the database. State is only available when processing the current request. This is the default for Form Region items.

• Per Session (Disk): Maintain for each session by storing the value in the database, to access it across requests.

• Per User (Disk): Value is saved in a user attribute repository and it is also available for later APEX sessions.

Please remember from Part 1 when session values are set and when you can access them.

Clear session state

Again there are several ways to clear the sessions state:

• Using f?p syntax: Remember the url syntax? We also have a ClearCache reference. When we place an item name in that reference, that item will be set to null. f?p=100:5:&APP_SESSION.::NO:P5_ITEM In this case P5_ITEM is set to null. We can even do this for entire pages: f?p=100:5:&APP_SESSION.::NO:RP,6,7 This will navigate to page 5, reset pagination on page 5 (RP) and clear session cache for page 6 and 7. We can take it a step further and clear cache for the entire app: f?p:App:Page:Session::NO:APP by using the APP keyword. Same for clearing a session by using the SESSION keyword.

• Call APEX_UTIL.CLEAR_APP_CACHE: You can call this from another application to clear the app completely.

Session Cloning

I know this is rarely used, but we do have this possibility. We can use this to create a new session in a new browser window and copy all values from the original APEX session. In older APEX versions the same session would be shared by all browser tabs, resulting in unpredictable results. Now in newer versions of APEX the developer can give the option to the user to open a new tab and specify the REQUEST as APEX_CLONE_SESSION. Example: f?p=&APP_ID.:&APP_PAGE_ID.:&APP_SESSION.:APEX_CLONE_SESSION

Beware: when the user logs out of one session, all associated sessions will be logged out as well.

Manage session state

As a developer we have the possibility to view and manage session state in the applications we build. I briefly showed the Runtime Developer Toolbar in Part 1. When we run an application from the builder the toolbar will be visible at the bottom of any editable page.

To view a session state, click on Session and then View Session State.

The session page appears and from here we can choose to see the session state of various options:

We can see in above image the values for the 2 page items. We can even see the status. So, remember, this is the value of the item in session on the database after submit, not the screen value.

In the previous image we can also see something called Session Overrides. This will open up the following screen:

From here we have the option to override some specific options, for instance the application language or the theme. This can be useful in certain situations.

Built-in substitution strings

Oracle APEX features a whole list of substitution strings which we can use for referencing states about the application. Well known are APP_ID, APP_SESSION, APP_USER, REQUEST. But there are many more.

Passing values dynamically

So far we have seen a few option on how to set session state. But in some situations we want to dynamically set the session state (so not on submit). In Part 1 I already mentioned the prepare_url function. We can use this function in PL/SQL to dynamically pass our field values, even when we don’t submit first.

So let’s take a closer look into this function.

APEX_UTIL.PREPARE_URL (
    p_url                    IN VARCHAR2,
    p_url_charset            IN VARCHAR2 default null,
    p_checksum_type          IN VARCHAR2 default null,
    p_triggering_element     IN VARCHAR2 default 'this'
    p_plain_url              IN BOOLEAN  default false 
RETURN VARCHAR2;

An example when using this function:

DECLARE
    l_url varchar2(2000);
    l_app number := v('APP_ID');
    l_session number := v('APP_SESSION');
BEGIN
    l_url := APEX_UTIL.PREPARE_URL(
        p_url => 'f?p=' || l_app || ':1:'||l_session||'::NO::P1_ITEM:xyz',
        p_checksum_type => 'SESSION');
END;

By using substitution we can pass the value of any item to the url.

Of course it wouldn’t be Oracle if they didn’t give us another option:

FUNCTION GET_URL (
    p_application        IN VARCHAR2 DEFAULT NULL,
    p_page               IN VARCHAR2 DEFAULT NULL,
    p_session            IN NUMBER   DEFAULT APEX.G_INSTANCE,
    p_request            IN VARCHAR2 DEFAULT NULL,
    p_debug              IN VARCHAR2 DEFAULT NULL,
    p_clear_cache        IN VARCHAR2 DEFAULT NULL,
    p_items              IN VARCHAR2 DEFAULT NULL,
    p_values             IN VARCHAR2 DEFAULT NULL,
    p_printer_friendly   IN VARCHAR2 DEFAULT NULL,
    p_trace              IN VARCHAR2 DEFAULT NULL,       
    p_triggering_element IN VARCHAR2 DEFAULT 'this',
    p_plain_url          IN BOOLEAN DEFAULT FALSE )
    RETURN VARCHAR2;

Notice the 2 parameters for items and values? Another way to set them to session state before rendering the url!

SELECT APEX_PAGE.GET_URL (
            p_page   => 1,
            p_items  => 'P1_X,P1_Y',
            p_values => 'somevalue,othervalue' ) f_url_1
FROM DUAL

This is the end of Part 2. I hope it helped you understand session state and how to use it in Oracle APEX.

Pieter van den Broek

Senior Oracle Consultant and APEX enthusiast