You are on page 1of 82

Oracle Application Express Listener

Installation and Developer Guide Release 1.1


E21058-01

March 2011

Oracle Application Express Listener Installation and Developer Guide, Release 1.1 E21058-01 Copyright 2011, Oracle and/or its affiliates. All rights reserved. Primary Author: Terri Jennings Contributors: Colm Divilly, Hilary Farrell, Sharon Kennedy, Elizabeth Saunders, and Jason Straub This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Contents
Preface ................................................................................................................................................................ vii
Topic Overview .......................................................................................................................................... Audience...................................................................................................................................................... Documentation Accessibility ................................................................................................................... Related Documents ................................................................................................................................... Conventions ................................................................................................................................................. Third-Party License Information............................................................................................................... vii vii viii viii ix ix

1 Installing Oracle Application Express Listener


About Oracle Application Express Listener........................................................................................ 1-1 Supported Java Enterprise Edition Application Servers .............................................................. 1-1 About System Requirements ................................................................................................................. 1-2 Oracle Application Express Listener Installation Overview .......................................................... 1-2 Downloading Oracle Application Express Listener.......................................................................... 1-2 Installing in Standalone Mode .............................................................................................................. 1-3 Install and Run in Standalone Mode............................................................................................... 1-3 About Standalone Configuration Options ..................................................................................... 1-4 About Stopping the Server in Standalone Mode........................................................................... 1-4 About JServ Protocol (AJP) Support................................................................................................ 1-5 Installing with Oracle WebLogic Server.............................................................................................. 1-5 Download and Unzip Oracle Application Express Listener ....................................................... 1-5 Create Web Archive for Oracle Application Express Images...................................................... 1-5 Launch the Administration Server Console................................................................................... 1-6 Install the Deployment ..................................................................................................................... 1-6 Create Users and Roles...................................................................................................................... 1-9 View Security Realms................................................................................................................. 1-9 Create Users .............................................................................................................................. 1-10 Create Roles .............................................................................................................................. 1-10 Access Oracle Application Express Listener Administration................................................... 1-12 Installing with Oracle GlassFish Server........................................................................................... 1-12 Download and Unzip Oracle Application Express Listener .................................................... 1-13 Copy Oracle Application Express Images ................................................................................... 1-13 Launch the Administration Console ............................................................................................ 1-13 Create Users and Roles................................................................................................................... 1-13 About Roles............................................................................................................................... 1-14

iii

Create Users .............................................................................................................................. Install the Deployment ................................................................................................................... Access Oracle Application Express Listener Administration................................................... Installing with Oracle Containers for J2EE (OC4J) ........................................................................ Download and Unzip Oracle Application Express Listener .................................................... Copy Oracle Application Express Images ................................................................................... Start the OC4J Server ...................................................................................................................... Start the Application Server Control Console............................................................................. Create Users and Roles................................................................................................................... Create Roles .............................................................................................................................. Create Users .............................................................................................................................. Install the Deployment .................................................................................................................. Access Oracle Application Express Listener Administration................................................... Upgrading Oracle Application Express Listener ............................................................................ Redeploy Oracle WebLogic Server ............................................................................................... Redeploy Oracle GlassFish Server................................................................................................ Redeploy Oracle Containers for J2EE (OC4J).............................................................................. Upgrading Oracle Application Express Images .............................................................................. Copy Application Express Images When Using Oracle WebLogic Server............................. Copy Application Express Images When Using Oracle GlassFish Server ............................. Copy Application Express Images When Using Oracle Containers for J2EE (OC4J) ...........

1-14 1-15 1-16 1-17 1-17 1-17 1-18 1-18 1-18 1-18 1-19 1-19 1-20 1-20 1-21 1-22 1-22 1-23 1-23 1-24 1-24

2 Configuring Oracle Application Express Listener


Accessing Oracle Application Express Listener ................................................................................. 2-1 Access Oracle Application Express Listener Administration...................................................... 2-1 View Status Information ................................................................................................................... 2-2 About Oracle Application Express Listener Administration .......................................................... 2-2 Establishing a Database Connection .................................................................................................... 2-2 Establish a Basic Connection ............................................................................................................ 2-3 Establish a TNS Connection ............................................................................................................. 2-3 Establish an Advanced Connection................................................................................................. 2-3 About JDBC Settings.......................................................................................................................... 2-4 Configuring Security ............................................................................................................................... 2-5 About Allowed Procedures .............................................................................................................. 2-5 Advantages of Allowed Procedures ........................................................................................ 2-6 About Blocked Procedures ............................................................................................................... 2-6 About the Internal Exclusion List ............................................................................................. 2-6 About Database Validation Function.............................................................................................. 2-7 About the Database Validation Function Format .................................................................. 2-7 About Security Settings ..................................................................................................................... 2-8 Understanding Security Processing ................................................................................................ 2-8 Defining Caching ..................................................................................................................................... 2-9 Specify Procedure Names to Cache Files........................................................................................ 2-9 Creating Pre- Post Processing Procedures ........................................................................................ 2-10 About Pre-processing Procedures ................................................................................................ 2-10 About Post-processing Procedures............................................................................................... 2-10 Viewing Status ....................................................................................................................................... 2-11

iv

About Statistics ................................................................................................................................ About Error Tracking ..................................................................................................................... About Logging................................................................................................................................. Configuring Miscellaneous Options.................................................................................................

2-11 2-12 2-12 2-12

3 RESTful APIs and Resource Templates


What is a RESTful API? .......................................................................................................................... 3-1 About Resource Templates ............................................................................................................... 3-1 About Resource Template Administration.......................................................................................... 3-2 Create a Resource Template ............................................................................................................. 3-2 About URI Templates................................................................................................................. 3-2 About the Entity Tag ......................................................................................................................... 3-3 About Resource Handlers................................................................................................................. 3-3 Add Other Handlers................................................................................................................... 3-3 About Supported HTTP Methods ............................................................................................ 3-3 Strategies When Choosing a Resource Handler Type........................................................... 3-4 About Resource Handler Parameters ...................................................................................... 3-4 Referencing Parameters ............................................................................................................. 3-4 About Acceptable Media Types................................................................................................ 3-5 About Security Constraints ....................................................................................................... 3-5 About Resource Handler Types............................................................................................................. 3-5 Query ................................................................................................................................................... 3-5 With One Result Only ................................................................................................................ 3-6 Comma Separated Values Query..................................................................................................... 3-6 Media Resource .................................................................................................................................. 3-7 PL/SQL Block ..................................................................................................................................... 3-8 Example: Creating an Image Gallery.................................................................................................... 3-9 Before You Begin ................................................................................................................................ 3-9 About URIs .................................................................................................................................. 3-9 About API Entry Points .......................................................................................................... 3-10 Create a Database Schema ............................................................................................................. 3-10 Upload Images................................................................................................................................. 3-10 Create an Image Upload Form ...................................................................................................... 3-11 Display the Image ........................................................................................................................... 3-12 Display the Gallery ......................................................................................................................... 3-12 Improve the Appearance of the Gallery ...................................................................................... 3-14 Create gallery.css ..................................................................................................................... 3-14 Create gallery.js ........................................................................................................................ 3-15 About the RESTful API .................................................................................................................. 3-15 About Resource Template Security.................................................................................................... 3-16 Integration with Oracle Single Sign On ....................................................................................... 3-17 External Authentication Using Apache JServ Protocol ............................................................. 3-17 Example: Protecting Gallery Uploads.......................................................................................... 3-17 Protect Upload Form ............................................................................................................... 3-17 Protect Gallery POST Handler ............................................................................................... 3-18 Test the Changes ...................................................................................................................... 3-18

A About the Configuration File


About the Listener Configuration File................................................................................................ Locating the Configuration File ...................................................................................................... How the Listener Searches for the Configuration File ......................................................... Setting the Value of the config.dir Parameter............................................................................... Understanding Configuration File Parameters ................................................................................. About Configurable Parameters........................................................................................................... A-1 A-1 A-1 A-2 A-2 A-3

B Troubleshooting
Oracle Application Express Images Not Displaying........................................................................ B-1 Cannot Log In to Oracle Application Express Listener Administration ...................................... B-3

Index

vi

Preface
Oracle Application Express Listener Installation and Developer Guide explains how to install and configure Oracle Application Express Listener as well as utilize exposed RESTful Application Programming Interfaces (APIs). Topics: Topic Overview

Audience Documentation Accessibility Related Documents Conventions Third-Party License Information

Topic Overview
This document contains the following sections:
Title Installing Oracle Application Express Listener Configuring Oracle Application Express Listener Description Describes how to download and install Oracle Application Express Listener in various environments. Explains how to use Oracle Application Express Listener Administration to set up a database connection, configure security and file caching, and perform other tasks. Explains how to use RESTful APIs to expose data stored in the Oracle Database. Describes the Oracle Application Express Listener configuration file. Describes common installation issues and offers solutions.

RESTful APIs and Resource Templates About the Configuration File Troubleshooting

Audience
This document is intended for system administrators or application developers who are installing Oracle Application Express Listener. This guide assumes you are familiar with Web technologies and have a general understanding of Windows and UNIX platforms.

vii

Documentation Accessibility
Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/. Accessibility of Code Examples in Documentation Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace. Accessibility of Links to External Web Sites in Documentation This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites. Access to Oracle Support Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.

Related Documents
For more information, see these Oracle resources:

Oracle Application Express Listener Release Notes Oracle Application Express Installation Guide Oracle Application Express Release Notes Oracle Database 2 Day + Application Express Developer's Guide Oracle Application Express Application Builder User's Guide Oracle Application Express SQL Workshop and Utilities Guide Oracle Application Express API Reference Oracle Application Express Migration Guide Oracle Application Express Administration Guide Oracle Database Concepts Oracle Database Advanced Application Developer's Guide Oracle Database Administrator's Guide

For information about Oracle error messages, see Oracle Database Error Messages. Oracle error message documentation is available only in HTML. If you have access to the Oracle Database Documentation Library, you can browse the error messages by

viii

range. Once you find the specific range, use your browser's "Find in Page" feature to locate the specific message. When connected to the Internet, you can search for a specific error message using the error message search feature of the Oracle online documentation. Many books in the documentation set use the sample schemas of the seed database, which is installed by default when you install Oracle. See Oracle Database Sample Schemas for information about how these schemas were created, and how you can use them yourself. For additional application examples, go to the Learning Library. Search for free online training content, including Oracle by Example (OBE), demos, and tutorials. To access the Oracle Learning Library, go to:
http://www.oracle.com/technetwork/tutorials/index.html

Printed documentation is available for sale in the Oracle Store at: http://shop.oracle.com/ To download free release notes, installation documentation, white papers, or other collateral, visit the Oracle Technology Network (OTN). You must register online before using OTN; registration is free and can be done at: http://www.oracle.com/technology/membership/ If you have a user name and password for OTN, then you can go directly to the documentation section of the OTN Web site at: http://www.oracle.com/technology/documentation/

Conventions
The following text conventions are used in this document:
Convention boldface italic monospace Meaning Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

Third-Party License Information


Oracle Application Express contains third-party code. Please see the Oracle Database Licensing Information book for notices Oracle is required to provide. Note, however, that the Oracle program license that accompanied this product determines your right to use the Oracle program, including the third-party software, and the terms contained in the following notices do not change those rights.

ix

1
1

Installing Oracle Application Express Listener

This section describes how to install Oracle Application Express Listener. Topics: About Oracle Application Express Listener

About System Requirements Oracle Application Express Listener Installation Overview Downloading Oracle Application Express Listener Installing in Standalone Mode Installing with Oracle WebLogic Server Installing with Oracle GlassFish Server Installing with Oracle Containers for J2EE (OC4J) Upgrading Oracle Application Express Listener Upgrading Oracle Application Express Images

About Oracle Application Express Listener


Oracle Application Express Listener is a J2EE-based alternative for Oracle HTTP Server (OHS) and mod_plsql. The J2EE implementation offers increased functionality including a Web-based configuration, enhanced security, and file caching. Oracle Application Express Listener also provides increased flexibility by supporting deployments using Oracle WebLogic Server (WLS), Oracle Glassfish Server, and Oracle Containers for J2EE (OC4J) as well as 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.

Supported Java Enterprise Edition Application Servers


Oracle Application Express Listener supports the following Java Enterprise Edition application servers:

Installing Oracle Application Express Listener

1-1

About System Requirements

Application Server Oracle WebLogic Server Oracle GlassFish Server Oracle Containers for J2EE

Supported Release 11g Release 1 (10.3.3) or higher Release 3 or higher Release 10.1.3.4 or higher

About System Requirements


Oracle Application Express Listener system and space requirements are as follows:

Oracle Database (Enterprise Edition, Standard Edition or Standard Edition One) release 10.2.0.3 or higher, or Oracle Database 10g Release 2 Express Edition or higher. Java 6 Update 20 JDK or higher. Java Servlet Specification 2.3 or higher. Web browser requirements: Microsoft Internet Explorer 8.0 or higher. Mozilla Firefox 3.0 or higher. Google Chrome 2.0 or higher.

Oracle Application Express Listener Installation Overview


To install Oracle Application Express Listener:
1. 2.

Download and unzip Oracle Application Express Listener. See "Downloading Oracle Application Express Listener" on page 1-2. Install Oracle Application Express Listener. Options include:

Standalone Mode. See "Installing in Standalone Mode" on page 1-3. Oracle WebLogic Server. See "Installing with Oracle WebLogic Server" on page 1-5. Oracle GlassFish Server. See "Installing with Oracle GlassFish Server" on page 1-12. Oracle Containers for J2EE (OC4J). See "Installing with Oracle Containers for J2EE (OC4J)" on page 1-17.

3.

Configure Oracle Application Express Listener. See "Configuring Oracle Application Express Listener" on page 2-1.
See Also: "Upgrading Oracle Application Express Listener" on page 1-20 and "Troubleshooting" on page B-1

