APEX Behind the Scenes by Scott Spendolini

APEX Behind the
Scenes
Scott Spendolini
President & Co-Founder

Copyright © 2010 Sumneva - All Rights Reserved - http://sumneva.com - info@sumneva.com
Welcome
2

ABOUT THE PRESENTER
• Scott Spendolini
• scott@sumneva.com
• @sspendol
• Ex-Oracle Employee of 10 years
• Senior Product Manager for Oracle APEX
from 2002 through 2005
• Founded Sumner Technologies
in October 2005
• Co-Founded Sumneva in January 2010
• Oracle Ace Director
• Co-Author,
Pro Oracle Application Express
• “Scott” on OTN Forums
3

ABOUT SUMNEVA
4
• Specializing in Oracle Application Express
• Training
• Instructor Led On-Site or Online
• Private & Public
• Consulting
• Anything APEX-related
• Solutions/Products
• sumnevaSERT
• sumnevaFramework

AGENDA
• Overview
• Primer
• Behind the Scenes
• Summary
5

Overview
6

OVERVIEW
7
• APEX is an amazing development environment
• Few others are as fast & as robust
• But, do you really know what happens once you click
submit?

• APEX is not magic
• There’s a method to everything that goes on
• Most of which is more basic
than you may think
• We’ll dispel some of the
“magic” today, so that you
truly understand how this
amazing technology works
BEHIND THE CURTAIN
8

KISS: KEEP IT SIMPLE, STUPID!
• For this session, we’re going to focus on the
internals of APEX, not the complexity of the
application
• This, our example will be extremely simple
• 2 Pages
• Login Page
• Blank Page
9

Primer
10

PRIMER
11
• Before we begin, let’s review a couple of basic
concepts
• Terminology
• HTML Form Basics
• wwv_ﬂow Overview

Terminology
12

TERMINOLOGY
13
• Much of APEX’s internal APIs and variables still use the
older names
• Most of which is based on
Oracle Flows terminology
• Subsequent versions of APEX
include APIs & variables that start
with the APEX_ preﬁx
• Thus, to understand the internals
of APEX, you need to be able
to map legacy term to
modern ones

TERMINOLOGY
14
Legacy Name Modern Name
Company Workspace
Flow Application
Step Page
Plug Region
Instance Session
Request Request
Debug Debug

HTML Form Basics
15

HTML FORM BASICS
16
• HTML Forms are used to pass data to a server
• Used by all web pages on the internet
• Regardless of the underlying technology
• Forms contain items which are passed as parameters
to the form action
• Text Field
• Radio Group
• Select List
• And so on...

• Each HTML Form has to have a form tag and a way
to submit it
• Can optionally have input tags; most have several
• The form tag will have the following attributes:
• Name
• Action
• Method
• ID
HTML FORM BASICS
17

HTML FORM BASICS
• All HTML forms start like this:
18
<form action="form_action.asp" method="post"
name="my_form" id="myForm">
Procedure
Name
HTTP
Method
Form
Name
Form ID

GET VS. POST
19
• All HTTP & HTTPS transactions for every web site
ever fall into one of two categories:
• GET
• POST

GET
• Typically involves passing parameters over the URL to a procedure
• More “usable” than POST
• Can be:
• Bookmarked
• Cached
• Remain in browser history
• Distributed & shared
• Hacked
• In APEX-speak, this is also known as Page Rendering and
handled by wwv_ﬂow.show
20

POST
• When a web page “sends” form data to the server
directly
• Using the attributes of the form to determine which server
process to execute
• Item names will also map to the form process’s input parameters
• Typically used to change or update data on the
server
• Thus, POST requests are never cached
• In APEX-speak, this is also known as Page Processing
and handled by wwv_ﬂow.accept
21

D E M O N S T R A T I O N
GET vs. POST
22

wwv_ﬂow Overview
23

QUESTION
24
• What does “WWV” stand for?
WebView

WWV_FLOW
25
• wwv_ﬂow is essentially APEX
• Contains many global variables, as well as several
functions & procedures
• Some of which you can use, other which are internal only
• We’ll focus on just a couple of them:
• accept
• show

