Skip Headers
Oracle® REST Data Services Installation and Configuration Guide
Release 2.0

E25066-11
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

1 Installing Oracle REST Data Services

This section describes how to install and deploy Oracle REST Data Services. (REST stands for Representational State Transfer.)

Name Change:

Oracle REST Data Services was called Oracle Application Express Listener before Release 2.0.6.

Topics:

1.1 About Oracle REST Data Services

Oracle REST Data Services is a Java EE-based alternative for Oracle HTTP Server and mod_plsql. The Java EE implementation offers increased functionality including a command line based configuration, enhanced security, file caching, and RESTful web services. Oracle REST Data Services also provides increased flexibility by supporting deployments using Oracle WebLogic Server, GlassFish Server, Apache Tomcat, and a standalone mode.

The Oracle Application Express architecture requires some form of web server to proxy requests between a web browser and the Oracle Application Express engine. Oracle REST Data Services satisfies this need but its use goes beyond that of Oracle Application Express configurations. Oracle REST Data Services simplifies the deployment process because there is no Oracle home required, as connectivity is provided using an embedded JDBC driver.

1.2 Understanding the Installation Process

This section offers an overview of Oracle REST Data Services and provides information about supported Java Platform, Enterprise Edition (Java EE) application servers and system requirements.

Topics:

1.2.1 Supported Java EE Application Servers

Oracle REST Data Services supports the following Java EE application servers:

Application Server Supported Release
Oracle WebLogic Server 11g Release 1 (10.3.3) or later
GlassFish Server Release 3 or later
Apache Tomcat Release 6 or later

1.2.2 System Requirements

Oracle REST Data Services system requirements are as follows:

  • Oracle Database (Enterprise Edition, Standard Edition or Standard Edition One) release 10.2.0.3 or later, or Oracle Database 10g Release 2 Express Edition or later.

  • Oracle Application Express:

    • Oracle REST Data Services depends on Oracle Application Express for storing and creating RESTful Services.

    • If you want to use RESTful Services, then Oracle Application Express 4.2 or later is required.

    • Ensure that all steps of the Oracle Application Express installation process have been completed, including the step "Configure RESTful Services" in Oracle Application Express Installation Guide.

    • If you do not want to use RESTful Services, then the use of any Oracle Application Express version is supported.

  • Java 6 Update 20 JDK or later.

  • Java Servlet Specification 2.3 or later.

  • Web browser requirements:

    • Microsoft Internet Explorer 8.0 or later.

    • Mozilla Firefox 3.0 or later.

    • Google Chrome 2.0 or later.

1.2.3 About Installing Oracle REST Data Services

To install Oracle REST Data Services:

  1. Download and unzip Oracle REST Data Services. See Section 1.3, "Installing Oracle REST Data Services".

  2. Configure Oracle REST Data Services. See Section 1.4, "Configuring Oracle REST Data Services".

  3. Deploy Oracle REST Data Services. Deployment options include:

1.3 Installing Oracle REST Data Services

To install Oracle REST Data Services:

  1. Download the file ords.version.number.zip from the Oracle REST Data Services download page. See:

    http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html

    Note that the version.number in the file name reflects the current release number.

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

    • UNIX and Linux: unzip ords.version.number.zip

    • Windows: Double-click the file ords.version.number.zip in Windows Explorer

1.4 Configuring Oracle REST Data Services

Before you deploy Oracle REST Data Services, you must configure it using a command-line interface. This section describes the various ways you can configure Oracle REST Data Services.

Tip:

To quickly get started with Oracle REST Data Services execute the following command:
java -jar ords.war

You are prompted to enter some information, and it then starts in Standalone Mode.

Topics:

1.4.1 About Using the Command-Line Interface

Oracle REST Data Services provides several command line commands. For example, you can configure the location where Oracle REST Data Services stores configuration files, configure the database Oracle REST Data Services uses, and start Oracle REST Data Services in standalone mode.

To display a full list of available commands, execute the following command:

java –jar ords.war help

A list of the available commands is displayed. To see instructions on how to use each of these commands, enter help followed by the command name, for example:

java -jar ords.war help configdir

1.4.2 About the Database Users Used by Oracle REST Data Services

Oracle REST Data Services uses the following database users:

User Name Required Description
APEX_PUBLIC_USER Yes If you use Oracle REST Data Services with Oracle Application Express, this is the database user used when invoking PL/SQL Gateway operations, for example, all Oracle Application Express operations.

For information on unlocking the APEX_PUBLIC_USER, see "Configure APEX_PUBLIC_USER Account" in Oracle Application Express Installation Guide.

APEX_REST_PUBLIC_USER Only if using RESTful Services The database user used when invoking RESTful services
APEX_LISTENER Only if using RESTful Services The database user used to query RESTful Services definitions stored in Oracle Application Express

Each of these database users is created during the Oracle Application Express installation process.

1.4.3 Downloading and Configuring Oracle REST Data Services

Note:

You must complete the configuration steps in this section before deploying to an application server.

To configure Oracle REST Data Services:

  1. Download and unzip Oracle REST Data Services. See Section 1.3, "Installing Oracle REST Data Services".

  2. Change your active directory to the directory where you unzipped Oracle REST Data Services.

  3. Execute the following command:

    java -jar ords.war
    
  4. When prompted, enter the information required to complete the configuration process. Each prompt may have a default response enclosed in brackets []. To choose the default response, press Enter without entering anything.

    You are prompted to enter the following data:

    • Location to store configuration data - Enter the location where you want to store Oracle REST Data Services configuration data. There is no default value.

    • Name of the database server - Enter the name of the database server. The default value is localhost.

    • Database listener port - Enter the port number that database is listening on. The default value is 1521.

    • Database service name or database SID - Options include:

      • Database service name - Enter 1 to specify the database service name (the default value).

      • Database SID - Enter 2 to specify the database SID.

    • Database user name - Enter the database user name to use for all PL/SQL Gateway operations. The default value is APEX_PUBLIC_USER.

    • Database user password - Enter the database password for the user specified in the previous step. There is no default value.

    • Passwords for RESTful Services Database Accounts - Options include:

      • Choose passwords - Enter 1 to specify passwords for APEX_LISTENER and APEX_REST_PUBLIC_USER accounts (the default value).

      • Re-use APEX_PUBLIC_USER password - Enter 2 to use the same password for APEX_LISTENER and APEX_REST_PUBLIC_USER as used for APEX_PUBLIC_USER.

      • Skip passwords - Enter 3 to skip configuring RESTful Services. Note that entering 3 disables RESTful Services.

1.4.4 Using SQL Developer Oracle REST Data Services Administration (Optional)

This section describes how to use Oracle SQL Developer to administer Oracle REST Data Services.

See Also:

"Oracle REST Data Services Administration" in Oracle SQL Developer User's Guide

Topics:

1.4.4.1 About SQL Developer Oracle REST Data Services Administration

Oracle SQL Developer (release 3.2 and later) enables you to administer Oracle REST Data Services using a graphical user interface. Using SQL Developer for Oracle REST Data Services administration is optional.

Using this graphical user interface, you can update the database connections, JDBC settings, URL mappings, RESTful connections, security (allowed procedures, blocked procedures, validation function and virus scanning), Caching, Pre/Post Processing Procedures, Environment, and Excel Settings. Oracle SQL Developer also provides statistical reporting, error reporting, and logging.

See Also:

"Oracle REST Data Services Administration" in Oracle SQL Developer User's Guide

1.4.4.2 Configuring an Administrator User

If you want to be able to administer Oracle REST Data Services using SQL Developer, then you must configure an administrator user as follows:

  • Execute the following command:

    java -jar ords.war user adminlistener "Listener Administrator"
    
  • Enter a password for the adminlistener user.

  • Confirm the password for the adminlistener user.

  • If you are using Oracle REST Data Services without HTTPS, follow the steps in Section 1.4.5, "Using OAuth2 in Non HTTPS Environments".

When using SQL Developer to retrieve and/or upload an Oracle REST Data Services configuration, when prompted, enter the credentials provided in the preceding list.

