Application Express 5.1: new Features for setup and administration
At the first glance, installing a new APEX 5.1 instance, or upgrading an existing APEX instance to 5.1, works
the same way as with the releases before: A DBA (e.g. logged in as SYS) runs the
apexins.sql installation script; typically as follows:
The first argument determines the tablespace for the APEX engine itself (which is installed into the
APEX_050100 schema); the second one sets the tablespace for the
FLOWS_FILES schema (which contains the table for uploaded files). The
default temporary tablespace for both schemas is set by the third argument ("TEMP"); and the last argument
one has to match the APEX web server configuration and can be changed using the
utilities/reset_image_prefix.sql script, if necessary.
Upgrading an Application Express instance
The Application Express engine is always installed in the APEX_XXXXXX schema;
XXXXXX denotes the APEX version. So, APEX 5.0 resides in the APEX_050000 schema whereas the objects of APEX 5.1
will be placed into APEX_050100.
For patch sets, no new schemas will be created: all patch levels of APEX 5.0
(5.0.1, 5.0.2, 5.0.3 and 5.0.4) will be in the APEX_050000 schema.
Thus installation of an APEX patch set is fundamentally different to installation of a new APEX version: Patch sets
(e.g. APEX 5.0.4) will be installed directly into the existing APEX engine schema (APEX_050000).
Unlike that, a
new APEX version (APEX 5.1) will be installed into the new database schema (APEX_050100).
Then, all application meta data in
the APEX respository will be copied from the existing APEX engine schema to the schema of the new APEX version. Finally, the public synonyms,
will be changed to point to the new APEX version.
Just after an upgrade has finished, we have two APEX installations in our database, the previous and the
latest version. Both versions contain the same applications, same workspaces and same end user definitions. The
APEX public synonyms now point to the new versions, so the old version is inactive; changes to applications will
only affect the new version.
Having that in mind, it's easy to understand why APEX allows to revert the upgrade when errors or problems
are encountered immediately after the upgrade: the old version is still here - we just have to point the
APEX public synonyms back, making it active again. The
APEX Installation Guide describes how that works.
Minimum downtime upgrade to Application Express 5.1
APEX 5.1 contains an interesting new feature: Upgrade from a previous version to APEX 5.1 can be done
in a minimum downtime fashion.
Previous APEX releases required the APEX instance to be down for the whole installation and upgrade
process. Before starting the apexins.sql script,
the web server had to be taken down until the script
finished and the upgrade was completed. Upgrade duration basically depends on the amount of existing
workspaces and applications. Dedicated APEX instances with only a few workspaces and applications are
rather quick and finish in a few minutes; large instances (like Oracle's
apex.oracle.com with thousands
of applications) require several hours for an upgrade to complete. Considering the fact, that
many projects and business departments are dependent on a multi-project APEX instance,
such a downtime can become a problem.
APEX 5.1 allows to perform the upgrade in four phases. Each phase has different downtime requirements.
- Create the APEX_050100 schema and install the APEX engine
- Migrate application meta data to the new APEX version
- Migrate runtime meta data, like interactive report settings, to the new APEX version
- Migrate archive data, like the APEX activity log, to the new APEX version
The first phase does not impact the existing APEX version at all; so the APEX instance (old version) is up
and running during that time: Developers and end users can work as usual. In the second phase, application meta data
will be migrated, which means that developers cannot change applications during that phase. Workspace login does
work, developers can also browse through the applications, but changes are not possible. End users are not impacted
Only the third phase requires a complete downtime. The web server must be taken down for that phase. But since the
work in that phase is only a small part of the whole process, downtime will be significantly reduced. After that
phase has been completed, the new APEX version is fully available to end users and developers; the final phase of
migrating archived data will run in background.
To perform a minimum downtime upgrade, the apexins1.sql to
apexins3.sql scripts must be used instead of apexins.sql.
For a runtime only installation, there are the apxrtins1.sql to
apxrtins3.sql scripts instead of apxrtins.sql.
- First, apexins1.sql / apxrtins1.sql is started. The
APEX web server remains up and running; so APEX is still available.
- After that, apexins2.sql / apxrtins2.sql initiate the
second phase. The web server still remains up and running. Developers can log into their workspaces and
browse their applications. However, an attempt to make a change leads to an error message similar to the following.
Applications cannot be changed during upgrade phase 2
- The third phase, initiated with the apexins3.sql or
apxrtins3.sql script, requires a downtime. as described above. So, before
that script is started, the web server must be taken down in order to prevent access to Application Express.
After the script finished, the static files of the new APEX version must be provided on the web server, so that
they are accessible under the URL prefix used in the apexins?.sql scripts (normally /i/).
Then the web server can be started again making the new APEX version available to all developers and end users.
- The fourth and final phase will be initiated from the apexins3.sql / apxrtins3.sql script as a DBMS_SCHEDULER job automatically. Developers and end users are not impacted by this phase.
REST services to retrieve Application Express statistics
APEX 5.1, introduces a REST-based administation interface. This first version contains REST services to provide
access statistics and metrics. That allows to fetch statistics over REST and to collect metrics from multiple applications,
workspaces and even instances into a central location. To use these REST services,
Oracle REST Data Services (ORDS) must be
used as the APEX web server and it has to be at least the 3.0.5 version.
Initially, the administrative REST interface is disabled. To enable it, log into the
INTERNAL workspace and then to the
Manage Instance section.
Workspace INTERNAL - Manage Instance
Click on REST Administration Interface. A dialog window opens showing a message, that
the REST interface is disabled.
The REST Administration Interface is disabled
Click the Enable Services button. That will enable the REST interface.
REST Administration Interface is now enabled
Authentication to the REST interface is done usingh the OAuth2 Client Credentials
flow. More information on this is contained in the
Oracle REST Data Services documentation.
So, an OAuth Client must be registered in order to generate a client ID and a client secret for authentication. Click
the Create OAuth Client button to do this.
Register a new OAuth client
Enter a descriptive name and a contact email address. In APEX 5.1 only the privilege to access statistic data
View Usage Statistics is available. Then click
Create OAuth Client, to actually register the client.
The new OAuth client has been created
Click the name of the new client in order to see its details; we are now interested in the
generated Client ID and Client Secret.
Client ID and Client Secret of the new OAuth client
The OAuth Client Credentials flow states, that Client ID and Client Secret are
being used to obtain an Access Token from the server. For the next one hour,
that access token can be used to authenticate with the actual REST interface.
The following code examples show how the REST interface is being used with the
curl command line utility. The first
request obtains the access token:
The server responds, as almost all REST services, in JSON format. The
access_token attribute contains the actual token value. With that, we
can execute the second request fetching statistics from the APEX instance.
Again, the metrics are delivered in JSON format.
The available REST services are documented in the Application Express Administrators Guide;
metrics can be obtained on instance, workspace or application level. Filtering for specific time frames or specific
metric values is also possible. The architecture based on open standards like JSON, REST and OAuth makes it easy to
integrate with 3rd party software.
Desupport of the APEX_PLSQL_JOB package
As already announced with the APEX 5.0 release, APEX_PLSQL_JOB
(which relied on the old DBMS_JOB package) has been removed.
APEX_PLSQL_JOB was used to run PL/SQL logic in the background. Since
Oracle10g (that means, since 2004) this is better done using the
PL/SQL package; with superior configuration options and job monitoring. Note that your applications' parsing schema
needs the CREATE JOB privilege in order to use DBMS_SCHEDULER.
Here is an example for some
code to run PL/SQL logic in background with APEX_PLSQL_JOB:
The following code does the same; but uses DBMS_SCHEDULER.
Applications or PL/SQL code using APEX_PLSQL_JOB
should therefore be migrated to use DBMS_SCHEDULER. That should be
done even when still on APEX 5.0 or 4.2. Having this done, applications will run without issues
after the upgrade to 5.1.
Zurück zur Community-Seite