BASIC HTML FORM
26
<form action="form_action.asp" method="post"
name="my_form" id="myForm">
Procedure
Name
HTTP
Method
Form
Name
Form ID

APEX HTML FORM
27
<form action="wwv_flow.accept" method="post"
name="wwv_flow" id="wwvFlowForm">
Procedure
Name
HTTP
Method
Form
Name
Form ID

WWV_FLOW.ACCEPT
• PL/SQL package.procedure that APEX calls when
POSTing pages
• Called for every APEX page that’s submitted
• Contains a number of parameters which are populated based
on a combination of system-deﬁned variables and
what the user enters into the form items
28

APEX_040000 SCHEMA
• A lot can be learned about the internals of APEX by
browsing the APEX_040000 schema
• However, NEVER, EVER, EVER make any changes
to anything here!
• If you want to explore this schema,
its best done on an isolated,
private instance of APEX
• Oracle XE
• VMWare/Virtual Box/etc.
29

APEX
Behind the Scenes
30

The f Procedure
31

THE f PROCEDURE
32
• Let’s start by navigating to our URL:
• http://localhost:8080/apex/f?p=181:1

THE f PROCEDURE
• The string 181:1 is passed to the p parameter of the
f procedure
33
PROCEDURE f
Argument Name Type In/Out Default?
------------------------------ -----------------------
P VARCHAR2 IN DEFAULT
P_SEP VARCHAR2 IN DEFAULT
P_TRACE VARCHAR2 IN DEFAULT
C VARCHAR2 IN DEFAULT
PG_MIN_ROW VARCHAR2 IN DEFAULT
PG_MAX_ROWS VARCHAR2 IN DEFAULT
PG_ROWS_FETCHED VARCHAR2 IN DEFAULT
FSP_REGION_ID VARCHAR2 IN DEFAULT
SUCCESS_MSG VARCHAR2 IN DEFAULT
NOTIFICATION_MSG VARCHAR2 IN DEFAULT
CS VARCHAR2 IN DEFAULT
S VARCHAR2 IN DEFAULT
TZ VARCHAR2 IN DEFAULT
P_LANG VARCHAR2 IN DEFAULT
P_TERRITORY VARCHAR2 IN DEFAULT
181:1

THE f PROCEDURE
• The f procedure will then tokenize the p parameter
into its component parts and call the
wwv_ﬂow.show procedure
34
PROCEDURE SHOW
Argument Name Type In/Out Default?
--------------------------------------------------------------
P_REQUEST VARCHAR2 IN DEFAULT
P_INSTANCE VARCHAR2 IN DEFAULT
P_FLOW_ID VARCHAR2 IN DEFAULT
P_FLOW_STEP_ID VARCHAR2 IN DEFAULT
P_DEBUG VARCHAR2 IN DEFAULT
P_ARG_NAMES TABLE OF VARCHAR2(32767) IN DEFAULT
P_ARG_VALUES TABLE OF VARCHAR2(32767) IN DEFAULT
P_CLEAR_CACHE TABLE OF VARCHAR2(32767) IN DEFAULT
P_BOX_BORDER VARCHAR2 IN DEFAULT
P_PRINTER_FRIENDLY VARCHAR2 IN DEFAULT
P_TRACE VARCHAR2 IN DEFAULT
P_COMPANY NUMBER IN DEFAULT
P_MD5_CHECKSUM VARCHAR2 IN DEFAULT
P_LAST_BUTTON_PRESSED VARCHAR2 IN DEFAULT
P_ARG_NAME VARCHAR2 IN DEFAULT
P_ARG_VALUE VARCHAR2 IN DEFAULT
181
1

wwv_ﬂow.show
35

WWV_FLOW.SHOW
36
• Procedure that handles all APEX page rendering
or GETs
• Called most often by the f?p procedure in the URL
• Also used in Ajax transactions
• The f procedure will decompose p= to its
component parameters and then call
wwv_ﬂow.show

WWV_FLOW.SHOW PARAMETERS
• p_ﬂow_id
• Application ID
• p_ﬂow_step_id
• Page ID
• p_instance
• Session ID
• p_request
• Request
37