Downloading Oracle Application Express Listener


To install Oracle Application Express Listener:
1.

Download the file apex_listener.version.number.zip from the Oracle Application Express Listener download page. See:
http://www.oracle.com/technetwork/developer-tools/apex-listener/dow nloads/index.html

1-2 Oracle Application Express Listener Installation and Developer Guide

Installing in Standalone Mode

Note that the version.number in the filename reflects the current release number.
2.

Unzip the downloaded zip file into a directory (folder) of your choice:

UNIX and Linux: Unzip apex_listener.version.number.zip Windows: Double click the file apex_listener.version.number.zip in Windows Explorer

Installing in Standalone Mode


Although Oracle Application Express Listener supports the Java Enterprise Edition application servers described in "Supported Java Enterprise Edition Application Servers" on page 1-1, you also have the option of running in standalone mode. Standalone mode enables you to quickly deploy Oracle Application Express Listener, at the cost of control and manageability gained when using a JEE application server Topics: Install and Run in Standalone Mode

About Standalone Configuration Options About Stopping the Server in Standalone Mode About JServ Protocol (AJP) Support

Install and Run in Standalone Mode


To launch Oracle Application Express Listener in standalone mode:
1. 2.

Download and unzip Oracle Application Express Listener. See "Downloading Oracle Application Express Listener" on page 1-2. Execute the following command:
java jar <temp directory>\apex.war

Where <temp directory> is the directory location of the unzipped Oracle Application Express Listener.
3. 4.

When prompted, specify the location of the folder containing the static resources used by Oracle Application Express. When prompted, choose a user name and password for the Oracle Application Express Listener Administrator and Manager roles.
Tip: You will only be prompted for the usernames and passwords the first time you launch Oracle Application Express Listener.

You default Web browser starts and navigates to:


http://<host>:<port>/apex/listenerConfigure

Where:

<host> is the DNS name or IP address of the Administration Server <port> is the listen port on which the Administration Server is listening for requests (port 8080 by default)

5.

Configure Oracle Application Express Listener. See "Configuring Oracle Application Express Listener" on page 2-1.

Installing Oracle Application Express Listener

1-3

Installing in Standalone Mode

About Standalone Configuration Options


Oracle Application Express Listener provides several configuration options when running in standalone mode. For example, you can configure the location of the Oracle Application Express images directory, the home directory where Oracle Application Express Listener stores run-time files, and the HTTP listen port. Additionally, you can also remove run-time files from the Oracle Application Express home directory. To display a full list of available commands, execute the following command:
java jar <temp directory>\apex.war --help

Where <temp directory> is the directory location of the unzipped Oracle Application Express Listener. The following output displays:
java [options] -jar apex.war [--help] Options: -Dapex.home=/path/to/apex : Path to the folder used to store the web container runtime, defaults to: ${java.io.tmpdir}/apex -Dapex.port=nnnn -Dapex.ajp=nnnn : HTTP listen port, default 8080 : AJP (mod_jk) listen port, default none If an AJP Port is specified then HTTP access is disabled

-Dapex.images=/images/location : Path to the folder containing static resources required by APEX -Dapex.erase=true : Erase the contents of ${apex.home} before launching : Print this usage message

--help

Consider the following example:


java -Dapex.home=/tmp/apex -Dapex.images=/usr/local/apex/images -Dapex.port=8585 -Dapex.erase -jar <temp directory>/apex.war

Specifying the options above produces the following results:


1. 2. 3. 4.

Erase the contents of /tmp/apex. Extract the run-time files to /tmp/apex. Configure the run-time to listen on HTTP port 8585. Use the contents of /usr/local/apex/images for serving the static content required by Oracle Application Express.

About Stopping the Server in Standalone Mode


To stop the Oracle Application Express Listener server in standalone mode, at a command prompt press CTRL+C.

1-4 Oracle Application Express Listener Installation and Developer Guide

Installing with Oracle WebLogic Server

About JServ Protocol (AJP) Support


Standalone mode supports the Apache JServ Protocol (AJP), enabling it to be integrated with Web servers that support AJP (for example, Apache 2.2 and mod_jk). To enable the AJP, use the -Dapex.ajp command line parameter to indicate the port to listen on (usually 8009).
Tip: Enabling AJP implicitly disables HTTP. It is not possible to listen for both protocols simultaneously.

Installing with Oracle WebLogic Server


You can install Oracle Application Express Listener with Oracle WebLogic Server. Oracle WebLogic Server is available for download from Oracle Technology Network. See:
http://www.oracle.com/technetwork/middleware/weblogic/downloads/weblogi c-developer-vm-303434.html

To learn more about installing Oracle WebLogic Server, see Oracle Fusion Middleware Getting Started With Installation for Oracle WebLogic Server and Oracle Fusion Middleware Installation Guide for Oracle WebLogic Server.
Tip: This section assumes that you have completed the installation process and are familiar with Oracle WebLogic Server. If you are unfamiliar with domains, managed servers, deployment, security, users and roles, refer to your Oracle WebLogic Server documentation.

Topics: Download and Unzip Oracle Application Express Listener


Create Web Archive for Oracle Application Express Images Launch the Administration Server Console Install the Deployment Create Users and Roles Access Oracle Application Express Listener Administration

Download and Unzip Oracle Application Express Listener


For more information, see "Downloading Oracle Application Express Listener" on page 1-2.

Create Web Archive for Oracle Application Express Images


Before you begin, you must create a Web archive (WAR) file to contain the Oracle Application Express image files. Using the Java Archive (jar) command, enter the following command to create a Web archive file named i.war:
jar cvf0 <temp directory>\i.war C <apex directory>\images .

Where:

<temp directory> is the directory location of the unzipped Oracle Application Express Listener file. <apex directory> is the directory location of Oracle Application Express.

Installing Oracle Application Express Listener

1-5

Installing with Oracle WebLogic Server

Tip:

The space and period (.) at the end of the command is required.

Launch the Administration Server Console


To launch the Administration Server console:
1. 2.

Start an Administration Server. Launch the WebLogic Administration Console by typing the following URL in your Web browser:
http://<host>:<port>/console

Where:

<host> is the DNS name or IP address of the Administration Server <port> is the listen port on which the Administration Server is listening for requests (port 7001 by default)

3. 4.

Enter your WebLogic Administrator username and password. If your domain is in Production mode, click the Lock & Edit button on the left-pane below the submenu Change Center. If your domain is in Development mode this button will not appear.

Install the Deployment


Tip: The Oracle Application Express Listener files, apex.war and i.war, must be available before you start this task. See "Downloading Oracle Application Express Listener" on page 1-2 and "Create Web Archive for Oracle Application Express Images" on page 1-5

To install the deployment:


1.

Go to the WebLogic Server Home Page. Below Domain Configuration, select Deployments. The Summary of Deployments displays.

2.

Click Install.

1-6 Oracle Application Express Listener Installation and Developer Guide

Installing with Oracle WebLogic Server

3.

Specify the location of the apex.war file and click Next. The apex.war file is located in the folder where you unzipped the Oracle Application Express Listener ZIP file. See "Downloading Oracle Application Express Listener" on page 1-2. Install Application Assistant appears.

4. 5.

Select Install this deployment as an application and click Next. Select the servers and/or clusters to which you want to deploy the application or module and click Next.
Tip: If you have not created additional Managed Servers or clusters, you will not see this assistant page.

6.

In the Optional Settings, specify the following:


a.

Name - Enter:
apex

b.

Security - Select the following: Custom Roles: Use roles that are defined in the Administration Console; use policies that are defined in the deployment descriptor

c.

Source accessibility - Select: Use the defaults defined by the deployments targets

7.

Click Next.

Installing Oracle Application Express Listener

1-7

Installing with Oracle WebLogic Server

A summary page appears.


8.

Under Additional configuration, select one of the following:

Yes, take me to the deployments configuration - Displays the Configuration page. No I will review the configuration later - Returns you to the Summary of Deployments page.

9.

Review the summary of configuration settings that you have specified.

10. Click Finish. 11. Repeat the previous steps and deploy the i.war file.

In the optional settings, specify the following:


a.

Name - Enter:
i

b.

Security - Select: DD Only: Use only roles and policies that are defined in the deployment descriptors

c.

Source Accessibility - Select: Use the defaults defined by the deployments targets

12. If your domain is in Production Mode, then on the Change Center click Activate

Changes. Verifying the State and Health of apex and i In the Summary of Deployments, select the Control tab and verify that both the apex and i State are Active and the Health status is OK.

1-8 Oracle Application Express Listener Installation and Developer Guide

Installing with Oracle WebLogic Server

If apex or i are not Active, then enable them. In the Deployments table, select the check box adjacent to apex and/or i. Click Start and select Servicing all requests to make them active.

Create Users and Roles


Oracle Application Express Listener requires users be assigned roles to access Oracle Application Express Listener Administration. This section describes how to create users and roles. For more information on security realms, users, and roles, see your Oracle WebLogic Server documentation. Topics: View Security Realms

Create Users Create Roles

View Security Realms


A security realm consists of a set of configured security providers, users, groups, security roles, and security policies. You must define each user in a security realm in order to access any WebLogic resources belonging to that realm. For more information on security realms, see your Oracle WebLogic Server documentation. To view a summary of security realms:
1.

If your domain is in Production mode, click Lock & Edit on the left pane below Change Center. If your domain is in Development mode, this button does not display. On the left pane below Domain Structure, click Security Realms.

2.

The Summary of Security Realms displays.

Installing Oracle Application Express Listener

1-9

Installing with Oracle WebLogic Server

Create Users
Next, create two users. Create an administrator user to access the Oracle Application Express Listener Administration page and a manager user to access the Oracle Application Express Listener Status page. To create users:
1. 2.

In the left pane of the Administration Console, select Security Realms. See "View Security Realms" on page 1-9. Select a security realm by clicking the security realm name (for example, myrealm). The Settings page displays.

3.

Click the Users and Groups tab and then click the Users tab. The User table displays the names of all defined users.

4. 5.

Click New. In Name, enter the name of the user. For example:
adminlistener

User names are case sensitive and must be unique. Do not use commas, tabs or any other characters in the following comma-delimited list:
<>, #, |, &, ?, ( ), { } 6.

In Description, enter a description (optional). For example:


APEX Listener administrator user

7.

From the Provider list, select the Authentication provider for the user. Next, define a password for the user. Note that the minimum password length for a user defined in the WebLogic Authentication provider is 8 characters.

8. 9.

In Password, enter a password. In Confirm Password, reenter the password.

10. Click OK.

The user appears in the User table.


11. Create another user to access the Oracle Application Express Listener Status page.

Specify the following:


Name - managerlistener Description - APEX Listener manager user

Create Roles
Oracle Application Express Listener requires you assign users roles to access the Application Express Listener Administration. There are two types of roles:

Admin - The user has permission to access the Oracle Application Express Listener Administration page. Manager - The user has permission to access the Oracle Application Express Listener Status Information Page.

To create roles:

1-10 Oracle Application Express Listener Installation and Developer Guide

Installing with Oracle WebLogic Server

1. 2.

In the left pane of the Administration Console, select Security Realms. See "View Security Realms" on page 1-9. On the Summary of Security Realms page, select the name of the realm you want to secure the resource (for example, myrealm). The Settings page displays.

3.

Select the Roles and Policies tab and then select the Realm Roles. The Roles page organizes all of the domain's resources and corresponding roles in a hierarchical tree control.

4.

On the Roles page, expand apex and click Roles.


a. b.

In the Roles table, expand the Deployment node in the Names column until you find the resource apex. Expand apex and click Roles.

5. 6.

On the Stand-Alone Web Application Scoped Roles table, click New. On Create Stand-Alone Web Applications Scoped Roles, specify the following:
a. b. c.

Name - Enter Admin Select the Provider Name for the role mapper (for example, XACMLRoleMapper). Click OK.

The Stand-Alone Web Application Scoped Roles table with the Admin role displays.
7.

Click the Admin role. The Edit Stand-Alone Web Application Scoped Roles page displays.

8.

Create a role condition, which specifies who is in the scoped role and under which set of conditions:
a. b. c.

Under Role Condition, click Add Conditions. In Predicate List, select User and click Next. In User Argument Name, add adminlistener. Then, click Add and then Finish. The user adminlistener appears.

d.

Click Save. A status message appears.

9.

Repeat the steps above starting at step 5 and create another role with the following information:
a.

Name field - Enter Manager

Installing Oracle Application Express Listener 1-11

Installing with Oracle GlassFish Server

b. c.

In the Role Conditions Predicate List for Manager, select User and add managerlistener. Once you have completed creating the Manager role, click Save.

10. If your domain is in Production Mode, in the left pane below the Change Center,

click Release Configuration.

Access Oracle Application Express Listener Administration


To access Oracle Application Express Listener Administration, in your Web browser go to:
http://<host>:<port>/apex/listenerConfigure

Next, configure Oracle Application Express Listener. See "Configuring Oracle Application Express Listener" on page 2-1.

Installing with Oracle GlassFish Server


You can install Oracle Application Express Listener with Oracle GlassFish Server. Oracle GlassFish Server is available for download from the Oracle Technology Network. See:
http://www.oracle.com/technetwork/java/javaee/downloads/index-jsp-14071 0.html

To learn more about installing Oracle GlassFish Server, see GlassFish Server Quick Start Guide and Oracle GlassFish Server Installation Guide.
Tip: This section assumes that you have completed the installation process and are familiar with GlassFish Server. If you are unfamiliar with domains, servers, applications, security, or users, see your Oracle GlassFish Server documentation.

Topics: Download and Unzip Oracle Application Express Listener


Copy Oracle Application Express Images Launch the Administration Console Create Users and Roles Install the Deployment Access Oracle Application Express Listener Administration

1-12 Oracle Application Express Listener Installation and Developer Guide