1.4.5 Using OAuth2 in Non HTTPS Environments

RESTful Services can be protected with the OAuth2 protocol to control access to nonpublic data. To prevent data snooping, OAuth2 requires all requests involved in the OAuth2 authentication process to be transported using HTTPS. The default behavior of Oracle REST Data Services is to verify that all OAuth2 related requests have been received using HTTPS. It will refuse to service any such requests received over HTTP, returning an HTTP status code of 403 Forbidden.

This default behavior can be disabled in environments where HTTPS is not available as follows:

  1. Locate the folder where the Oracle REST Data Services configuration is stored.

  2. Edit the file named defaults.xml.

  3. Add the following setting to the end of this file just before the </properties> tag.

    <entry key="security.verifySSL">false</entry>
    
  4. Save the file.

  5. Restart Oracle REST Data Services if it is running.

Note that it is only appropriate to use this setting in development or test environments. It is never appropriate to use this setting in production environments because it will result in user credentials being passed in clear text.

Note:

Oracle REST Data Services must be restarted after making configuration changes. See your application server documentation for information on how to restart applications.

1.5 Running in Standalone Mode

Although Oracle REST Data Services supports the Java EE application servers described in Section 1.2.1, "Supported Java EE Application Servers", you also have the option of running in standalone mode. This section describes how to run Oracle REST Data Services in standalone mode.

Standalone mode is suitable for development use only, and is not supported for use in production deployments. Use a supported Java EE application server for production deployments.

Topics:

1.5.1 Starting in Standalone Mode

To launch Oracle REST Data Services in standalone mode:

  1. To start Standalone mode, execute the following command:

    java –jar ords.war
    

    If you have not yet completed configuration, you are prompted to do so.

    Tip:

    To see help on standalone mode options, execute the following command:
    java -jar ords.war help standalone
    

    Note:

    Standalone mode does not support HTTPS, so the steps in Section 1.4.5, "Using OAuth2 in Non HTTPS Environments" must be followed if you want to use RESTful Services that require secure access (including the SQL Developer Administration View).
  2. When prompted, specify the location of the folder containing the Oracle Application Express static resources used by Oracle REST Data Services, or press Enter if you do not want to specify this location.

  3. When prompted, enter the value of the HTTP port you want the standalone Oracle REST Data Services to listen on. The default port is 8080.

    You are only prompted for these values the first time you launch standalone mode.

    Note:

    Ensure that no other servers are listening on the port you choose. The default port 8080 is commonly used by HTTP or application servers including the embedded PL/SQL gateway.

1.5.2 Stopping the Server in Standalone Mode

To stop the Oracle REST Data Services server in standalone mode, at a command prompt press Ctrl+C.

1.5.3 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 --ajp-port command line option with the standalone command to indicate the port to listen on (usually 8009). For example:

java -jar ords.war standalone --ajp-port 8009 --apex-images /usr/local/ords/images

Note:

Enabling AJP implicitly disables HTTP. It is not possible to listen for both protocols simultaneously.

1.6 Deploying to Oracle WebLogic Server

This section describes how to deploy Oracle REST Data Services on Oracle WebLogic Server. It 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:

1.6.1 About Oracle WebLogic Server

You can download Oracle WebLogic Server from Oracle Technology Network. See:

http://www.oracle.com/technetwork/middleware/weblogic/downloads/index.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.

1.6.2 Downloading and Unzipping Oracle REST Data Services

For information, see Section 1.3, "Installing Oracle REST Data Services".

1.6.3 Configuring Oracle REST Data Services

You must complete this step before deploying Oracle REST Data Services on WebLogic. For more information, see Section 1.4, "Configuring Oracle REST Data Services".

1.6.4 Configuring Oracle Application Express Images

Before you begin, you must create a web archive (WAR) file to reference the Oracle Application Express image files. Use the static command to create a web archive file named i.war:

java -jar ords.war static <apex directory>\images

Where:

  • <apex directory> is the directory location of Oracle Application Express.

This command runs the static command contained in the ords.war file. It packages the Application Express static images into an archive file named i.war.