• p_debug
• Debug Mode
• “YES” to enable;“NO” or NULL to disable
• p_clear_cache
• Clear Cache & Reset Pagination
38

• p_arg_names
• p_arg_name used when passing a single item
• p_arg_values
• p_arg_value used when passing a single value
• p_printer_friendly
• Printer Friendly mode
• “YES” to enable;“NO” or NULL to disable
39

• p_trace
• When passed “YES”,APEX will generate a SQL trace file
based on the current page view
• Done in the background so that it does not slow down processing
• A SQL trace file will be generated in $ORACLE_BASE/
admin/SID/udump
• The SQL trace file can then be analyzed with TKPROF,
Profiler, SQL Developer or any number of other tools
• Note:You will need filesystem access to get to the trace file;
thus you may need to seek help from your DBA/system admin
40

SAME THING
41
http://localhost/apex/wwv_flow.show?
p_flow_id=181
&p_flow_step_id=2
&p_instance=292381000
&p_arg_names=P2_EMPNO
&p_arg_values=7499
http://localhost/apex/f?
p=181:2:292381000::::P2_EMPNO:7499

wwv_ﬂow.show
42

Page Rendering
43

PAGE RENDERING
• APEX will render a page
ﬁrst by display/render
position
• Multiple components within
the same display/render
position can be sequenced
accordingly
• At any point, any
component can be
conditional and may or
may not render
44

NLS Parameters
45

NLS PARAMETERS
• National Language Settings (NLS) parameters must be
set for each and every page view
• Seems inefﬁcient, but there is no way to guarantee
that an APEX session will be linked to the same database
session from page view to page view
• Thus, we need to set these each and every time
46

NLS PARAMETERS
• Some NLS settings can be managed from within
an APEX application
• Shared Components > Globalization
• All can be set from the value of an APEX item
• Allowing for ﬂexibility between users of the same application
47

NLS PARAMETERS
• Built-in NLS settings will show up in the APEX Debug
mode report at the very top of the report
• If needed, you can also manually set additional
NLS Parameters
48

MANUALLY SETTING NLS PARAMETERS
• For those not available in the Globalization options,
you will need to manually set them via:
• VPD Context
• Part of the Authentication Scheme
• Application Computation
• Before Header
• Application Process
• Before Header
49
EXECUTE IMMEDIATE 'alter session set
nls_date_format=''mm/dd/yyyy'' ';

MANUALLY SETTING NLS PARAMETERS
50
VPD Context
Computation
Process

NLS Parameters
51

Session Management
52

SESSION MANAGEMENT
• After NLS Parameters are set,APEX checks to see if
you are logged in or not
• APEX will also check to see if you are also logged in a
developer in the same workspace as the application
which you are running
• If so, then you will also see the developer’s toolbar:
53

• Debug log of an unauthenticated session vs. an
authenticated session
SESSION MANAGEMENT
54
Unauthenticated Session
Authenticated Session

SESSION MANAGEMENT
55
• By default, this functionality is built in to APEX
and does not need to be enabled
• You can override APEX’s session management, but you
better know what you are doing!
• If you choose to implement your own Page Session
Management, it is controlled via either the Page
Sentry Function or Session Verify Function
in the Authorization Scheme

SESSION MANAGEMENT
• When a session is not valid,APEX will redirect to one
of two places:
• Session Not Valid Page
• If a page is selected here, that page will by default become accessible
by anyone, even if they are not authenticated
• Session Not Valid URL
• Can specify the Built In Login Page or SSO/Portal here, as well
as your own function or URL
56

SESSION MANAGEMENT
57

Session NotValid
58

PAGE SENTRY & SESSION VERIFY
59
• APEX provides the ability to take over session
management entirely
• Page Sentry Function
• Executed before EVERY APEX page view
• Can check any criteria to determine if the session is valid
• Session Verify Function
• Determines whether or not a valid session exists
• Can only use one of these, not both

SESSION MANAGEMENT
60
Page Sentry
Function
Session Verify
Function

Page Sentry Function
61

Authentication
62

AUTHENTICATION SCHEME
• What happens next depends on whether the user is
authenticated or not
63
Authenticated:
Continue to Display Page Requested
Unauthenticated:
Redirect to Login Page deﬁned in the
Authentication Scheme