Installing with Oracle GlassFish Server

Download and Unzip Oracle Application Express Listener


For more information, see "Downloading Oracle Application Express Listener" on page 1-2.

Copy Oracle Application Express Images


Before you begin, you must copy Oracle Application Express images. To copy Oracle Application Express images:
1.

Create folder named i in:


<glassfish directory>/domains/<domainName>/docroot

2.

Copy all files and folders in the Oracle Application Express images directory:
<apex directory>/images

Tip: Do not include the images folder. Copy only the files and folders below the Oracle Application Express images folder.

Paste the copied files and folder to:


<glassfish directory>/domains/<domainName>/docroot/i

If the images are not in this location, the Oracle Application Express login page will appear to be missing images and style sheets.

Launch the Administration Console


At least one GlassFish server domain must be started before you start the Administration Console. To launch the Administration Console:
1.

Launch the Administration Console by typing the following URL in your Web browser:
http://localhost:4848

2.

If prompted, log in to the Administration Console.


Tip: You will be prompted to log in if you chose to require an administration password at the time GlassFish server was installed.

Create Users and Roles


Oracle Application Express Listener requires users be assigned roles to access Oracle Application Express Listener Administration. This section describes how to create users and roles. For more information on security realms, users, group list, or roles, see your Oracle GlassFish Server documentation. Topics: About Roles

Create Users

Installing Oracle Application Express Listener 1-13

Installing with Oracle GlassFish Server

About Roles
Oracle Application Express Listener requires you assign users roles to access the Application Express Listener Administration. There are two types of roles:

Admin - The user has permission to access the Oracle Application Express Listener Administration page. Manager - The user has permission to access the Oracle Application Express Listener Status Information Page.

You can enable a default principal-to-role mapping on the Application Server using the Admin Console if the group list names is defined the same as the role names To enable a default principal-to-role mapping:
1.

On the navigation tree, select Configuration and then Security. The Security page displays.

2. 3.

Select the check box next to Default Principal to Role Mapping. Click Save.
Tip: Enabling the Default Principal to Role requires the Group List to be the same as the role name as described in the sect section.

Create Users
You must create users to access the Oracle Application Express Administration page and Status page. To create users:
1. 2. 3. 4.

In the navigation tree, expand the Configuration node. Expand the Security node. Expand the Realms node. Select the realm to which to add your user (for example, file). The Edit Realm page appears.

5.

On the Edit Realm page, click the Manage Users button. The File Users page appears.

6.

On the File Users page, click New. The New File Realm User page appears.

7.

On the New File Realm User page, create an Admin user:


a.

User ID - Enter the name of the Oracle Application Express Listener administrator: adminlistener

b.

Group List - Enter the role to which the user belong: Admin

c. d. e.

New Password - Enter a unique password. Confirm New Password - Enter the password again. Click OK.

1-14 Oracle Application Express Listener Installation and Developer Guide

Installing with Oracle GlassFish Server

8.

Repeat the previous steps and create another user for the Oracle Application Express Listener manager, by specifying the following:
a. b. c.

User ID: managerlistener Group List: Manager Click OK.

Install the Deployment


Tip: The Oracle Application Express Listener files, apex.war must be available before you start this task. See "Downloading Oracle Application Express Listener" on page 1-2.

To install the deployment:


1.

On the navigation tree, click the Application node. The Applications page displays.

2.

Click the Deploy button. The Deploy Applications or Modules page displays.

3. 4.

Select Packaged File to be Uploaded to the Server and click Browse. Navigate to the location of the apex.war file, select the file, and click Open. The Deploy Applications or Modules page displays.

5.

On the Deploy Applications or Modules page, specify the following:


a. b. c. d. e. f.

Type: Web Application Context Root: apex Application Name: apex Status: Enabled Description: Application Express Listener Accept all other default settings and click OK.

Installing Oracle Application Express Listener 1-15

Installing with Oracle GlassFish Server

The Applications page appears. A check mark should appear in the Enabled field for apex

Tip:

If a check mark does not appear in the Enabled column for apex, then select the check box next to apex and click Enable.

Access Oracle Application Express Listener Administration


To access Oracle Application Express Listener Administration, in your Web browser go to:
http://<host>:<port>/apex/listenerConfigure

Where:

<host> is the DNS name or IP address of the Administration Server <port> is the listen port on which the Administration Server is listening for requests

Next, configure Oracle Application Express Listener. See "Configuring Oracle Application Express Listener" on page 2-1.

1-16 Oracle Application Express Listener Installation and Developer Guide

Installing with Oracle Containers for J2EE (OC4J)

Installing with Oracle Containers for J2EE (OC4J)


You can install Oracle Application Express Listener with Oracle Containers for J2EE (OC4J). Oracle Containers for J2EE (OC4J) is available for download from the Oracle Technology Network. See:
http://www.oracle.com/technetwork/middleware/ias/downloads/utilsoft-090 603.html

To learn more about installing Oracle Containers for J2EE (OC4J), see Oracle Containers for J2EE Installation Guide.
Tip: This section assumes that OC4J is already installed and you are familiar with OC4J. If you are unfamiliar with servers, deployment, security, users, and roles, refer to your Oracle Containers for J2EE documentation.

Topics: Download and Unzip Oracle Application Express Listener


Copy Oracle Application Express Images Start the OC4J Server Start the Application Server Control Console Create Users and Roles Install the Deployment Access Oracle Application Express Listener Administration

Download and Unzip Oracle Application Express Listener


For more information, see "Downloading Oracle Application Express Listener" on page 1-2.

Copy Oracle Application Express Images


Before you begin, you must copy Oracle Application Express images. To copy Oracle Application Express images:
1.

Create a folder named i in:


<oc4j install directory>/j2ee/home/default-web-app

2.

Copy all files and folders in the Oracle Application Express images directory:
<apex directory>/images

Tip: Do not include the images folder. Copy only the files and folders below the Oracle Application Express images folder.

Paste the copied files and folder to:


<oc4j install directory>/j2ee/home/default-web-app/i

If the images are not in this location, the Oracle Application Express login page will appear and be missing images and style sheets.

Installing Oracle Application Express Listener 1-17

Installing with Oracle Containers for J2EE (OC4J)

Start the OC4J Server


The default port for the OC4J Server is 8888. If you must change the port number, edit the following file:
<oc4j install directory>/j2ee/home/config/default-web-site.xml

You must start the OC4J Server before you start the Application Server Control Console. Consider the following example:
cd <oc4j install directory>/j2ee/home java -jar oc4j.jar

To learn more, see your Oracle for Containers J2EE documentation.


Tip: If this is your first-time initializing the server, you will be prompted to enter a password for the OC4J administrator account. The username for this account defaults to oc4jadmin.

Start the Application Server Control Console


To start the Application Server Control Console:
1.

Typing the following URL in your Web browser:


http://localhost:8888/em

2.

When prompted, log in with the oc4jadmin account.

Create Users and Roles


Oracle Application Express Listener requires users be assigned roles in order to access Oracle Application Express Listener Administration. This section describes how to create users and roles. For more information on security realms, users, and roles refer to your Oracle for Containers J2EE documentation. Topics: Create Roles

Create Users

Create Roles
Oracle Application Express Listener requires you assign users roles to access the Application Express Listener Administration. There are two types of roles:

Admin - The user has permission to access the Oracle Application Express Listener Administration page. Manager - The user has permission to access the Oracle Application Express Listener Status Information Page.

To create roles:
1. 2. 3. 4.

On the OC4J Home page, click the Administration tab. Expand the Security node. Locate Security Providers and click the Go To Task icon. Click Instance Level Security. The Instance Security Level page displays.

1-18 Oracle Application Express Listener Installation and Developer Guide

Installing with Oracle Containers for J2EE (OC4J)

5. 6. 7.

Click the Realms tab. Use an existing realm or create a realm. Click the selected realms Roles number. The Roles page displays.

8.

Create the role, Admin:


a. b. c.

Click the Create button. On the Name field enter Admin. Click OK.

9.

Create the role, Manager:


a. b. c.

Click the Create button. In Name, enter Manager Click OK.

Create Users
You must create users to access the Oracle Application Express Administration page and Status page. To create users:
1.

In the Instance Security Level page, click the selected realms Users number. The Users page displays.

2.

Create a user for the Oracle Application Express Listener admin:


a. b. c. d.

Click the Create button. In Name, enter adminlistener and a password. For Selected Roles, select Admin. Click OK.

3.

Create another user for the Oracle Application Express Listener manager:
a. b. c. d.

Click the Create button. In Name, enter managerlistener and specify a password. For Selected Roles, select Manager. Click OK.

4.

On the top page, click the OC4J:home link.

Install the Deployment


Tip: The Oracle Application Express Listener files, apex.war must be available before you start this task. See "Downloading Oracle Application Express Listener" on page 1-2.

To install the deployment:


1.

On the OC4J Home page, click the Applications tab. The Applications page displays.

Installing Oracle Application Express Listener 1-19

Upgrading Oracle Application Express Listener

2.

Click the Deploy button. The Deploy: Select Archive page displays.

3.

On the Deploy: Select Archive page:


a. b. c.

Select Archive is present on local host. Upload the archive to the server where Application Server Control is running. Specify the location of the apex.war. file. Click Next.

The Deploy: Application Attributes page displays.


4.

In the Application Name field, enter apex and click Next. The Deploy: Deployment Settings displays.

5.

In the Deployment Tasks, click Configure Class Loadings Go To Task. The Deployment Settings: Configure Class Loading page displays.

6.

On the Deployment Settings: Configure Class Loading page:


a.

In the Import Shared Libraries, deselect the Inherit parent applications shared library imports check box. Oracle Application Express Listener contains its own libraries in the apex.war file and does not use the OC4J Shared Libraries. Also, verify that the Import column check boxes for all the Shared Library deselected.

b. 7.

Click OK.

Click the Deploy button. A confirmation message with the following message displays:
The Application apex has been successfully deployed.

8. 9.

Return to the Application page by clicking the Return button. Verify that apex is listed on the Applications page and the Status displays a green up-arrow indicating that it is Active.

Access Oracle Application Express Listener Administration


To access Oracle Application Express Listener Administration, in your Web browser go to:
http://<host>:<port>/apex/listenerConfigure

Next, configure Oracle Application Express Listener. See "Configuring Oracle Application Express Listener" on page 2-1.

Upgrading Oracle Application Express Listener


Upgrading Oracle Application Express Listener requires that you redeploy the application.
Tip: Before you begin the upgrade process, you must download and unzip Oracle Application Express Listener. See "Downloading Oracle Application Express Listener" on page 1-2.

1-20 Oracle Application Express Listener Installation and Developer Guide

Upgrading Oracle Application Express Listener

Topics: Redeploy Oracle WebLogic Server


Redeploy Oracle GlassFish Server Redeploy Oracle Containers for J2EE (OC4J)

Redeploy Oracle WebLogic Server


This section describes how to upgrade Oracle Application Express Listener when Oracle WebLogic Server. To redeploy Oracle WebLogic Server:
1. 2. 3.

Download and unzip Oracle Application Express Listener. See "Downloading Oracle Application Express Listener" on page 1-2. Start an Administration Server domain. Launch the Administration Server console:
a. b.

Start an Administration Server. Launch the WebLogic Administration Console by typing the following URL in your Web browser:
http://<host>:<port>/console

Where:
c. d.

<host> is the DNS name or IP address of the Administration Server <port> is the listen port on which the Administration Server is listening for requests (port 7001 by default)

Enter the WebLogic Administrator username and password. If your domain is in Production mode, click the Lock & Edit button on the left-pane below the submenu Change Center. If your domain is in Development mode this button will not appear.

4.

Go to the WebLogic Server Home Page. Below the Domain Configuration, select Deployments. The Summary of Deployments displays.

5. 6.

Click the check box next to apex to enable the Update button. Click the Update button. The Update Application Assistant displays.

7. 8. 9.

Specify the location of your apex.war file. Click Next. Review your choices and click the Finish button. The Summary of Deployments. Messages appear indicating the status of apex deployment.

10. Follow any additional instructions provided in the Messages. 11. If your domain is in Production Mode, on the Change Center click Activate

Changes.

Installing Oracle Application Express Listener 1-21

Upgrading Oracle Application Express Listener

Redeploy Oracle GlassFish Server


To redeploy Oracle GlassFish Server:
Tip: At least one GlassFish server domain must be started before you start the Administration Console.
1. 2.

Unzip Oracle Application Express Listener. See "Downloading Oracle Application Express Listener" on page 1-2. Launch the Administration Console:
a.

Launch the Administration Console by typing the following URL in your Web browser:
http://localhost:4848

b.

If prompted, log in to the Administration Console.


Tip: You will be prompted to log in if you chose to require an administration password at the time GlassFish server was installed.

3.

On the navigation tree, click the Application node. The Applications page displays.

4. 5.

Select the check box next to apex. Click the Disable button. An X appears in the Enabled field next to apex.

6.

Click the Redeploy link for apex. The Redeploy Applications or Modules page displays.

7. 8.

Specify the location of your apex.war file. Click OK. The Application page appears.

9.

Verify that a check mark displays on the Enabled field next to apex.

Redeploy Oracle Containers for J2EE (OC4J)


To redeploy Oracle Containers for J2EE (OC4J):
1. 2.

Unzip Oracle Application Express Listener. See "Downloading Oracle Application Express Listener" on page 1-2. Start the OC4J Server. See "Start the OC4J Server" on page 1-18.
Tip: You must start the OC4J Server before you start the Application Server Control Console.

3.

To start the Application Server Control Console:


a.

Typing the following URL in your Web browser:


http://localhost:8888/em

b. 4.

When prompted, log in with the oc4jadmin account.

On the navigation tree, click the Application node.

1-22 Oracle Application Express Listener Installation and Developer Guide

Upgrading Oracle Application Express Images

The Applications page displays.