The created images WAR does not contain the static resources; instead, it references the location where the static resources are stored. Therefore the static resources must be available at the specified path on the server where the WAR is deployed.

Tip:

Use java -jar ords.war help static to see the full range of options for the static command.

Use the i.war file to deploy to WebLogic in the following steps:

  1. Launching the Administration Server Console

  2. Installing the Oracle WebLogic Server Deployment

  3. Configuring WebLogic to Handle HTTP Basic Challenges Correctly

1.6.5 Launching the Administration Server Console

To launch the Administration Server console:

  1. Start an Administration Server.

  2. 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 port on which the Administration Server is listening for requests (port 7001 by default).

  3. Enter your WebLogic Administrator username and password.

  4. 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 does not appear.

1.6.6 Installing the Oracle WebLogic Server Deployment

Tip:

The Oracle REST Data Services files, ords.war and i.war, must be available before you start this task. See Section 1.3, "Installing Oracle REST Data Services" and Section 1.6.4, "Configuring Oracle Application Express Images"

To install the deployment:

  1. Go to the WebLogic Server Home Page. Below Domain Configuration, select Deployments.

    The Summary of Deployments is displayed.

  2. Click Install.

  3. Specify the location of the ords.war file and click Next.

    The ords.war file is located in the folder where you unzipped the Oracle REST Data Services ZIP file. See Section 1.3, "Installing Oracle REST Data Services".

    Tip:

    WebLogic Server determines the context root from the file name of a WAR archive. If you need to keep backward compatibility, so that URLs are of the form http://server/apex/... rather than http://server/ords/..., then you must rename ords.war to apex.war before the deployment.

    The Install Application assistant is displayed.

  4. Select Install this deployment as an application and click Next.

  5. 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 do not see this assistant page.
  6. In the Optional Settings, specify the following:

    1. Name - Enter:

      ords
      
    2. Security - Select the following:

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

    3. Source accessibility - Select:

      Use the defaults defined by the deployment's targets

  7. Click Next.

    A summary page is displayed.

  8. Under Additional configuration, select one of the following:

    • Yes, take me to the deployment's 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 to deploy the i.war file.

    In the optional settings, specify the following:

    1. Name - Enter:

      i
      
    2. Security - Select:

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

    3. Source Accessibility - Select:

      Use the defaults defined by the deployment's targets

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

1.6.7 Configuring WebLogic to Handle HTTP Basic Challenges Correctly

By default WebLogic attempts to intercept all HTTP Basic Authentication challenges. This default behavior needs to be disabled for Oracle REST Data Services to function correctly.

See your WebLogic documentation for the location of the WebLogic configuration file named: config.xml

Add the <enforce-valid-basic-auth-credentials> element to config.xml within the<security-configuration> element. The edited file should look like the following:

...
<enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>
</security-configuration>
...

Save the updated config.xml file, and restart WebLogic if it is running.

1.6.8 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.

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.

1.7 Deploying to GlassFish Server

This section describes how to deploy Oracle REST Data Services on GlassFish Server.

Topics:

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, users and roles, see your GlassFish Server documentation.

1.7.1 About GlassFish Server

You can install Oracle REST Data Services with GlassFish Server. GlassFish Server is available for download from the Oracle Technology Network. See:

http://www.oracle.com/us/products/middleware/application-server/oracle-glassfish-server/index.html

1.7.2 Downloading and Unzipping Oracle REST Data Services

For information, see Section 1.3, "Installing Oracle REST Data Services".

1.7.3 Configuring Oracle REST Data Services

You must complete this step before deploying Oracle REST Data Services on GlassFish. For more information, see Section 1.4, "Configuring Oracle REST Data Services".

1.7.4 Configuring Oracle Application Express Images

Before you begin, you must create a web archive (WAR) file to reference the Oracle Application Express image files. Use the static command to create a web archive file named i.war:

java -jar ords.war static <apex directory>\images

Where:

  • <apex directory> is the directory location of Oracle Application Express.

The created images WAR does not contain the static resources; instead, it references the location where the static resources are stored. Therefore the static resources must be available at the specified path on the server where the WAR is deployed.