• Since we are not yet authenticated,APEX will
redirect to the Login Page
• Which will run through the Page Rendering phase
• NLS Parameters
• Page Session Management
• Which will pass this time, as the Login Page will display to an
unauthenticated user
• Computations
• Processes
• Regions
64

Page Components
65

GET USERNAME COOKIE PROCESS
• Process that will check to see if there is an APEX
username stored in the APEX session cookie
• If so, it will set the default value of P101_USERNAME to
this value
66
declare
v varchar2(255) := null;
c owa_cookie.cookie;
begin
c := owa_cookie.get('LOGIN_USERNAME_COOKIE');
:P101_USERNAME := c.vals(1);
exception when others then null;
end;

LOGIN_USERNAME_COOKIE
67
Username
Hostname
DAD
Require SSL
Expiration
Cookie Name

APEX User Cookie
68

DISPLAY REGIONS
69
• After attempting to set the cookie,APEX will render
the regions & items on the page in their
corresponding order

Page Processing
70

PAGE PROCESSING
• APEX will process a page ﬁrst by
process position
• Multiple components within the same
display/render position can be
sequenced accordingly
• At any point, any component can be
conditional and may or may not
render
71

PAGE PROCESSING
• Let’s enter our username & password and click
Login to start processing our page
72

PAGE PROCESSING
• When the Login button is clicked,APEX will POST a
transaction to the server
• We can use Web Developer to see the
parameters it will pass to wwv_ﬂow.accept
73

DISPLAY FORM DETAILS
74
APP_ID
APP_PAGE_ID SESSION_ID
Form Name

wwv_ﬂow.accept
75

WWV_FLOW.ACCEPT
76
• Procedure that handles all APEX page
processing or POSTs
• Have likely seen this before in error messages

WWV_FLOW.ACCEPT PARAMETERS
• p_request
• Typically set by the button clicked on a POST
• Can be passed via the URL in a GET
• But it will only be good for the next page phase
• Can not get the value of p_request in Page Rendering if
the page is submitted/POSTed
77

• p_instance
• Session ID
• Also referred to as :APP_SESSION or :SESSION_ID
• Automatically maintained by APEX
• Can not alter programmatically
78

• p_ﬂow_id
• Application ID
• Also referred to as :APP_ID
• Automatically set by APEX based on which application you’re
running
79

• p_company
• Workspace ID
• Also referred to as :WORKSPACE_ID
• Not typically present in the HTML rendered by APEX
• But is calculated inside the wwv_ﬂow.accept procedure
80

• p_ﬂow_step_id
• Page ID
• Also referred to as :APP_PAGE_ID
• Returns the current Page ID
• Can not be altered otherwise
81

• p_arg_names
• Array used to store the corresponding APEX Item IDs from
an APEX page
• Appears before each and every APEX page item
82

• p_arg_values
• Used to protect hidden items from being manipulated
via JavaScript
• When a hidden & protected item is rendered, there will be a
corresponding p_arg_values item rendered as well
83
<input type="hidden" id="P2_EMPNO" name="p_t01" value="7369" />
<input type="hidden" name="p_arg_values" value="9DDE9C18F8337D..." />

• p_t01 ... p_t100
• Set ofVARCHAR parameters used to receive APEX page
item values
• This is where the “100 item per page” limit comes from
• Which is not accurate, since it’s really 100 enabled items per page
84
<input type="text" id="P1_ITEM" name="p_t01" value="" size="30"
maxlength="4000" class="text_field" />
APEX Item Parameter
Item

• p_v01 ... p_v100
• Set of 100 arrays used to store results from items that
return potentially more than one value
• Multi-select Lists, Shuttle Regions, etc.
85
<select name="p_v01" id="P1_ITEM" size="1" multiple="multiple"
class="multi_selectlist">
Array Item APEX Item

• f01 ... f50
• Group of 50 arrays, typically used in conjunction with
g_f01 ... g_f50
• Most often used with tabular forms & APEX_ITEM API calls
• Name used for PL/SQL; ID used for JavaScript
86
<input type="text" name="f03" size="12" value="" id="f03_0001" />
Array
Name
Array
Element ID