5.

Click the check box next to apex and then select the Redeploy button. The Redeploy: Select Archive and deployment plan page displays.

6. 7.

Specify the location of your apex.war file. Click Next. The Redeploy: Application Attributes page displays.

8. 9.

Review the information. Click Next. The Redeploy: Deployment Settings displays.

10. Click the Redeploy button.

The Applications tab appears.


11. Verify that the apex Status displays a green up-arrow indicating that the Status is

Up (Active).

Upgrading Oracle Application Express Images


If you are upgrading Oracle Application Express, you must copy the Oracle Application Express images from the upgraded version. Having Oracle Application Express images on your application server from a previous release, will result in errors. Topics: Copy Application Express Images When Using Oracle WebLogic Server

Copy Application Express Images When Using Oracle GlassFish Server Copy Application Express Images When Using Oracle Containers for J2EE (OC4J)

Copy Application Express Images When Using Oracle WebLogic Server


To copy Application Express images when using Oracle WebLogic Server:
1. 2. 3.

Create a Web archive for the images directory. See "Create Web Archive for Oracle Application Express Images" on page 1-5. Start an Administration Server domain. Launch the Administration Server console:
a. b.

Start an Administration Server. Launch the WebLogic Administration Console by typing the following URL in your Web browser:
http://<host>:<port>/console

Where:
c.

<host> is the DNS name or IP address of the Administration Server <port> is the listen port on which the Administration Server is listening for requests (port 7001 by default)

Enter the WebLogic Administrator username and password.

Installing Oracle Application Express Listener 1-23

Upgrading Oracle Application Express Images

d.

If your domain is in Production mode, click the Lock & Edit button on the left-pane below the submenu Change Center. If your domain is in Development mode this button will not appear.

4.

Go to the WebLogic Server Home Page. Below the Domain Configuration, select Deployments. The Summary of Deployments displays.

5. 6.

Click the check box next to i to enable the Update button. Click the Update button. The Update Application Assistant displays.

7. 8. 9.

Specify the location of your i.war file. Click Next. Review your choices and click the Finish button. The Summary of Deployments. Messages appear indicating the status of apex deployment.

10. Follow any additional instructions provided in the Messages. 11. If your domain is in Production Mode, on the Change Center click Activate

Changes.

Copy Application Express Images When Using Oracle GlassFish Server


To copy Application Express images when using GlassFish Enterprise Server:
1.

Delete all files and folders in folder i in:


<glassfish directory>/domains/<domainName>/docroot/i

2.

Follow the instructions in "Copy Oracle Application Express Images" on page 1-13.

Copy Application Express Images When Using Oracle Containers for J2EE (OC4J)
To copy Application Express images when using J2EE (OC4J):
1.

Delete all files and folders in folder i in:


<oc4j install directory>/j2ee/home/default-web-app/i

2.

Follow the instructions in "Copy Oracle Application Express Images" on page 1-17.

1-24 Oracle Application Express Listener Installation and Developer Guide

2
2

Configuring Oracle Application Express Listener


This section explains how to use Oracle Application Express Listener Administration to configure Oracle Application Express Listener. It describes how to set up a database connection, configure security, define file caching, create pre and post processing procedures, and perform other tasks. Topics: Accessing Oracle Application Express Listener

About Oracle Application Express Listener Administration Establishing a Database Connection Configuring Security Defining Caching Creating Pre- Post Processing Procedures Viewing Status Configuring Miscellaneous Options

Accessing Oracle Application Express Listener


Oracle Application Express Listener Administration enables you to configure Oracle Application Express Listener. Note that some of the URLs listed in the section require the user have a specified role. To learn more, see the section for creating users and roles for your application server in "Installing Oracle Application Express Listener" on page 1-1. Topics: Access Oracle Application Express Listener Administration

View Status Information

Access Oracle Application Express Listener Administration


To access Oracle Application Express Listener Administration initially, enter the following URL in your Web browser:
http://<host>:<port>/apex/listenerConfigure

Configuring Oracle Application Express Listener

2-1

About Oracle Application Express Listener Administration

Once you have completed the configuration process, use the following URL to access Oracle Application Express Listener Administration:
1.

In your Web browser, enter the following URL:


http://<host>:<port>/apex/listenerAdmin

2.

When prompted, enter your credentials. Note that in order to log in using this URL, a user must have the Admin role.

View Status Information


You can view Oracle Application Express Listener Status information, by entering the following URL in your Web browser:
http://<host>:<port>/apex/listenerStatus

Note that in order to log in using this URL, a user must have the Manager role.

About Oracle Application Express Listener Administration


This section describes the Oracle Application Express Listener Administration user interface which is separated into six categories:

Connection - See "Establishing a Database Connection" on page 2-2. Security - "Configuring Security" on page 2-5. Caching - "Defining Caching" on page 2-9. Pre-Post Processing - "Creating Pre- Post Processing Procedures" on page 2-10. Status - "Viewing Status" on page 2-11. Miscellaneous - "Configuring Miscellaneous Options" on page 2-12.
Tip: Every category (or tab) has an Apply button. Every time you click Apply, Oracle Application Express Listener Administration saves the information and returns you to the defined default Web page. If you need to update information on multiple tabs, make all your updates and then click Apply.

Establishing a Database Connection


Use the Connection tab to enter database credentials. Key elements of this page include:

Username - Defines the name of the database user for the connection. Password - Defines the password of the specified database user. Connection Type - Select Basic, TNS, or Advanced. The fields that display depend on the type selected.

Note that Username, Connection Type, Port, and SID contain default values. Topics: Establish a Basic Connection Establish a TNS Connection Establish an Advanced Connection

2-2 Oracle Application Express Listener Installation and Developer Guide

Establishing a Database Connection

About JDBC Settings

Establish a Basic Connection


To configure a basic database connection:
1. 2. 3. 4. 5.

Click the Connection tab. For Username, enter the name of the database user for the connection. For Password, enter the password of the specified database user. For Connection Type, select Basic. Specify the following:
a. b.

Hostname - Enter host system for the Oracle database. Port - Enter the database listener port.

6.

Select one of the following:


SID - Enter the name of the database. Service name - Network service name of the database.

7.

Click Apply.

Establish a TNS Connection


To configure a TNS database connection:
1. 2. 3. 4. 5.

Click the Connection tab. For Username, enter the name of the database user for the connection. For Password, enter the password of the specified database user. For Connection Type, select TNS. Specify the following:
a. b.

TNS Alias Name - The TNS alias name must match the name in the tnsnames.ora file. TNS Directory - The directory location of your tnsnames.ora file.

If you define the environment variables TNS_ADMIN or ORACLE_HOME, then the listener checks if the file, tnsnames.ora, exists in either the TNS_ADMIN directory or [ORACLE_HOME]/NETWORK/ADMIN directory. If the file exists, then the TNS Directory will contain the default directory location. Otherwise, the user required to specify the TNS Directory.
6.

Click Apply.

Establish an Advanced Connection


You can specify a custom JDBC URL to connect to the database by selecting the Connection Type, Advanced on the Connection tab. To configure an Advanced database connection:
1. 2. 3.

Click the Connection tab. For Username, enter the name of the database user for the connection. For Password, enter the password of the specified database user.

Configuring Oracle Application Express Listener

2-3

Establishing a Database Connection

4.

For Connection Type, select Advanced. The Custom JDBC URL field displays.

5.

In Custom JDBC URL, enter a custom URL. You can specify different formats for the custom JDBC URL. Consider the following examples:

SID:
jdbc:oracle:thin:<host>:<port>:<sid>

Example:
jdbc:oracle:thin:myhost:1521:orcl jdbc:oracle:oci8:myhost:1521:orcl

Service name:
jdbc:oracle:thin:@//<host>:<port>/<servicename>

Example:
jdbc:oracle:thin:@//myhost:1521/orcl.us.oracle.com

Oracle Net keyword-value pair:


jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=myhost)(PORT=15 21))(CONNECT_DATA=(SERVICE_NAME=myservicename.com)))

6.

Click Apply.
See Also: Oracle Database Net Services Administrator's Guide for more information about connection formats.

About JDBC Settings


Use the JDBC Settings section of the Connection tab to configure JDBC option. To configure JDBC settings:
1. 2. 3. 4. 5. 6.

Click the Connection tab. For Username, enter the name of the database user for the connection. For Password, enter the password of the specified database user. For Connection Type, select a connection type. To expand the JDBC Settings heading, click JDBC Settings. Specify the following:

JDBC Driver Type - Select either thin or oci8. Initial Pool Size - Specify the initial pool size for the number of connections that will be created. Minimum Connections - Define the minimum number of connections. Maximum Connections - Specify the maximum number of connections. Maximum Statements - Define the maximum number of statements to cache for each connection.

2-4 Oracle Application Express Listener Installation and Developer Guide

Configuring Security

Inactivity Timeout - Indicate how long (in seconds) an available connection can remain idle before it is closed. Abandoned Connection Timeout - Determine how long a borrowed (in use) connection can remain unused (in seconds) before it is considered as abandoned and reclaimed.

7.

Click Apply.
Tip: Except for the JDBC Driver type, JDBC options can also be changed during run time

Configuring Security
Use the Security tab to validate procedure requests and determine if a user is allowed to access the procedure. Click each section heading to expose the content. Topics: About Allowed Procedures

About Blocked Procedures About the Internal Exclusion List About Database Validation Function About Security Settings Understanding Security Processing

About Allowed Procedures


Use Allowed Procedures to specify procedures, packages, or schema names that can be executed from the Web browser. To specify Allowed Procedures:
1. 2. 3.

Click the Security tab. Click Allowed Procedures to expand or hide the content. In Inclusion list, enter the procedure name or procedure patterns separated by commas.

Note that the wildcard characters asterisk (*) and question mark (?) are supported. Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character.

Configuring Oracle Application Express Listener

2-5

Configuring Security

If the Inclusion list field is left blank, then the Oracle Application Express Listener does not validate the procedure names to determine if the procedure is allowed for processing.
4.

Click Apply.
Tip: The advantage of using Allowed Procedures is that the procedure names and procedure patterns are stored in the Oracle Application Express Listener, whereas invoking the Database Validation Function requires a database round-trip.

Advantages of Allowed Procedures


The advantage of using Allowed Procedures is that the procedure names and procedure patterns are stored in the Oracle Application Express Listener. In contrast, invoking the Database Validation Function requires a database round-trip.

About Blocked Procedures


Use Blocked Procedures to specify procedures, packages, or schema names that cannot be executed from the Web browser. To specify Blocked Procedures:
1. 2. 3.

Click the Security tab. Click Blocked Procedures to expand or hide the content. In Inclusion list, enter the procedure name or procedure patterns separated by commas.

Note that the wildcard characters asterisk (*) and question mark (?) are supported. Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character. If the Exclusion list field is left blank, then the Oracle Application Express Listener does not validate the procedure names to determine if the procedure is allowed for processing.
4. 5.

To disable this feature, select Disable Default Internal Exclusion List. See "About the Internal Exclusion List" on page 2-6. Click Apply.

About the Internal Exclusion List


The Oracle Application Express Listener includes an internal exclusion list which blocks users from accessing the following:

2-6 Oracle Application Express Listener Installation and Developer Guide

Configuring Security

sys.*, dbms_*, utl_*, owa_*, owa.*, htp.*, htf.*, wpg_docload.*

This option enables you to disable the default internal exclusion list, however, Oracle does not recommend this approach. Instead, Oracle recommends using the external exclusion list solely for debugging purposes. Disabling the Internal Exclusion List To disable the internal exclusion list:
1. 2. 3. 4.

Click the Security tab. Click Blocked Procedures to expand the content. Select the Disable Default Internal Exclusion List check box. Click Apply.

About Database Validation Function


Use Database 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. To learn more, see "About Security Settings" on page 2-8. To specify a Database Validation Function:
1. 2. 3.

Click the Security tab. Click Database Validation Function to expand or hide the section. In the field provided, enter the name of the Database Validation Function.

The validation function you specify is a stored function that resides in the database. If the validation function you specify does not exist, an error message displays. The validation function returns true if the procedure is allowed for processing. Otherwise, it returns false. If the Validation Functions field is left blank, then Oracle Application Express Listener does not validate the procedure name to determine if the procedure should be allowed for processing.
4.

Click Apply.

About the Database Validation Function Format


The validation function must return a boolean and have one argument for the procedure name. Consider the following example:
CREATE OR REPLACE FUNCTION CHECK_VALID_PROCEDURE (Procedure_Name IN VARCHAR2) RETURN BOOLEAN AS BEGIN IF (UPPER(Procedure_Name) LIKE ('CUST%')) THEN

Configuring Oracle Application Express Listener

2-7

Configuring Security

RETURN true; ELSE RETURN false; END IF; END CHECK_VALID_PROCEDURE;

About Security Settings


When you specify a Database 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 above Validation Function. To specify Security Settings:
1. 2.

Click the Security tab. Click Security Settings to expand or hide the content.

3.

Specify the following:

Maximum Cache Entries - Specify the 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 - Displays the 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, then the Clear Cache button displays, enabling you to delete the cache entries. As a best practice, clear the cache whenever a Database Validation Function is updated.

4.

Click Apply.

Understanding Security Processing


If the user enters data for Allowed Procedures, a Database Validation Function, or Blocked Procedures, the Oracle Application Express Listener determines if the entered procedure name is valid by checking the security information in the following order:
1. 2. 3.

Database Validation Function - Checks if the procedure name is valid. Allowed Procedures - Checks if the procedure name is in the inclusion list. Blocked Procedures - Checks if the procedure is NOT in the exclusion list.

If these validations pass, then the procedure is valid for processing.

2-8 Oracle Application Express Listener Installation and Developer Guide

Defining Caching

Defining Caching
The Oracle Application Express Listener enables you to cache file-based content for quick access. Caching is only enabled if you specify the procedure names. Topics: Specify Procedure Names to Cache Files