Tip:

Use java -jar ords.war help static to see the full range of options for the static command.

Use the i.war file to deploy to GlassFish in the following steps:

  1. Launching the Administration Server Console

  2. Installing the GlassFish Server Deployment

1.7.5 Launching the Administration Server 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 are prompted to log in if you chose to require an administration password at the time GlassFish server was installed.

1.7.6 Installing the GlassFish Server Deployment

Tip:

The Oracle REST Data Services files, ords.war and i.war must be available before you start this task. See Section 1.3, "Installing Oracle REST Data Services" and Section 1.7.4, "Configuring Oracle Application Express Images".

To install the deployment:

  1. On the navigation tree, click the Application node.

    The Applications page is displayed.

  2. Click the Deploy button.

    The Deploy Applications or Modules page is displayed.

  3. Select Packaged File to be Uploaded to the Server and click Browse.

  4. Navigate to the location of the ords.war file, select the file, and click Open.

    The Deploy Applications or Modules page is displayed.

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

    1. Type: Web Application

    2. Context Root: ords

      Tip:

      The Context Root value defaults to ords. However you can change it to apex if you need to keep backward compatibility, so that URLs are of the form http://server/apex/... rather than http://server/ords/....
    3. Application Name: ords

    4. Status: Enabled

    5. Description: Oracle REST Data Services

    6. Accept all other default settings and click OK.

  6. Repeat the previous steps to deploy the i.war file. Clear the Context Root field so that the context root set in the sun-web.xml is used.

The Applications page is displayed. A check mark should appear in the Enabled field for ords

Tip:

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

1.8 Deploying to Apache Tomcat

This section describes how to deploy Oracle REST Data Services on Apache Tomcat.

Topics:

1.8.1 About Apache Tomcat

You can download Apache Tomcat from:

http://tomcat.apache.org/download-70.cgi

Tip:

This section assumes that you have completed the installation process and are familiar with Apache Tomcat. If you are unfamiliar with domains, servers, applications, security, users and roles, see your Apache Tomcat documentation.

1.8.2 Downloading and Unzipping Oracle REST Data Services

For information, see Section 1.3, "Installing Oracle REST Data Services".

1.8.3 Configuring Oracle REST Data Services

You must complete this step before deploying Oracle REST Data Services on Apache Tomcat. For more information, see Section 1.4, "Configuring Oracle REST Data Services".

1.8.4 Configuring Oracle Application Express Images

To configure Oracle Application Express Images on Apache Tomcat:

  • Copy the contents of the <apex directory>/images folder to <Tomcat directory>/webapps/i/.

    Where:

    • <apex directory> is the directory location of the Oracle Application Express distribution.

    • <Tomcat directory> is the folder where Apache Tomcat is installed.

1.8.5 Installing the Apache Tomcat Deployment

Tip:

The Oracle REST Data Services file ords.war must be available before you start this task. See Section 1.3, "Installing Oracle REST Data Services" and Section 1.8.4, "Configuring Oracle Application Express Images".

To install the Apache Tomcat deployment:

  1. Move the ords.war file into the webapps folder where Apache Tomcat is installed.

    Tip:

    Apache Tomcat determines the context root from the file name of a WAR archive. If you need to keep backward compatibility, so that URLs are of the form http://server/apex/... rather than http://server/ords/..., then you must rename ords.war to apex.war before moving it into to the webapps folder.
  2. Access Oracle REST Data Services typing the following URL in your web browser:

    http://<hostname>:<port>/ords
    

    Where:

    • <hostname> is the name of the server where Apache Tomcat is running.

    • <port> is the port number configured for Apache Tomcat application server.

1.9 Upgrading Oracle REST Data Services

In Oracle REST Data Services 2.0, the format of configuration files has changed and RESTful Services (also known as Resource Templates) are now stored in the Oracle Application Express schema.

If the configuration folder specified during Section 1.4, "Configuring Oracle REST Data Services" contains an existing Oracle REST Data Services 1.1 configuration, the configuration and any RESTful Services are migrated to 2.0 format.