• x01 ... x20
• Group of 20VARCHARs, typically used in conjunction with
the global variables g_x01 ... g_x10
• Difference between the parameter count & global variable count can
be attributed to APEX itself needing extras
• Most often used with Ajax transactions to pass
parameters
87

• p_debug
• When passed “YES”,APEX will run in DEBUG mode
• No value or “NO” will disable DEBUG mode
88

• p_trace
• When passed “YES”,APEX will generate a SQL trace file
based on the current page view
• Done in the background so that it does not slow down processing
• A SQL trace file will be generated in $ORACLE_BASE/
admin/SID/udump
• The SQL trace file can then be analyzed with TKPROF,
Profiler, SQL Developer or any number of other tools
• Note:You will need filesystem access to get to the trace file;
thus you may need to seek help from your DBA/system admin
89

Item Mapping
90

ITEMS
91
• APEX Page Items are named p_t01 through p_t100
• The PX_ITEM_NAME is never directly sent back to the
database
• Used for client-side JavaScript interactions
• Thus, if all APEX pages items are named the same,
then how does it map them to the corresponding
page item in an application when submitting a page?

ITEM MAPPING
• Each APEX page item will have a corresponding
p_arg_names entry:
92
<input type="hidden" name="p_arg_names"
value="8295929934913911" />
<input type="text" id="P101_USERNAME" name="p_t01"
value="admin" size="40" maxlength="100" class="text_field" />
...
<input type="hidden" name="p_arg_names"
value="8296003745913912" />
<input type="password" name="p_t02" size="40" maxlength="100"
value="" id="P101_PASSWORD" class="password"
onkeypress="return submitEnter(this,event)" />

ITEM MAPPING
• p_arg_names values will map back to the internal
item ID in the wwv_ﬂow_step_items table:
93

ITEM MAPPING
• The ID of an input element does not get submitted
back to the server
• Thus, the need for the p_arg_names array
• It provides the mapping from the p_txx elements to
the corresponding APEX page items
94
Item Name Parameter
P101_USERNAME p_t01
P101_PASSWORD p_t02
ID p_arg_name
1 8295929934913911
2 8296003745913912

Validations, Computations
& Processes
95

VALIDATIONS, COMPUTATIONS & PROCESSES
96
• After validating that the session is still valid,APEX will
process all Validations, Computations &
Processes according to their execution point and
corresponding sequence
• Nothing in this phase will ever be output to the screen
• All “Built In” APEX Processes are merely calls to underlying
PL/SQL procedures
• Application Builder abstracts this concept to keep things simple

SET USERNAME COOKIE
• Sets the LOGIN_USERNAME_COOKIE based
on the value of the username entered
• Regardless of whether it successfully authenticated or not
• Can be disabled for security purposes
97
begin
owa_util.mime_header('text/html', FALSE);
owa_cookie.send(
name => 'LOGIN_USERNAME_COOKIE',
value => lower(:P101_USERNAME));
exception when others then null;
end;

LOGIN
• APEX API Call to the standard login procedure:
wwv_ﬂow_custom_auth_std.login
• Will use the current authentication scheme and
determine whether or not a user should be logged in
98
wwv_flow_custom_auth_std.login(
P_UNAME => :P101_USERNAME,
P_PASSWORD => :P101_PASSWORD,
P_SESSION_ID => v('APP_SESSION'),
P_FLOW_PAGE => :APP_ID||':1'
);
Determines the initial
page of your application

Authentication Schemes
99

• APEX can use a number of different
Authentication Schemes
• APEX Credentials
• Custom
• SSO
• LDAP
• Database Schema Users
• Open Door
• None
100

• Regardless of which one you choose, the method
which APEX uses to validate credentials is largely
the same
• Pre-Authentication Process
• Authentication Function
• Post-Authentication Process
101

• Pre-Authentication Process
• Executes just before credentials are veriﬁed
• However, it looks like there may be a bug here, as it seems like is
executes just AFTER credentials are veriﬁed
102