Specify Procedure Names to Cache Files


To specify procedure names to allow the caching of files:
1.

Click the Caching tab. The Cache Files page appears.

2.

Specify the following:


Description Specify the procedure names to allow for caching of their files. The procedure names can contain the wildcard characters asterisk (*) and question mark (?). Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character Separate multiple procedures with a comma, for example: p, wwv_flow_file*, download_my_file

Option Procedure Name

Keep most recently used files Maximum entries

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. If selected, files that are cached expire after the specified length of time. Specify the length of time after the files expire. Note the selected value must be a numeric value greater than 0. Select the amount of time from the list. Options include: days, hours, or minutes.

Keep files for the specified duration Expires after duration

Configuring Oracle Application Express Listener

2-9

Creating Pre- Post Processing Procedures

Tip: Once you specify a Procedure Name, the Keep files for the specified duration and Keep most recently used files button are enabled.
3.

To configure Cache Settings, click Cache Settings.

Specify the following Cache Settings options:


a. b. c. 4.

Total Cache Entries - Displays the total number of files that are cached. Clear Cache - If the total cache entries is greater than zero, then the Clear Cache button displays, enabling you to delete the cache entries. Directory - Specify the directory location for the cache files.

Click Apply.

Creating Pre- Post Processing Procedures


Click the Pre-Post Procedures tab to specify database procedures to invoke before or after executing the procedure specified on the URL. Topics: About Pre-processing Procedures

About Post-processing Procedures

About Pre-processing Procedures


Click Pre-Processing to expand or hide this section. In Procedure Names, enter the procedure names to execute after executing the procedure specified on the URL and click Apply. Separate multiple procedure names with a comma.

Oracle Application Express Listener executes the procedures in the order specified in the Procedure Names field (for example, proc1, proc2, . . . , procN).

About Post-processing Procedures


Click Post-Processing to expand or hide this section. In Procedure Names, enter the procedure names to execute after executing the procedure specified on the URL and click Apply. Separate multiple procedure names with a comma.
2-10 Oracle Application Express Listener Installation and Developer Guide

Viewing Status

Oracle Application Express Listener executes the procedures in the order specified in the Procedure Names field (for example, proc1, proc2, . . . , procN).

Viewing Status
Click the Status tab to view statistics, error tracking, and logging information.
Tip:

Users with the manager role only see the Status tab.

Topics: About Statistics


About Error Tracking About Logging

About Statistics
Click Statistics to expand or hide this section. Statistics displays the following Oracle Application Express Listener information:

Server uptime. Total accesses, total traffic, total errors, total file downloads, and total processing time. Processing time in milliseconds for minimum, average, median, and maximum. Database time in milliseconds for minimum, average, median, and maximum. Active requests. Active and available connections in the pool. Security enabled or disabled, and its cache entries and maximum entries. Cache file enabled or disabled, and its cache entries and maximum entries.

Configuring Oracle Application Express Listener 2-11

Configuring Miscellaneous Options

About Error Tracking


Click Error Tracking to expand or hide recent error message. Message display in descending order. Error Tracking provides the total number of errors, date, time, and elapsed time for each error message.

About Logging
Click Logging to expand or hide the log of the different types of activities that occur 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.

Configuring Miscellaneous Options


The Miscellaneous tab provides various configuration options, including specifying the default Web page, enabling the different types of error reporting, and whether to clear logging. To specify options on the Miscellaneous tab:
1.

Click the Miscellaneous tab. The Miscellaneous tab appears.

2-12 Oracle Application Express Listener Installation and Developer Guide

Configuring Miscellaneous Options

2.

Specify the following options. Under Error Reporting:


Default Web Page - Specify the default page to display (for example, apex). Show debug messages on console - Select this option to display debugging messages on the application server console. Show error messages on browser - Select this option to display error messages on the browser. Keep most recent error messages - Select this option to retain the error messages. Maximum Error Entries - Specify the total number of error messages to retain. Total Error Entries - If the total error entries is greater than zero, then the Clear Cache button is enabled. Click the Clear Cache button to delete the error entries.

Under Logging:

Keep most recent log messages - Select this option to retain log messages. Maximum Log Entries - Specify the total number of error messages to retain. Total Log Entries - If the total log entries is greater than zero, then the Clear Cache button is enabled. Click the Clear Cache button to delete log entries.

3.

Click Apply. If the Oracle Application Express Listener detects missing data or incorrect information, then an error message displays. When saved, the data is written to the Oracle Application Express Listener configuration file and the specified default Web page appears.
See Also:

"About the Configuration File" on page A-1

Configuring Oracle Application Express Listener 2-13

Configuring Miscellaneous Options

2-14 Oracle Application Express Listener Installation and Developer Guide

3
3

RESTful APIs and Resource Templates


This section describes how to use Oracle Application Express Listener RESTful Application Programming Interfaces (APIs) to expose data stored in an Oracle database. Topics: What is a RESTful API?

About Resource Template Administration About Resource Handler Types Example: Creating an Image Gallery About Resource Template Security

What is a RESTful API?


Representational State Transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. An API is described as RESTful when it conforms to the tenets of REST. Although a full discussion of REST is outside the scope of this document, a RESTful API has the following characteristics:

Data is modelled as a set of resources. Resources are identified by URLs. A small set of operations are used to manipulate resources (for example, PUT, POST, GET, DELETE). A resource can have multiple representations (for example, a blog might have a HTML representation and a RSS representation). Services are stateless and since it is likely that the client will want to access related resources, these should be identified in the representation returned, typically by providing hypertext links.

About Resource Templates


RESTful APIs are created by configuring resource templates. A resource template is a configuration file that binds a set of Uniform Resource Identifiers (URIs) to a SQL query or anonymous PL/SQL block. The set of URIs is identified by a URI template. A URI template is simple syntax for describing URIs, for example:
people/{userid}

The URI template may contain zero or more parameters (for example, {userid}) which along with the HTTP headers sent with a HTTP request can be bound to parameters in the SQL query or anonymous PL/SQL block.
RESTful APIs and Resource Templates 3-1

About Resource Template Administration

About Resource Template Administration


To access the Resource Template Administration, go to:
1.

In your Web browser, go to:


http://<hostname>:<port>/apex/resourceTemplates/

2.

Enter your Oracle Application Express Listener Administrator credentials. The Oracle Application Express Listener Administration Resource Templates page appears.

The Oracle Application Express Listener Administration Resource Templates page displays a list of the currently defined resource templates and provides buttons to create a new resource template, import resource template definitions, and to export the existing definitions to a zip file. Topics: Create a Resource Template About the Entity Tag About Resource Handlers

Create a Resource Template


A resource template is a configuration file that binds a set of Uniform Resource Identifiers (URIs) to a SQL query or anonymous PL/SQL block. To create a new resource template, click Add Resource Template. A pre-populated sample resource template displays. Hover the mouse over a field on the page to see a tooltip that describes the purpose of the field.

About URI Templates


Uniform Resource Identifier (URI) template is a compact syntax for describing a range of URIs. For example, assume the Oracle Application Express Listener is running on a machine named example.com then the URI Template hello?who={person} would match the following URI:
http://example.com/apex/hello?who=World

The literal value World is bound to the URI Template parameter named person. About URI Template Grammar Currently there is no standardized URI Template syntax. Oracle Application Express Listener supports a limited subset of the current draft specification. The following grammar rules apply:

URI Templates must not start with a slash (/) character. URI Templates can contain any Unicode character. Parameters are declared with the use of curly braces ({}) Parameter names must start with an alphabetic character followed by zero or more alphanumeric characters and the characters: underscore (_) or hyphen (-). There is no support for optional parameters.

3-2 Oracle Application Express Listener Installation and Developer Guide

About Resource Template Administration

About the Entity Tag


An entity tag (ETag) is a HTTP Header that acts as a version identifier for a resource. Use ETag headers to avoid retrieving previously retrieved resources and to perform optimistic locking when updating resources. Oracle Application Express Listener provides three strategies for generating entity tags:

Secure Hash - The contents of the returned resource representation are hashed using a secure digest function to provide a unique fingerprint for a given resource version. Query - Manually define a query that uniquely identifies a resource version. Instead of hashing the entire resource representation, only the result of the query is hashed. A manually defined query can often generate an entity tag more efficiently than hashing the entire resource representation. None - Do not generate an entity tag.

About Resource Handlers


A resource handler is a query or an anonymous PL/SQL block responsible for handling a particular HTTP method. Although multiple resource handlers can be defined for a resource template, only one handler per HTTP method is permitted. Topics: Add Other Handlers

About Supported HTTP Methods Strategies When Choosing a Resource Handler Type About Resource Handler Parameters Referencing Parameters About Acceptable Media Types About Security Constraints

Add Other Handlers


To add other handlers to a resource template:
1.

Click the Add Handler button. The Add HTTP Method Handler dialog box appears.

2. 3.

Choose the HTTP method you wish to implement. See "About Supported HTTP Methods" on page 3-3. Click Add. Each resource handler displays as a separate tab identified by the HTTP method that it implements.

About Supported HTTP Methods


The HTTP specification defines several standard methods which are used to operate on a resource. The four most commonly used operations are:

GET - Retrieves a representation of a resource POST - Creates a new resource or adds a resource to a collection
RESTful APIs and Resource Templates 3-3

About Resource Template Administration

PUT - Updates an existing resource DELETE - Deletes an existing resource

Strategies When Choosing a Resource Handler Type


Many different strategies are supported for generating representations:

Comma Separated Values Query - Executes an SQL and transforms the result set into a CSV representation. Query - Executes an SQL Query and transforms the result set into a JSON (JavaScript Object Notation) representation. A specialization of this strategy, generates a single JSON result. Note that the result is not wrapped in a JSON array. PL/SQL Block - Executes an anonymous PL/SQL block and transforms any OUT or INOUT parameters into a JSON representation. Media Resource - Executes a SQL Query conforming to a specific format and turns the result set into a binary representation with an accompanying HTTP Content-Type header identifying the internet media type of the representation.

About Resource Handler Parameters


Parameters declared in the URI template are implicitly passed to the resource handler. For example if the URI template is people/{userid} then a parameter userid is automatically made available to the resource handler. Parameters to a resource handler can also be manually defined to bind HTTP headers to the resource handler, or to cast a URI template parameter to a specific data type. For example, a resource handler might need to know the value of the HTTP Accept-Language header in order to localize the generated representation. To add a parameter:
1. 2.

Click the Add Parameter button. Specify the following:

Name - Enter the name of the parameter as passed to the resource handler (required). Aliasing - Enter the original name of the parameter if you wish to rename a parameter (optional). Source - Enter either the header (that is, the HTTP header) or URI (that is, the parameter from the URI template). Access - IN, INOUT, or OUT. URI Template parameters can only be IN. A value of IN for a header parameter implies the header will be present in the HTTP request. A value of INOUT indicates the value will be present in both the HTTP request and response. A value of OUT indicates the value will only be present in the HTTP response. Type - The primitive data type of the parameter: String, Integer, Double, Boolean, or Long
Tip:

To delete a parameter, select the icon on the immediate right.

Referencing Parameters
You can reference parameters in the resource handler definition by prefixing the parameter name with a colon character, for example:
3-4 Oracle Application Express Listener Installation and Developer Guide

About Resource Handler Types

select 'Hello ' || :person || ' from APEX' greeting from dual

This example causes the :person token to be replaced with the actual value of the person parameter when the resource template is evaluated. Parameter substitution uses the standard Oracle Prepared Statement facilities, so the normal rules apply as to when and where parameters can be placed. For example the following example is not valid, because the table name cannot be specified using a parameter:
select * from :table where some_id = :id

About Acceptable Media Types


