Home > SQL Developer Concepts and ... > Application Express Listene...
The Oracle Application Express Listener Administration interface enables you to specify global settings and multiple database settings with different database connections for the Oracle Application Express Listener. You can create, retrieve, upload, and save Application Express Listener settings.
See the following subtopics for more information:
Oracle Application Express Listener is a JEE-based alternative for Oracle HTTP Server (OHS) and mod_plsql. The JEE implementation offers increased functionality including command line based configuration, enhanced security, file caching and RESTful Web Services. Oracle Application Express Listener also provides increased flexibility by supporting deployments using Oracle WebLogic Server, Oracle Glassfish Server, and a standalone mode.
The Oracle Application Express architecture requires some form of Web server to proxy requests between a Web browser and the Oracle Application Express engine. Oracle Application Express Listener satisfies this need but its use goes beyond that of Oracle Application Express configurations. Using Oracle Application Express Listener simplifies the deployment process because there is no Oracle home required as connectivity is provided using an embedded JDBC driver. See Oracle Application Express Listener Installation and Developer Guide for concepts and details.
The Oracle Application Express Listener (Release 2.0 or later) must be installed and running in order to retrieve or upload administration settings. In addition, the Application Express Listener Administrator user must be configured on the Application Express Listener. See Oracle Application Express Listener Installation and Developer Guide for information about installing Oracle Application Express Listener.
The Application Express Listener Administration window has a toolbar with icons at the top, and a context menu when you right-click on the Listener navigator. The toolbar and context menu let you perform the following actions:
New Administration displays the Create Listener Administration dialog box, where you specify the Name and optionally a Description of the administration.
After you click Apply in that box, the Listener navigator in the Application Express Listener Administration window contains a hierarchical display of global and database settings. Select any node to display the pane for viewing and changing related settings
Open File lets you open a file that contains saved administration settings. If administration settings are already displayed, you will be warned if you want to overwrite the existing settings.
Save As saves the current settings to a .zip file, which you can open later.
Retrieve Settings obtains the administration settings from the Application Express Listener.
Upload Settings uploads the administration settings to the Application Express Listener. The database settings will be validated before they are uploaded. If any settings are invalid or if required settings are missing, the administration settings will not be uploaded.
Tip: Before you upload the administration settings, click Test Settings to validate the database settings. Review the messages and fix any errors.
Test Settings validates the Database Settings and displays informational messages for incorrect settings or required settings that are missing. If errors are not found during validation, a message will be displayed that validation completed successfully.
Launch URL displays the home page in your browser, for example: http://
host:port
/apex
Connect (context menu only): Connects to the Application Express Listener (see Connecting to Application Express Listener Server).
Retrieve Settings, Upload Settings, and Launch URL are enabled when you connect to the Application Express Listener.
Disconnect (context menu only): Disconnects from the Application Express Listener.
Related Topics
The Application Express Listener Administration requires a connection to the Application Express Listener to retrieve or upload the administration settings. Right-click on the Listener navigator to display the context-menu and select Connect. The Listener Connection dialog box is displayed, where you can select a connection, add a connection to the list, or edit a connection in the list.
When you select a connection and click OK, you are always prompted for the Application Express Listener Administration password (the password you provided during the installation of the Application Express Listener). After successful authentication, the administration settings are retrieved and displayed.
If you add or edit a listener connection, you can specify the following information.
Connection Name: Name to identify the Application Express Listener that you are connecting to based on the information that you are providing.
Username: Application Express Listener Administrator username that you provided during Application Express Listener installation. See Oracle Application Express Listener Installation and Developer Guide for information about configuring the administration user.
http or https: Select which protocol to use.
Hostname: DNS name or IP address of the Application Express Listener.
Port: Port on which the Application Express Listener is listening for requests.
Server Path: Location at which the Application Express Listener is deployed on the application server. Default: /apex
Related Topics
The Administration settings are displayed in the following Listener navigator hierarchy. The Administration settings consist of the global settings and database settings for one or more databases. The settings are displayed in the following Listener navigator hierarchy.
Administration Global Settings Connections JDBC Security Allowed Procedures Blocked Procedures Validation Function Virus Scanning Cache Files Caching Environment Error Reporting Log Reporting Pre-Processing Post-Processing Excel Database Settings <database-name> Connections JDBC URL Mapping RESTful Connections Security Allowed Procedures Blocked Procedures Validation Function Virus Scanning Cache Files Caching Environment Error Reporting Log Reporting Pre-Processing Post-Processing Excel
Global Settings provide the default values for Database Settings. Tip: Specify commonly used settings in the global settings ( Connection, Security, Caching, and so on).
Database Settings specify values for Listener connections to specific databases. The Application Express Listener supports connecting to multiple databases by letting you create multiple database settings with different database connections and use URL mapping to route requests to the appropriate database.
You can create, edit, or remove multiple database settings in the Listener navigator. To add database settings, right-click Database Settings and select New Settings. To remove database settings, right-slick on the desired settings and select Remove Settings.
In panes that display database settings, any setting values that are highlighted indicate the global settings value. If you change a database settings value and later decide to use the global settings value, you can click Reset to restore the global settings values.
To check the validity of database settings, click Test Settings in the Application Express Listener Administration window toolbar.
Use Connections to enter database credentials. Includes the following options related to connection management.
Username: The database user used when invoking PL/SQL Gateway operations, for example, all Oracle Application Express operations.
Password: Password for the specified database user.
For the remaining Connections options, see the Connection Type information (Basic, TNS, Advanced) for Create/Edit/Select Database Connection, especially for the Oracle tab.
JDBC
Use JDBC to configure JDBC options.
JDBC Driver Type: thin or oci8.
Initial Pool Size: Initial pool size for the number of connections that will be created.
Maximum Statements: Maximum number of statements to cache for each connection.
Connection Size: Maximum and Minimum number of connections.
Inactivity Timeout: How long (in seconds) an available connection can remain idle before it is closed.
Abandoned Connection Timeout: How long (in seconds) a borrowed (in use) connection can remain unused before it is considered as abandoned and reclaimed.
URL Mapping
URL mapping is used in configuring multiple database connections, to define the rules for how requests are routed to the appropriate database.
Specify the rules in the Rule Type and the Routing Rule to your database connection. You can use regular expressions in the Routing Rule.
To add a mapping, click the Add URL (+) icon, select the Rule Type, and specify the Routing Rule. To delete a mapping, select it and click the Remove URL (X) icon.
Rule Type: Type of rule: Request Path
, URL Path
, or Regular Expression
.
Routing Rule: Rule on how to route the request to your database connection. See the examples or routing rules in this topic.
Schema for RESTful Services (optional): The name of the Application Express workspace where RESTful services are defined in the database connection. This can be omitted if RESTful Services are not being used.
Example of routing rules:
URL = http://example.com/apex/sales/f?p=1:1
Protocol: http
Host name: example.com
Context root: /apex
(location at which the Listener in deployed on the application server)
Request path: /sales/f?p=1.1
(the request URL relative to the context root)
Example of routing rule using request path prefix:
Assuming the Application Express Listener is deployed on example.com
, its context path is /apex
, and your database setting name is sales_prod
, you can create the following request path prefix routing rule:
Rule Type: Request Path
Routing Rule: /sales
Schema for RESTful Services: sales_rest
The preceding rule means that any requests matching: http://example.com/apex/sales/...
will be routed to the sales_prod
database connection. The sales_rest
schema, specified in the sales_prod
database connection, will be searched for RESTful Services definitions.
The preceding routing rule will match any of the following requests:
http://example.com/apex/sales/f?p=1:1 https://example.com/apex/sales/f?p=1:1 http://example.com/apex/sales/leads/ http://www.example.com/apex/sales/forecasting.report?month=jan (if www.example.com resolves to the same system)
The preceding routing rule will not match any of the following requests:
http://example.com:/apex/leads/f?p=1:1 (missing the /sales prefix) http://example.com/apex/f?p=1:1 (missing the /sales prefix) http://example.com/pls/sales/leads/ (the context root is wrong)
Example of routing rule using URL prefix:
Assuming the Application Express Listener is deployed on example.com
, its context path is /apex
, and your database setting name is sales_prod
, you can create the following URL prefix routing rule:
Rule Type: URL Path
Routing Rule: http://example.com/apex/sales
Schema for RESTful Services: sales_rest
The preceding rule means that any requests matching: http://example.com/apex/sales/...
will be routed to the sales_prod
database connection. The sales_rest
schema, specified in the sales_prod
database connection, will be searched for RESTful Services definitions.
The preceding routing rule will match any of the following requests:
http://example.com/apex/sales/f?p=1:1 http://example.com/apex/sales/leads/ http://example.com/apex/sales/forecasting.report?month=jan
The preceding routing rule will not match any of the following requests:
https://example.com/apex/sales/f?p=1:1 (the protocol is wrong) http://example.com:8080/apex/sales/f?p=1:1 (the port is wrong) http://example.com/apex/f?p=1:1 (missing the /sales segment of the base URL) http://example.com/pls/sales/leads/ (the context root is wrong) http://www.example.com/apex/sales/forecasting.report?month=jan (the host name is wrong)
Related Topics
RESTful Services enable an application to publish web services that are accessed by other applications to exchange data. For example, you can configure a RESTful service to return all employee names for a particular department. The data exchange for a RESTful Service follows the Representational State Transfer (REST) protocol. See RESTful Services Administration and Oracle Application Express Application Builder User's Guide for information on how to develop RESTful Services for use with the Application Express Listener.
If you are using RESTful services, specify the password for the database user APEX_REST_PUBLIC_USER, which used when invoking PL/SQL Gateway operations, and for the database user APEX_LISTENER, which is used to query RESTful services definitions stored in Oracle Application Express.
Related Topics
RESTful Services Administration
Security settings are used to validate procedure requests and determine if a user is allowed to access the procedure.
Verify Secure Socket Layer Requests: Enable this option if HTTPS is available in your environment.
A RESTful service can be protected with the OAuth2 protocol to control access to non-public data. OAuth2 requires all requests involved in the OAuth2 authentication process to be transported via HTTPS. The default behavior of the Application Express Listener is to verify that all OAuth2 related requests have been received via HTTPS. It will refuse to service any such requests received over HTTP, returning an HTTP status code of 403 Forbidden.
Disabling this option should only be used for development or test environments. Do not disable this option for production environments because it will result in user credentials being passed in clear text.
Security Cache: When you specify a PL/SQL validation function, Oracle Application Express Listener uses the security cache to cache the procedures names and determine if they are valid or invalid. Using a caching mechanism reduces the number of database round-trips needed to execute the PL/SQL Validation Function.
Maximum Cache Entries: Maximum cache size. When the maximum entries have been reached, the older (or stale) procedure name that was least recently used is removed from the cache and a new procedure name is added to the cache.
Total Cache Entries: Total number of procedure names that are valid or invalid in the security cache.
Clear Cache: If the total cache entries is greater than zero, Clear Cache is available, and you can click it to delete the cache entries. As a best practice, clear the cache whenever a PL/SQL Validation Function is updated.
Allowed Procedures
Specify patterns for procedures, packages, or schema names that are allowed to be directly executed from a browser. You can use an asterisk (*) to substitute zero or more characters, and a question mark (?) to substitute for any one character.
A benefit of specifying allowed procedures is that the procedure names and procedure patterns are stored in the Oracle Application Express Listener. By contrast, invoking the PL/SQL validation function requires a database round-trip.
To add an entry, click the Add Procedure (+) icon and enter the pattern. To delete an entry, select it and click the Remove Procedure (X) icon.
If no allowed procedures are specified, the Oracle Application Express Listener does not validate the procedure names to determine if the procedure is allowed for processing.
Blocked Procedures
Specify patterns for procedures, packages, or schema names that are forbidden be directly executed from a browser. You can use an asterisk (*) to substitute zero or more characters, and a question mark (?) to substitute for any one character.
If no blocked procedures are specified, the Oracle Application Express Listener does not validate the procedure names to determine if the procedure is blocked from processing
To add an entry, click the Add Procedure (+) icon and enter the pattern. To delete an entry, select it and click the Remove Procedure (X) icon.
Disable Default Internal Exclusion List: If option is selected, the Oracle Application Express Listener internal exclusion list is not enforced. This internal exclusion list blocks users from accessing the following:
sys.*, dbms_*, utl_*, owa_*, owa.*, htp.*, htf.*, wpg_docload.*
Oracle recommends that you not select this option; that is, do not disable the default internal exclusion list. The only possible exception is temporarily disabling the internal exclusion list for debugging purposes.
Validation Function
You can use the Validation Function to determine if the requested procedure in the URL should be allowed for processing. Oracle Application Express Listener executes the validation function you specify for each requested procedure, or checks the security cache to determine if a procedure is valid or invalid.
The validation function returns true
if the procedure is allowed for processing. Otherwise, it returns false
.
Validation Function Type: Implementation language: PL/SQL or JavaScript.
Validation Function: For PL/SQL, the name of the stored function that resides in the database. If the validation function you specify does not exist, an error message is displayed.
For JavaScript, the code written in JavaScript. The advantage of using JavaScript instead of using the PL/SQL database function is that there are not any database round-trips to execute the validation function.
Virus Scanning
Specify the Internet Content Adaptation Protocol (ICAP) Server name and Port for virus-scanning of your files. A message is displayed if a file is infected.
Related Topics
Specify procedure names to allow caching of files.
To add an entry, click the Add Procedure (+) icon and enter the procedure. To delete an entry, select it and click the Remove Procedure (X) icon.
Keep most recently used files: If selected, files that are most recently used will remain in the cache. Specify the maximum number of files to cache. When the maximum entries have been reached, the older files are removed from the cache when a new file is added
Keep files for the specified duration: If selected, files that are cached expire after the specified number of days, hours, or minutes (must be greater than 0).
Caching
Total Cache Entries: Maximum cache size. When the maximum entries have been reached, the older (or stale) procedure name that was least recently used is removed from the cache and a new procedure name is added to the cache.
Clear Cache (displayed the total cache entries is greater than zero): Deletes the current cache entries.
Cache File Location: Directory for the cache files.
Related Topics
Application Express Document Table: Name of the document table used by Application Express. (All files uploaded using the PL/SQL Gateway are stored in a document table.)
PL/SQL Gateway
Default Web Page: Default web page to display.
Extension Classes: Extension classes to extend the Application Express Listener.
Procedure Recorder: If selected, causes procedures to be logged.
Error Reporting
You can specify to show debug messages on the console: or to show error messages in a browser, or to do both or neither. On production systems, you should leave both options unselected (disabled).
Show debug messages on console: If selected, displays debug messages on the console. This may help with problem diagnosis and is appended to the Application Express Listener log output. However, you should not enable this option on production systems due to the performance impact of outputting large amounts of data to the log.
Show error messages on browser: If selected, displays error responses in the browser, including for each a detailed error message and a stack trace. However, do not enable this option on productions systems due to the risk of sensitive information being revealed.
Log Reporting
Logging: Specifies whether to make entries in the Oracle Application Express Listener. The log includes activities such as adding a procedure to the cache, finding a procedure in the cache, or reloading a procedure. The log displays the database time and processing time in milliseconds for that procedure.
Keep most recent log messages: If selected, entries that are most recent will remain in the log. Specify the maximum number of log messages to cache. When the maximum entries have been reached, the older log messages are removed from the cache when a new log message is added.
Pre-Processing
Specify the names of procedures to be executed before executing the requested procedure.
To add an entry, click the Add Procedure (+) icon and enter the procedure name. To delete an entry, select it and click the Remove Procedure (X) icon.
Post-Processing
Specify the names of procedures to be executed after executing the requested procedure.
To add an entry, click the Add Procedure (+) icon and enter the procedure name. To delete an entry, select it and click the Remove Procedure (X) icon.
Related Topics
If you are using Oracle Application Express, you have the option of placing your Excel files into an Application Express collection.
Process Excel files into a collection: If selected, puts Excel files into an Application Express Collection.
Put each Excel worksheet into one collection: If selected, puts all Excel worksheets into a single collection, for which you specify the Collection Name.
Use the name of the Excel worksheet as the collection name: If selected, creates a collection for each Excel worksheet, and uses each worksheet name for the corresponding collection name.
Related Topics