• Authentication Function
• Can be one of the following:
• -BUILTIN-
• APEX User Credentials
• -DBACCOUNT-
• Database Credentials
• -LDAP-
• LDAP using parameters deﬁned in LDAP section
• Custom
• Custom PL/SQL Function returning Boolean
103

• Post-Authentication Process
• Executes just after credentials are veriﬁed
104

105

WWV_CUSTOM-F COOKIE
• Upon successful authentication,APEX will send
another cookie to the client
• This cookie’s sole purpose is to map your browser to your
APEX session
106

BREAKING IT DOWN
107
wwv_ﬂow_sessions$
wwv_ﬂow_companies

CLEAR PAGE CACHE
• Clears the page cache for Page 101
• Thus, removing the username from the APEX session state
108

Logging Out
109

LOGGING OUT
110
• There’s several ways to “log out” of an APEX
application
• Click the Logout link
• Close the Browser Tab/Window
• Quit the Browser
• Let the session expire
• Not all of these truly logs you out

LOGGING OUT
• Close the Browser Tab/Window
• Does NOTHING to log you out
• Quit the Browser
• Expires the Session Cookie
• Let the session expire
• Click the Logout link
• Deletes the Session from wwv_ﬂow_sessions$
111

LOGGING OUT
• APEX automatically schedules a job -
ORACLE_APEX_PURGE_SESSIONS - which
will remove stale session data
• By default, it is set to run hourly
• You can alter the duration to make it run more or less
frequently
112

LOGGING OUT
• The Logout URL is speciﬁed in the Authentication
Scheme
• When clicked, it will expire the session cookie and also
purge the session state from the database
113
wwv_flow_custom_auth_std.logout?
p_this_flow=&APP_ID.&p_next_flow_page_sess=&APP_ID.:1
The Current Application Which Application to Run Next

Logging Out
114

Summary
115

SUMMARY
116
• There are a LOT of things that go on when rendering
or processing an APEX page
• Fortunately,APEX abstracts most of the complexity,
making it easy & efﬁcient to use
• Understanding the discrete steps will help make you a
better and more secure APEX developer

DOWNLOAD
• This and all other Sumneva presentations can
be downloaded for free from:
117
http://sumneva.com/presentations

FEEDBACK
• To provide feedback on this session:
118
http://kscope.ezsession.com
Session ID: 242796

• p_accept_processing
• NEED TO RESEARCH
120

• The next ﬁve parameters have to do with the management of tabular
forms, and should not be altered
• fcs
• <input type="hidden" id="fcs_0003" name="fcs"
value="989EDF72FEF5A40D4F36854921FBBC34">
• fmap
• <input type="hidden" name="fmap" value="ENAME" id="fmap_003" />
• fhdr
• <input type="hidden" name="fhdr" value="Ename" id="fhdr_003" />
• fcud
• <input type="hidden" id="fcud_0003" name="fcud" value="U" />
• frowid
• <input type="hidden" id="frowid_0003" name="frowid"
value="AAANCNAAHAAAAAeAAC" />
121

• p_listener
• Used to communicate with the APEX listener
122

• p_map1, p_map2, p_map3 & p_survey_map
• NEED TO RESEARCH
123

• The next three parameters control report pagination,
and are relatively self-explanatory
• p_flow_current_min_row
• p_flow_current_max_rows
• p_flow_current_rows_fetched
124

• p_md5_checksum
• Used to store the MD5 checksum for data in an APEX form
• Will also be used to compare to the current MD5 checksum
before data is updated
• Always present in the HTML; may not contain a value, if the
current page does not have a Automatic Row Fetch process
125
<input type="hidden" name="p_md5_checksum" value="BF258D46D..." />
MD5 Hash

• p_page_submission_id
• Internal ID used to track individual page submissions within a
session
• Found close to the top of the page
• Should not alter or modify
126

• The last three parameters have to do with NLS
Settings:
• p_time_zone
• Current Time Zone
• p_lang
• Current Language
• p_territory
• Current Country/Region
127

APEX Behind the Scenes by Scott Spendolini

More Related Content

What's hot (20)

Similar to APEX Behind the Scenes by Scott Spendolini (20)

More from Enkitec (20)

Recently uploaded (20)

APEX Behind the Scenes by Scott Spendolini