For resource handlers that accept a content body (POST and PUT), you can define what types of content the handler is able to accept by specifying acceptable MIME types in the Acceptable field. You can specify more than one content type by separating types with a comma. You can also specify a wildcard character to accept a range of types, for example:
image/*

About Security Constraints


Resource handlers can define a security constraint to provide a degree of access control. You can specify the following options:

None - Any user is allowed access to the resource. Authenticated - A user must be logged in to access the resource. Secure - The resource must be accessed over a secure channel (for example, HTTPS). Secure & Authenticated - User must be logged in and the channel must be secure.

The security constraint can only be applied when the Oracle Application Express Listener is correctly configured to use one of the supported security configurations. For more information, see "About Resource Template Security" on page 3-16

About Resource Handler Types


This section describes supported resource handler types. Topics: Query

Comma Separated Values Query Media Resource PL/SQL Block

Query
This resource handler type evaluates the supplied query and turns the resulting rows into a JSON representation. Consider the following example:
select 'Hello ' || :person || ' from APEX' greeting from dual

RESTful APIs and Resource Templates

3-5

About Resource Handler Types

This example generates a response similar to the following:


{ "items": [ { "greeting":"Hello World from APEX" } ] }

In this example:

The Content-Type of the response will be application/json The root the JSON document will be a JSON Object The JSON Object will contain a property named: items The value of the property will be an array Each row in the result set will map to a JSON object Each column in a row will map to a JSON property The column name will always be in lower-case and the case of the value will be preserved If the query has no results, the items property referred to above will just contain an empty array

Since a query can only retrieve data and can never change the state of the database, the Query resource handler can only be used the HTTP GET Method.

With One Result Only


A variation of the Query resource handler enables the production of JSON resources that correspond to a result set with exactly one row, for example:
select * from oe.orders where order_id = :id

This example generates a response similar to:


{ "order_id":2458, "order_date":"2007-08-16T21:34:12.234Z", "order_mode":"direct", "customer_id":101, "order_status":0, "order_total":78279.6, "sales_rep_id":153 }

If an invalid order_id value is provided then a 404 - Not Found response is generated.

Comma Separated Values Query


This resource handler type is very similar to the Query resource handler except that the results are returned as a comma separated values instead of JSON. Consider the following example:
select * from oe.categories_tab

This example generates a response similar to:

3-6 Oracle Application Express Listener Installation and Developer Guide

About Resource Handler Types

hardware4,memory components/upgrades,14,10 hardware5,"processors, sound and video cards, network cards, motherboards",15,10 ...

In this example:

Each column is delimited by a comma Each row is delimited by a new line character Columns containing commas or double quotes will be quoted with the double quote character

Media Resource
This resource handler type evaluates a specially structured SQL query and returns the resulting row as a binary representation. The query must follow the following format:
select <content_type>, <content_body> from ... where ...

In this format:

The query must return one row and one row only The result set must consist of two columns: The first <content_type> must be a string indicating the internet media type of the representation The second <content_body> must contain the content of the representation. This column must be one of the following types: VARCHAR, CLOB, BLOB, RAW, LONG RAW, or XMLType

Similar to the Query resource handler, the Media resource handler can only be used for the HTTP GET method, since it can only evaluate an SQL Query. This resource handler type is very useful for generating XML and HTML representations. The following example generates a KML representation of customer locations by state, making it possible to easily share customer location data with GIS applications:
select 'application/vnd.google-earth.kml+xml', xmlquery(' <k:kml xmlns:k="http://www.opengis.net/kml/2.2"> <k:Folder> <k:name>{$state}</k:name> { for $c in ora:view("oe","customers")/ROW let $loc := $c/CUST_GEO_LOCATION/SDO_POINT where $c/CUST_ADDRESS/STATE_PROVINCE = $state return <k:Placemark> <k:name>{concat($c/CUST_FIRST_NAME," ", $c/CUST_LAST_NAME)}</k:name> <k:Point> <k:coordinates>{$loc/X/text()}, {$loc/Y/text()},0</k:coordinates> </k:Point> </k:Placemark> } </k:Folder> </k:kml>' passing :state as "state" returning content) from dual

RESTful APIs and Resource Templates

3-7

About Resource Handler Types

PL/SQL Block
This resource handler type evaluates the supplied PL/SQL block and turns any outbound parameters into a JSON representation. This resource handler type is typically used to service HTTP POST,PUT and DELETE operations. This handler has several features aimed at increasing ease of use, including:

When a HTTP request includes a content body, two parameters named :contentType and :body are automatically passed to the handler. The former provides the Content-Type of the request and the latter provides the content body of the request as a BLOB. When the HTTP request includes a content body with a Content-Type of application/x-www-form-urlencoded, the body is automatically parsed and each field in the form is converted to a parameter passed to the handler. The PL/SQL block can indicate the HTTP Status code using the X-APEX-STATUS-CODE response header. The PL/SQL block can indicate the location of the updated resource using the X-APEX-FORWARD response header.

For example, suppose you have a Resource Template with the following definition:

URI Template - gallery/ HTTP Method - POST Handler Type - PL/SQL Block

Assume the following parameters are defined:


Name name status location Aliasing Slug X-APEX-STATUS-CODE X-APEX-FORWARD Source Header Header Header Access IN OUT OUT Type String Integer String

Assume the following PL/SQL block is defined:


declare begin insert into scott.gallery values(:name,:contentType,:body); :status := 201; :location := 'gallery/' || :name; end;

The above handler inserts the supplied image into the scott.gallery table, returns the location of the stored image, and indicates the operation created a new resource. Note the following:

The :contentType and :body parameters are automatically passed to the handler. You do not need to define them manually. You must manually define the :name parameter to map it from the Slug header. The :status parameter is mapped to the X-APEX-STATUS-CODE header as an Integer. The value of 201 is specified by HTTP to indicate a new resource was created. The :location parameter is mapped to the X-APEX-FORWARD header.

3-8 Oracle Application Express Listener Installation and Developer Guide

Example: Creating an Image Gallery

When the Oracle Application Express Listener sees this header in the response, it abandons generating a JSON representation of the outbound parameters and attempts to return a representation of the indicated location. Note that this example assumes that there is a separately defined Resource Template that retrieves resources of the form gallery/<name>.

Example: Creating an Image Gallery


This example builds an image gallery that displays thumbnails of all images and upload new images. Additionally, this example creates a Web application suitable for use with modern Web browsers and a RESTful API for non-browser-based clients. Topics: Before You Begin

Create a Database Schema Upload Images Create an Image Upload Form Display the Image Display the Gallery Improve the Appearance of the Gallery About the RESTful API

Before You Begin


This section describes some common conventions used in this example as well as best practices regarding API entry points. Topics: About URIs

About API Entry Points

About URIs
Throughout this example, URIs and URI Templates are referenced using an abbreviated form that omits the host name and context path. Consider the following example:
gallery

To access this URI in your Web browser, you would use a URI in the following format:
http://<host>:<port>/apex/gallery

Where:

<host> is the host on which the Oracle Application Express Listener is running. <port> is the port on which the Oracle Application Express Listener is running. apex is the Web application context where the Oracle Application Express Listener is deployed.

RESTful APIs and Resource Templates

3-9

Example: Creating an Image Gallery

About API Entry Points


In RESTful designs it is a best practice to have only one well known entry point. This minimizes the hard-coded footprint of the API, making it much easier to evolve the API over time. In this example, the entry point of our application will be a URI named:
gallery

This URI will provide a HTML representation that:

Enumerates all the images in the gallery. For each image, you must know: The URI of the image The title of the image

Provides a link to the URI to which to post new images Provides a link to an alternate JSON representation of the gallery that includes all the information above

Create a Database Schema


First, create two tables and two sequences to store the image gallery data. Note this exercise assumes that you have configured Oracle Application Express Listener to connect to the database using apex_public_user. Execute the following scripts as the database user, scott.
create sequence gallery_seq; / grant select on gallery_seq to apex_public_user; / create table gallery (image_id number, title varchar2(1000), content_type varchar2(1000), image blob); / grant all on gallery to apex_public_user;

Upload Images
This gallery URI functions as the endpoint to which clients can submit new images. The upload facility should be able to accept requests containing the actual image data and also requests containing multipart form-data (as generated by HTML forms). To build the upload features:
1.

Create a new Resource Template with the following data:


URI Template - gallery HTTP Method - POST Handler Type - PL/SQL Block

2.

Manually define the following parameters:


Aliasing Slug X-APEX-STATUS-CODE X-APEX-FORWARD Source Header Header Header Access IN OUT OUT Type String Integer String

Name title status location

3-10 Oracle Application Express Listener Installation and Developer Guide

Example: Creating an Image Gallery

3.

Define the following PL/SQL block:


declare image_id integer; begin select scott.gallery_seq.nextval into image_id from dual; insert into scott.gallery values(image_id,:title,:contentType,:body); :status := 201; :location := 'gallery/' || image_id; end;

Note that the:

PL/SQL block assigns a unique id to the image (image_id) and inserts the image data, image title, and image content type into the scott.gallery table. Block returns a 201 status which indicates a new resource has been created. Block indicates the location of the created resource is of the form gallery/<imageid>.

4.

Once you create the Resource Template, save it, and proceed to the next step.

Create an Image Upload Form


To invoke the previously defined image upload handler, you need a HTML form that enables users to specify the image to upload. To create an upload form:
1.

Create a new Resource Template with the following data:


URI Template - upload HTTP Method - GET Handler Type - Media Resource

2.

Include the following SQL Query:


select 'text/html', '<html> <head> <title>Choose Image to Upload</title> </head> <body> <div> <h1>Choose Image to Upload</h1> <form action="gallery" enctype="multipart/form-data" method="post"> <label for="title">Title</label> <input type="text" id="title" name="title"><br/> <label for="file">File</label> <input type="file" id="file" name="file"><br/> <div class="buttons"> <button type="submit" class="button">Upload</button> <a href="gallery" class="button">Cancel</a> </div> </form> </div> </body>

RESTful APIs and Resource Templates 3-11

Example: Creating an Image Gallery

</html>' from dual

Note that:

This illustrates a simple way to generate static text resources using Oracle Application Express Listener. Notice that the first column in the query is mapped to the content type of the resource and the second column becomes the body of the resource. Oracle does not typically recommend this approach since the SQL literal strings cannot be very big and it involves a database round-trip for data that is not actually retrieved from the database. Instead, Oracle recommends having your Web application serve static resources directly.

This form contains two fields. The first indicates the image title and the second the image content

3.

When you have created the Resource Template, try it in your browser. Enter a URL with the format:
http://<host>:<port>/apex/upload

Try choosing an image, giving it a title, and uploading it. When you click the Upload button, the browser should result in a 404 Not Found error. Remember that the POST handler you configured tells the Web browser to redirect to a gallery/<imageid> URI which you have not yet defined. However the image data will be stored in the scott.gallery table.

Display the Image


To display the image:
1.

Create a new Resource Template with the following data:


URI Template - gallery/image/{imageid} HTTP Method - GET Handler Type - Media Resource

2.

Manually define the following parameters:


Aliasing Source URI Access IN Type Integer

Name imageid 3.

Include the following SQL Query:


select content_type, image from scott.gallery where image_id = :imageid

Note that this query retrieves the content type and image data for the specified image.

Display the Gallery


To display the gallery:
1.

Open the gallery Resource Template and add the following data for a GET resource handler:

3-12 Oracle Application Express Listener Installation and Developer Guide

Example: Creating an Image Gallery

HTTP Method Handler Type

GET Media Resource

This will enable you to display the data stored in the gallery.
2.

Include the following SQL Query:


select 'text/x-apex-html', xmlquery(' <html> <head> <link rel="alternate" type="application/json" href="gallery? alt=json"/> </head> <body> <h1>Image Gallery</h1> <div class="buttons"> <a href="upload" >Upload Image</a> </div> <div> <span itemscope="itemscope"><a itemprop="gallery" href="./gallery"/></span> <ol id="images"> { for $i in ora:view("scott","gallery")/ROW order by $i/IMAGE_ID descending return <li itemscope="itemscope"> <a href="./gallery/{$i/IMAGE_ID/text()}"> <img itemprop="image" src="./gallery/images/ {$i/IMAGE_ID/text()}"/> <div itemprop="title">{$i/TITLE/text()}</div> </a> </li> } </ol> </div> <br/> </body> </html> ' returning content) from dual

Note that the:

Media resource handler is used to define a HTML resource and the HTML is generated dynamically using the xmlquery() SQL function. Content type of the resource is specified as text/x-apex-html. This is an Oracle Application Express specific content type. When Oracle Application Express Listener encounters this content type it expects the content of the resource to be well formed XML. It then transforms this XML into HTML. Generated HTML includes a link to an alternate JSON representation of the gallery data:
<link rel="alternate" type="application/json" href="gallery?alt=json"/>

This representation is automatically generated by Oracle Application Express Listener using its capability to transform HTML marked up with Microdata into JSON.
RESTful APIs and Resource Templates 3-13

Example: Creating an Image Gallery

For each image in the gallery a <li> element is generated. The <li> element is marked up with Microdata to assist clients in extracting the gallery data from the HTML. Microdata is a feature of HTML5 enabling structured semantic data to be interwoven into HTML documents. This semantic data can be easily and reliably parsed by clients.
3.

When you have updated the Resource Template go ahead and try it. In your Web browser, enter a URL using the format:
http://<host>:<port>/<apex>/gallery

You should see the image you previously uploaded.

Improve the Appearance of the Gallery


Next, create some JavaScript and CSS resources to improve the appearance of the gallery. Topics: Create gallery.css

Create gallery.js

Create gallery.css
To create gallery.css:
1.

Create a new Resource Template with the following data:


URI Template - gallery.css HTTP Method - GET Handler Type - Media Resource

2.

Include the following SQL Query:


select 'text/css', ' html { font-size: 100%; } body { font-size: 1em; font-family: Arial, Helvetica, sans-serif; background : #e2e1e1; margin-left: 3em; margin-right: 3em;} h1, h2, h3, h4, label { text-shadow: 0px 1px 0px #e5e5ee;} h1 { text-align: center;} a img { border:none; } #images { margin: 1em auto; width: 100%; } #images li { display: inline; } #images a { background: #fff; display: inline; float: left; margin: 0 0 27px 30px; width: auto; padding: 10px 10px 15px; textalign: center; text-decoration: none; color: #333; font-size: 18px; -webkit-box-shadow: 0 3px 6px rgba(0,0,0,.25); -moz-boxshadow: 0 3px 6px rgba(0,0,0,.25); -webkit-transform: rotate(2deg); -webkit-transition: -webkit-transform .15s linear; -moztransform: rotate(-2deg); } #images img { display: block; width: 190px; margin-bottom: 12px; } #images li:nth-child(3n) a { -webkit-transform: none; position: relative; top: -5px; -moz-transform: none; } #images li:nth-child(3n) a { -webkit-transform: none; position: relative; top: -5px; -moz-transform: none; } #images li:nth-child(5n) a { -webkit-transform: rotate(5deg); position: relative; right: 5px; -moz-transform: rotate(5deg); }

3-14 Oracle Application Express Listener Installation and Developer Guide

Example: Creating an Image Gallery

#images li:nth-child(8n) a { position: relative; right: 5px; top: 8px; } #images li:nth-child(11n) a { position: relative; left: -5px; top: 3px; } #images li.messy a { margin-top: -375px; margin-left: 160px; -webkit-transform: rotate(-5deg); -moz-transform: rotate(-5deg); } #images li a:hover { -webkit-transform: scale(1.25); -moztransform: scale(1.25); -webkit-box-shadow: 0 3px 6px rgba(0,0,0,.5); -moz-box-shadow: 0 3px 6px rgba(0,0,0,.5); position: relative; z-index: 5; } .buttons { float: right; margin-top: 1em; margin-bottom: 1em; } label {font-weight: bold; text-align: right;float: left; width: 120px; margin-right: 0.625em; } label :after {content(":")} input, textarea { width: 250px; margin-bottom: 5px;textalign: left} textarea {height: 150px;} br { clear: left; } ' from dual

This style sheet transforms the numbered list of images into a series of thumbnails. It uses some modern CSS features such as transforms and shadows which will not work on older Web browsers.
3.

When you have created the Resource Template edit the gallery Resource Template and add the following in the <head> section:
<link rel="stylesheet" href="gallery.css" type="text/css"/>

4.

Save your changes and view the gallery again using a URL in the format:
http://<host>:<port>/apex/gallery

Create gallery.js
To create gallery.js:
1.

Create a new Resource Template with the following data:


URI Template - gallery.js HTTP Method - GET Handler Type - Media Resource

2.

Include the following SQL Query:


select 'application/javascript', ' $(function() { $(".buttons a").button(); $(".buttons button").button(); }); ' from dual

This script uses the JQuery UI framework to transform the Upload Image link to a clickable button.

About the RESTful API


The previous example created both a Web application and a RESTful API. This section explores the RESTful API.

RESTful APIs and Resource Templates 3-15

About Resource Template Security

The structured semantic data that clients need to interact with the API is encoded in the HTML as microdata. Clients have two choices for processing this microdata, they can either:

Parse it directly from the HTML (browser-based applications will be able to use the HTML5 Microdata JavaScript APIs) Process the alternate JSON representation that Oracle Application Express Listener generates automatically

The alternate representation is identified by the <link> element in the <head> section of the gallery resource. The link element has a rel attribute with the value alternate and a type attribute of application/json. Consider the following example:
{ "items": [ { "properties": { "gallery": ["http://localhost:8080/apex/gallery"] } }, { "properties": { "image": ["http://localhost:8080/apex/gallery/images/13"], "title": ["Cherries"] } }, ... { "properties": { "image": ["http://localhost:8080/apex/gallery/images/4"], "title": ["Bay"] } } ] }

To successfully navigate the API, clients need the following information:


The location of an image is indicated by the image property The title of an image is indicated by the title property New Images can be uploaded by posting data to the URI indicated by the gallery property.

Note that the client only knows about a single URI (gallery) and discovers all other URIs from this initial URI. It does not know anything about the structure of the URIs. It only knows the names of properties that identify certain link types. As the application evolves, the URIs are free to change and clients will not be affected.

About Resource Template Security


Oracle Application Express Listener supports two mechanisms for securing access to Resource Templates:

Oracle Single Sign On Integration (OSSO) External authentication using Apache JServ Protocol (AJP)

When you configure either of these two options, Oracle Application Express Listener can honor any Security Constraint values specified in the Resource Template. Note
3-16 Oracle Application Express Listener Installation and Developer Guide

About Resource Template Security

that the identity of the authenticated user is available to the Resource Template using the X-APEX-USER header that is passed with the request. Topics: Integration with Oracle Single Sign On

External Authentication Using Apache JServ Protocol Example: Protecting Gallery Uploads

Integration with Oracle Single Sign On


When you correctly configure a supported JEE application container (for example, WebLogic or OC4J) to integrate with Oracle Single Sign On (OSSO), Oracle Application Express Listener attempts to determine the authenticated user identity using the Proxy-Remote-User header that mod_osso provides to the JEE application container. In addition the Oracle Application Express Listener produces a dynamic authentication request which causes the client to be redirected to the single sign on page if the user credentials are missing. Since Oracle Application Express Listener is trusting a HTTP header (Proxy-Remote-User) to assert the user identity, you must configure Oracle Application Express Listener to only accept requests from the HTTP proxy where mod_osso is deployed. To accomplish this task, add the following line to the apex-config.xml configuration file:
<entry key="apex.security.trustedProxies">ossoproxy.example.com</entry>

In this example, osso-proxy.example.com is the hostname of the server that forwards requests to Oracle Application Express Listener.

External Authentication Using Apache JServ Protocol


When running Oracle Application Express Listener in embedded mode, you can configure it to listen using the Apache JServ Protocol (AJP) protocol instead of HTTP. The AJP protocol has the capability to propagate a user identity. For example, you can configure an Apache HTTPD instance to perform user authentication and to communicate with Oracle Application Express Listener using mod_jk. This means that Resource Templates can be protected with any of the many authentication solutions available to Apache HTTPD.

Example: Protecting Gallery Uploads


You can reconfigure the Gallery's Resource Templates to require users be authenticated before they can upload images to the gallery. This will protect both the upload Resource Template and the POST handler of the gallery Resource Template. Topics: Protect Upload Form

Protect Gallery POST Handler Test the Changes

Protect Upload Form


To protect the upload form:
1.

Edit the upload Resource Template.


RESTful APIs and Resource Templates 3-17

About Resource Template Security

2. 3.

Change the Security Constraint of the GET handler to Authenticated. Click Save.

Protect Gallery POST Handler


To protect the gallery POST handler:
1. 2. 3.

Edit the gallery Resource Template. Change the Security Constraint of the POST handler to Authenticated. Click Save.

Test the Changes


Tip: This section assumes you are running Oracle Application Express Listener on a JEE Application Container with OSSO configured.

To test the changes:


1.

In your Web browser go to:


http://<host>:<port>/apex/gallery link

2.

Click Upload Image. The Oracle Single Sign On page appears.

3.

Enter your credentials. The Upload page appears.

3-18 Oracle Application Express Listener Installation and Developer Guide

A
A

About the Configuration File

The section describes the Oracle Application Express Listener configuration file. Topics: About the Listener Configuration File

Understanding Configuration File Parameters About Configurable Parameters

About the Listener Configuration File


The Oracle Application Express Listener Administration creates and updates a configuration file, named apex-config.xml. This file is an XML file that conforms to the Java Properties policy. You can create or edit this file manually. Topics: Locating the Configuration File

Setting the Value of the config.dir Parameter

Locating the Configuration File


To determine the location of the apex-config.xml:
1.

Go to the web.xml file:


/<application server directory>/apex/WEB-INF/web.xml

2.

Locate the web.xml initialization parameter, config.dir. This parameter specifies the location of the configuration file.

How the Listener Searches for the Configuration File


The Oracle Application Express Listener searches for the apex-config.xml configuration file at the following locations and in the following sequence:
1. 2. 3. 4.

${config.dir}/<Mount-Point>/apex-config.xml (from web.xml, if specified) ${config.dir}/apex-config.xml (from web.xml, if specified) ${user.home}/<Mount-Point>/apex-config.xml. ${java.io.tmpdir}/<Mount-Point>/apex-config.xml (default for new installs)

About the Configuration File

A-1

Understanding Configuration File Parameters

5. 6.

$HOME/apex-config.xml ${java.io.tmpdir}/apex/apex-config.xml (default for new installs)

If no existing apex-config.xml is found in any of the above locations, then a new apex-config.xml is created and stored as follows:

If a config.dir value was specified in web.xml, then apex-config.xml is stored in $config.dir/<Mount-Point>. If the folder does not exist, then it is created. Otherwise, if a folder named ${user.home}/<Mount-Point> exists, then apex-config.xml is stored in there. Otherwise, apex-config.xml is created in the default location ${java.io.tmpdir}/<Mount-Point>/apex-config.xml

Where:

${config.dir} is the initialization parameter named config.dir in the Oracle Application Express Listener web.xml file. <Mount-Point> is the Context Path at which Oracle Application Express Listener is deployed on the application server. Note if the application is deployed in the default context path ('/'), then <Mount-Point> defaults to a value of apex. ${user.home} is the value of the Java System Property named user.home. ${java.io.tmpdir} is the value the Java System Property named: java.io.tmpdir.

Setting the Value of the config.dir Parameter


The config.dir parameter specifies the location of the web.xml configuration file. To specify the value of the config.dir parameter:
1. 2. 3. 4. 5. 6.

Unzip apex.war into a temporary folder. Edit the WEB-INF/web.xml file. Remove the comment markers (<!--, -->) around the <init-param> for config.dir. Edit the value of the <param-value> element to point to the location where you created apex-config.xml. Rezip the modified files into a new apex.war file. Deploy the modified apex.war file.

Note that some application servers unzip the apex.war file into a folder after deploying the application. In that case, navigate to the unpacked version of web.xml created by the application server and edit it directly. After editing the file, restart the application server.

Understanding Configuration File Parameters


Each entry in the apex-config.xml contains a key and a corresponding value. The following is an example of an XML file document containing the declaration, entry key and value format:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties>

A-2 Oracle Application Express Listener Installation and Developer Guide

About Configurable Parameters

<entry key="key.name">value</entry> <entry key="key.name">value</entry> . . . <entry key="key.name">value</entry> </properties> <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties> <comment> Created: Tue Apr 27 03:00:39 PDT 2010 Version: 0.10.111.13.51 </comment> <entry key="apex.db.username">APEX_PUBLIC_USER</entry> <entry key="apex.db.password">@05D783103A9583BF206ABCA52F7D2E850B</entry> <entry key="apex.db.connectionType">basic</entry> <entry key="apex.db.hostname">localhost</entry> <entry key="apex.db.port">1521</entry> <entry key="apex.db.sid">ora111</entry> <entry key="apex.db.servicename"></entry> <entry key="apex.db.tnsAliasName">MY_TNSALIAS</entry> <entry key="apex.db.tnsDirectory">C:\ORACLE\NETWORK\ADMIN</entry> <entry key="apex.db.customURL"> jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP) (HOST=myhost)(PORT=1521))(CONNECT_DATA=(SERVICE_ NAME=ora111.us.oracle.com)))</entry> <entry key="apex.jdbc.DriverType">thin</entry> <entry key="apex.jdbc.InitialLimit">3</entry> <entry key="apex.jdbc.MinLimit">1</entry> <entry key="apex.jdbc.MaxLimit">10</entry> <entry key="apex.jdbc.MaxStatementsLimit">10</entry> <entry key="apex.jdbc.InactivityTimeout">1800</entry> <entry key="apex.jdbc.AbandonedConnectionTimeout">900</entry> <entry key="apex.security.inclusionList">apex, p, v, f, wwv_*, apple, y*, c*</entry> <entry key="apex.security.exclusionList">customer_account,bank*, employe?</entry> <entry key="apex.security.disableDefaultExclusionList">false</entry> <entry key="apex.security.requestValidationFunction">CHECK_VALID_PROCEDURE</entry> <entry key="apex.security.maxEntries">2000</entry> <entry key="apex.cache.caching">true</entry> <entry key="apex.cache.procedureNameList">p,download_file</entry> <entry key="apex.cache.type">lru</entry> <entry key="apex.cache.maxEntries">500</entry> <entry key="apex.cache.expiration">7</entry> <entry key="apex.cache.duration">days</entry> <entry key="apex.cache.monitorInterval">60</entry> <entry key="apex.cache.directory">C:\data\cachefiles</entry> <entry key="apex.procedure.preProcess">SCOTT.PREPROC1, INITIALIZE, PKG1.PROC</entry> <entry key="apex.procedure.postProcess">SCHEMA1.SUBMIT.REQUEST,FINISHTASK</entry> <entry key="apex.misc.defaultPage">apex</entry> <entry key="apex.debug.debugger">false</entry> <entry key="apex.debug.printDebugToScreen">false</entry> <entry key="apex.error.keepErrorMessages">true</entry> <entry key="apex.error.maxEntries">50</entry> <entry key="apex.log.logging">true</entry> <entry key="apex.log.maxEntries">50</entry> </properties>

About Configurable Parameters


Table A1 lists editable parameters in the apex-config.xml configuration file.
About the Configuration File A-3

About Configurable Parameters

Table A1 Key apex.cache.caching

Oracle Application Express Listener Configuration File Parameters Type boolean Description Supported values:

Example true

true false (default)

For caching to be enabled, this must be set to true and the procedureNameList must have a procedure. apex.cache.directory apex.cache.duration string string The directory location for the cache files. Supported values:

C:\data\cachefiles days

days (default) minutes hours

Required for expire cache type. apex.cache.expiration numeric Required for expire cache type. Defaults to 7. apex.cache.maxEntries numeric Required for lru cache type. Defaults to 500. apex.cache.monitorInter numeric val Interval time is specified in minutes. If the cache type is expire, Oracle Application Express Listener will check the cache every NN minutes for files that have expired. For example, if the monitorInterval is 60, then it will check the cache every 60 minutes. Defaults to 60. apex.cache.procedureNam string eList Specify the procedure names to allow for caching of their files. Procedure names can contain the wildcard characters asterisk (*) or question mark (?). Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character. Each procedure name must be separated by a comma. apex.cache.type string Supported values:

500

60

p, download_file

iru

expire iru (default) basic

apex.db.connectionType

string

The type of connection. Supported values:


basic tns advanced

A-4 Oracle Application Express Listener Installation and Developer Guide

About Configurable Parameters

Table A1 (Cont.) Oracle Application Express Listener Configuration File Parameters Key apex.db.customURL Type string Description The JDBC URL connection to connect to the database. Example jdbc:oracle:thin:@(DESCR IPTION=(ADDRESS= (PROTOCOL=TCP) (HOST=myhost)(PORT=1521) ) (CONNECT_DATA=(SERVICE_ NAME=ora111.us.example.c om))) apex.db.hostname apex.db.password string string The host system for the Oracle database. The password of the specified database user. Include an exclamation at the beginning of the password so that it can be stored encrypted. The database listener port. The network service name of the database. The name of the database. The TNS alias name that matches the name in the tnsnames.ora file. The directory location of your tnsnames.ora file. The name of the database user for the connection. Indicate whether to display debugging messages on the application server console. Supported values:

myhostname !password4user

apex.db.port apex.db.servicename apex.db.sid apex.db.tnsAliasName apex.db.tnsDirectory apex.db.username apex.debug.debugger

numeric string string string string string boolean

1521 ora111.example.com ora111 MY_TNSALIAS C:\ORACLE\NETWORK\ADMIN APEX_PUBLIC_USER false

true false (default) false

apex.debug.printDebugTo boolean Screen

Indicate whether to display error messages on the browser. Supported values:


true false (default) true

apex.error.keepErrorMes boolean sages

Indicate whether to retain the error messages. Supported values:


true false (default) 50

apex.error.maxEntries

numeric

Specify the total number of error messages to retain. Defaults to 50.

About the Configuration File

A-5

About Configurable Parameters

Table A1 (Cont.) Oracle Application Express Listener Configuration File Parameters Key Type Description Example

apex.jdbc.AbandonedConn numeric ectionTimeout

900 Specify how long a borrowed (in use) connection can remain unused before it is considered as abandoned and reclaimed. The abandoned connection timeout is in seconds. Defaults to 900.

apex.jdbc.DriverType

string

The JDBC driver type. Supported values:


thin

thin oci8

apex.jdbc.InactivityTim numeric eout

Specify how long an available 1800 connection can remain idle before it is closed. The inactivity connection timeout is in seconds. Defaults to 1800.

apex.jdbc.InitialLimit

numeric

Specify the initial size for the number of connections that will be created. Defaults to 3

apex.jdbc.MaxLimit

numeric

Specify the maximum number of connections. Defaults to 10

10

apex.jdbc.MaxStatements numeric Limit

Specify the maximum number of statements to cache for each connection. Defaults to 10.

10

apex.jdbc.MinLimit

numeric

Specify the minimum number of connections. Defaults to 1.

apex.log.logging

boolean

Indicate whether to retain the log messages. Supported values:


true

true false (default) 50

apex.log.maxEntries

numeric

Specify the total number of log messages to retain. Defaults to 50.

apex.misc.defaultPage

string

The default page to display. The Oracle Application Express home page, apex, is commonly used. Specify the procedure name(s) to execute after executing the procedure specified on the URL. Multiple procedure names must be separated by commas.

apex

apex.procedure.postProc string ess

SCHEMA1.SUBMIT.REQUEST,F INISHTASK

A-6 Oracle Application Express Listener Installation and Developer Guide

About Configurable Parameters

Table A1 (Cont.) Oracle Application Express Listener Configuration File Parameters Key Type Description Specify the procedure name(s) to execute prior to executing the procedure specified on the URL. Multiple procedure names must be separated by commas. Supported values:

Example SCOTT.PREPROC1, INITIALIZE, PKG1.PROC

apex.procedure.preProce string ss

apex.security.disableDe boolean faultExclusionList

false

true false (default) customer_account,bank*, employe?

apex.security.exclusion string List

Specify a pattern for procedures, packages, or schema names which are forbidden to be directly executed from a browser. Procedure names can contain the wildcard characters asterisk (*) or question mark (?). Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character. Note: Separate multiple patterns using commas.

apex.security.inclusion string List

Specify a pattern for procedures, packages, or schema names which are allowed to be directly executed from a browser. Procedure names can contain the wildcard characters asterisk (*) or question mark (?). Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character. Note: Separate multiple patterns using commas.

apex, p, v, f, wwv_*, y*, c*

apex.security.maxEntrie numeric s apex.security.requestVa string lidationFunction

Specify the maximum cache size. Defaults to 2000. Specify a validation function to determine if the requested procedure in the URL should be allowed or disallowed for processing. The function should return true if the procedure is allowed; otherwise, return false.

2000

CHECK_VALID_PROCEDURE

About the Configuration File

A-7

About Configurable Parameters

A-8 Oracle Application Express Listener Installation and Developer Guide

B
B

Troubleshooting

This appendix contains information on troubleshooting. Topics: Oracle Application Express Images Not Displaying

Cannot Log In to Oracle Application Express Listener Administration

Oracle Application Express Images Not Displaying


If your login page is missing images or has images that only partially display (for example, links display instead of images), then Oracle Application Express images have not been copied to your application server. To correct this issue, you must copy Oracle Application Express images to your application server. To learn more see:

For Oracle WebLogic Server - See "Create Web Archive for Oracle Application Express Images" on page 1-5 and "Install the Deployment" on page 1-6. For Oracle GlassFish Server - See "Copy Oracle Application Express Images" on page 1-13. For Oracle Containers for J2EE (OC4J) - See "Copy Oracle Application Express Images" on page 1-17.

Issue 1: Oracle Application Express Images Copied But Still Not Displaying You have copied the Oracle Application Express images to your application server as described in "Installing Oracle Application Express Listener" on page 1-1. However, the images are still not displaying: Resolution: 1. Make sure the Oracle Application Express images that you copied to your application server are the same Oracle Application Express version that is installed in your database.
2.

If you upgraded Oracle Application Express, see "Upgrading Oracle Application Express Images" on page 1-23.

Issue 2: Images Copied Using a Different Web Applications Context Root You have copied Oracle Application Express images and used a different Web applications context root other than the default context root (for example, i). The images are not displaying.

Troubleshooting B-1

Oracle Application Express Images Not Displaying

Resolution: 1. Execute reset_image_prefix.sql utility located in Oracle Application Express to change the default image prefix path (for example, /i/ ) to your Web applications context root for the images. Execute this utility using SQL*Plus and connect as SYS. See Oracle Application Express Installation Guide. The default Web applications context root for the Oracle Application images is i. Oracle recommends to use the default context root, i, for the Oracle Application images unless your business practice requires to change it.
Note:

Example: If you copied Oracle Application Express images using a different context root name (for example, apeximages) instead of using the default context root name (for example, i), then you must specify the different context root in the prefix path (for example, /apeximages/). If the images are located in a folder (for example, myfolder) of a context root, then you must specify the context root and the folder in the prefix path, for example:
/apeximages/myfolder/

The prefix path is case-sensitive and must begin and end with a forward slash. Consider the following example:
SQL> @<apex directory>\utilities\reset_image_prefix.sql Enter the Application Express image prefix [/i/] /apeximages/myfolder/ . . . Image Prefix update complete

2.

Next, update the image prefix for each application in Oracle Application Express Application Builder. To update the image prefix for each application in Oracle Application Express, release 4.0:
a. b. c. d.

Log in to Oracle Application Express. On the Workspace home page, click the Application Builder icon. Select an application. Click the Edit Application Properties button to the right of the application name. The Edit Application page appears.

e.

Under Name, locate Image Prefix. By default, this attribute is defined as /i/. Change Image Prefix to the prefix that you specified in the reset_image_prefix.sql utility as described in the previous section. For example:
/apeximages/myfolder/

f.

Click Apply Changes.

To update the image prefix for each application in Oracle Application Express, release 3.0:

B-2 Oracle Application Express Listener Installation and Developer Guide

Cannot Log In to Oracle Application Express Listener Administration

a. b. c. d.

Log in to Oracle Application Express. On the Workspace home page, click the Application Builder icon. Select an application. Click Shared Components. The Shared Components page appears.

e.

Under Application, click Application Definition. The Edit Definition page appears.

f.

Scroll down to Image Prefix. By default, this attribute is defined as /i/. Change Image Prefix to the prefix that you specified in the reset_image_prefix.sql utility as described in the previous section. For example:
/apeximages/myfolder/

g.

Click Apply Changes.

Cannot Log In to Oracle Application Express Listener Administration


If you cannot log in to Oracle Application Express Listener, check if the user is assigned the role Admin or Manager and if the roles are setup properly on your application server. Note that roles, Admin and Manager, are case-sensitive. To learn more about users and roles see the following sections and review your application server documentation:

"Installing with Oracle WebLogic Server" on page 1-5 "Installing with Oracle GlassFish Server" on page 1-12 "Installing with Oracle Containers for J2EE (OC4J)" on page 1-17

Troubleshooting B-3

Cannot Log In to Oracle Application Express Listener Administration

B-4 Oracle Application Express Listener Installation and Developer Guide

Index
A
Apache JServ Protocol (AJP), 3-17 apex-config.xml, A-1 about configuration parameters, A-2 configurable parameters, A-3 locating, A-1 setting config.dir parameter, A-2 apex-config.xml parameters apex.cache.caching, A-4 apex.cache.directory, A-4 apex.cache.duration, A-4 apex.cache.expiration, A-4 apex.cache.maxEntries, A-4 apex.cache.monitorInterval, A-4 apex.cache.procedureNameList, A-4 apex.cache.type, A-4 apex.db.connectionType, A-4 apex.db.customURL, A-5 apex.db.hostname, A-5 apex.db.port, A-5 apex.db.servicename, A-5 apex.db.sid, A-5 apex.db.tnsAliasName, A-5 apex.db.tnsDirectory, A-5 apex.db.username, A-5 apex.debug.debugger, A-5 apex.debug.printDebugToScreen, A-5 apex.error.keepErrorMessages, A-5 apex.error.maxEntries, A-5 apex.jdbc.DriverType, A-6 apex.jdbc.InactivityTimeout, A-6 apex.jdbc.InitialLimit, A-6 apex.jdbc.MaxLimit, A-6 apex.jdbc.MaxStatementsLimit, A-6 apex.jdbc.MinLimit, A-6 apex.log.logging, A-6 apex.log.maxEntries, A-6 apex.misc.defaultPage, A-6 apex.procedure.postProcess, A-6 apex.procedure.preProcess, A-7 apex.security.disableDefaultExclusionList, A-7 apex.security.exclusionList, A-7 apex.security.inclusionList, A-7 apex.security.maxEntries, A-7 apex.security.requestValidationFunction, A-7 Application Express missing images, B-1 Application Express Listener about, 1-1 about RESTful APIs, 3-1 about upgrading, 1-20 accessing Listener Administration, 2-1 configuration file, A-1 configuration file, locating, A-1 configuring, 2-1 default Web page, 2-12 downloading, 1-2 error reporting, 2-12 installation overview, 1-2 logging, 2-12 redeploying Oracle Containers for J2EE (OC4J), 1-22 redeploying Oracle GlassFish Server, 1-22 redeploying Oracle WebLogic Server, 1-21 supported Java Enterprise Edition application servers, 1-1 system requirements, 1-2 viewing status information, 2-2 Application Express Listener Administration about, 2-2 accessing, 2-1 cannot log in, B-3 configuring miscellaneous, 2-12 configuring security, 2-5 creating Pre-Post processing procedures, 2-10 defining caching, 2-9 establishing a database connection, 2-2 viewing status, 2-11 Application Express Listener caching specifying procedure names to allow, 2-9 Application Express Listener post-processing about, 2-10 Application Express Listener pre-processing about, 2-10

D
database connection Advanced connection, 2-3 Basic connection, 2-3 establishing, 2-2

Index-1

JDBC settings, 2-4 TNS connection, 2-3 default Web page, 2-12

E
entity tag strategies to generate, 3-3 error reporting, 2-12

G
GlassFish Server See Oracle GlassFish Server, 1-24

I
installation overview, 1-2 installation options Oracle Containers for J2EE (OC4J), 1-17 Oracle GlassFish Server, 1-12 Oracle WebLogic Server, 1-5 standalone mode, 1-3

installing the deployment, 1-15 installing with, 1-12 launching Administration Console, 1-13 redeploying when upgrading, 1-22 Oracle Web Logic Server, 1-2 Oracle WebLogic Server accessing Application Express Listener Administration, 1-12 copying Application Express images directory, 1-23 creating roles, 1-10 creating users, 1-10 creating users and roles, 1-9 installing, 1-5 installing the deployment, 1-6 installing with, 1-5 redeploying when upgrading, 1-21

R
resource handler, 3-3 about parameters, 3-4 about security constraints, 3-5 about types, 3-5 acceptable media types, 3-5 Comma Separated Values type, 3-6 Media Resource type, 3-7 PL/SQL Block type, 3-8 Query type, 3-5 type strategies, 3-4 resource handler type, 3-5 Comma Separated Values, 3-6 Media Resource, 3-7 PL/SQL block, 3-8 Query, 3-5 Resource Template Administration accessing, 3-2 resource template security example, 3-17 integration with Oracle Single Sign On, 3-17 using Apache JServ Protocol (AJP), 3-17 resource templates, 3-1 about entity tags (ETag), 3-3 about resource handlers, 3-3 about security, 3-16 about Uniform Resource Identifier (URI), 3-2 adding other handlers, 3-3 adding other handles to a resource template, 3-3 creating, 3-2 resource handler parameters, 3-4 resource handler type strategies, 3-4 RESTful APIs, 3-1 about, 3-1 about resource templates, 3-1 example, 3-9

L
Listener security about security settings, 2-8 specifying allowed procedures, 2-5 specifying blocked procedures, 2-6 specifying database validation functions, understanding security processing, 2-8 logging, 2-12

2-7

O
Oracle Containers for J2EE (OC4J), 1-2 accessing Application Express Listener Administration, 1-20 copying Application Express images, 1-17 copying Application Express images directory, 1-24 creating roles, 1-18 creating users, 1-19 creating users and roles, 1-18 installing the deployment, 1-19 installing with, 1-17 redeploying when upgrading, 1-22 starting the Application Server Control Console, 1-18 starting the OC4J server, 1-18 Oracle GlassFish Server, 1-2 about roles, 1-14 accessing Application Express Listener Administration, 1-16 copying Application Express images, 1-13 copying Application Express images directory, 1-24 create users and roles, 1-13 creating users, 1-14

S
standalone mode about JServ Protocol (AJP) support, 1-5

Index-2

configuration options, 1-4 installing and running in, 1-3 stopping the server, 1-4

T
troubleshooting, B-1 Application Express missing images, B-1 cannot log in to Listener Administration, B-3

U
Uniform Resource Identifier (URI), 3-2 grammar, 3-2 upgrading Application Express about, 1-23 copying images directory with J2EE (OC4J), 1-24 copying images directory with Oracle GlassFish Server, 1-24 copying images directory with Oracle WebLogic Server, 1-23

Index-3

Index-4