1. Installation, Configuration, and Development Guide
  2. Introduction to Oracle REST Data Services

1 Introduction to Oracle REST Data Services

This chapter introduces Oracle REST Data Services and also describes how to install and deploy it. REST stands for Representational State Transfer.

Note:

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

Topics:

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

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:

Supported Java EE Application Servers

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

Application Server Supported Release

Oracle WebLogic Server

12c Release 2 (from version 12.2.1.3 and later) and 14c Release and later

Apache Tomcat

Release 8.5.x through Release 9.0.x

Supported Oracle Application Express (APEX) Versions

Oracle REST Data Services supports the currently supported versions of APEX.

See Also:

The Oracle Application Express (Formerly HTML DB) table in the ORACLE INFORMATION-DRIVEN SUPPORT document for supported versions of APEX.

System Requirements

Oracle REST Data Services system requirements are as follows:

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

  • Oracle Java 8 or later.

  • Web browser requirements:

    • Microsoft Internet Explorer 8.0 or later.

    • Mozilla Firefox 3.0 or later.

    • Google Chrome 2.0 or later.

Note:

Oracle Application Express is not a prerequisite for using Oracle REST Data Services.

If Oracle Application Express is installed and if RESTful services have been configured during the installation (see the step Configure RESTful Services in Oracle Application Express Installation Guide), then Oracle REST Data Services supports it, including executing the RESTful services defined in Oracle Application Express.

About Installing Oracle REST Data Services

To install Oracle REST Data Services:

  1. Download, install, and configure Oracle REST Data Services.

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

    • Standalone Mode.

    • Oracle WebLogic Server.

    • Apache Tomcat.

Related Topics

Configuring and Installing Oracle REST Data Services

Before you deploy Oracle REST Data Services, you must install and configure it using a command-line interface.

Topics:

See Also:

To use the Oracle REST API for JSON Data Persistence, you must also install the Oracle REST API. See "Oracle REST API Installation" in Oracle REST Data Services SODA for REST Developer's Guide.

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, go to the directory or folder containing the ords.war file and 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

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

Only if using Oracle REST Data Services with Oracle Application Express

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 defined in Application Express of version 5.0 or above.

The database user used when invoking Oracle Application Express RESTful Services if RESTful Services defined in Application Express workspaces are being accessed

APEX_LISTENER

Only if using RESTful Services defined in Application Express of version 5.0 or above.

The database user used to query RESTful Services definitions stored in Oracle Application Express if RESTful Services defined in Application Express workspaces are being accessed

ORDS_METADATA

Yes

Owner of the PL/SQL packages used for implementing many Oracle REST Data Services capabilities. ORDS_METADATA is where the metadata about Oracle REST Data Services-enabled schemas is stored.

It is not accessed directly by Oracle REST Data Services; the Oracle REST Data Services application never creates a connection to the ORDS_METADATA schema. The schema password is set to a random string, connect privilege is revoked, and the password is expired.

ORDS_PUBLIC_USER

Yes

User for invoking RESTful Services in the Oracle REST Data Services-enabled schemas.

The APEX_<xxx> users are created during the Oracle Application Express installation process.

Privileges Required for Oracle REST Data Services

As part of the Oracle REST Data Services installation, privileges are granted to several users and roles:

  • ORDS_RUNTIME_ROLE role
    • ORDS_RUNTIME_ROLE is granted EXECUTE on the following packages if these packages are not granted EXECUTE to PUBLIC:
      • SYS.DBMS_LOB
      • SYS.DBMS_SESSION
      • SYS.DBMS_UTILITY
      • SYS.WPIUTL
    • ORDS_RUNTIME_ROLE is granted the necessary ORDS_METADATA object privileges to determine the repository version and to access the connection pool configurations.
  • ORDS_PUBLIC_USER user
    • ORDS_PUBLIC_USER is granted connect to allow connection to the database.
    • ORDS_PUBLIC_USER is granted role, ORDS_RUNTIME_ROLE to allow the user to act as an ORDS runtime user
  • ORDS_ADMINISTRATOR_ROLE role
    • ORDS_ADMINISTRATOR_ROLE is granted EXECUTE on ORDS_METADATA.ORDS_ADMIN PL/SQL package.
  • PUBLIC
    • PUBLIC is granted EXECUTE on ORDS_METADATA.ORDS_REPVERSION view to allow the repository version to be queried by anyone.
    • PUBLIC is granted SELECT on many ORDS_METADATA views.
    • PUBLIC is granted EXECUTE on ORDS_METADATA PL/SQL packages that are available for developer users.
  • ORDS_METADATA schema
    • ORDS_METADATA schema is granted on the following packages if these packages are not granted EXECUTE on PUBLIC:
      • SYS.DBMS_ASSERT
      • SYS.DBMS_LOB
      • SYS.DBMS_OUTPUT
      • SYS.DBMS_SCHEDULER
      • SYS.DBMS_SESSION
      • SYS.DBMS_UTILITY
      • SYS.DEFAULT_JOB_CLASS
      • SYS.HTP
      • SYS.OWA
      • SYS.WPG_DOCLOAD
    • ORDS_METADATA is granted SELECT (11g) or READ (12c or later) on the following view if it is not granted SELECT or READ to PUBLIC:
      • SYS.SESSION_PRIVS
    • ORDS_METADATA schema is granted EXECUTE on the following packages:
      • SYS.DBMS_CRYPTO
      • SYS.DBMS_METADATA
    • ORDS_METADATA schema is granted SELECT (11g) or READ (12c or later) on the following views:
      • SYS.DBA_OBJECTS
      • SYS.DBA_ROLE_PRIVS
      • SYS.DBA_TAB_COLUMNS
    • ORDS_METADATA schema is granted SELECT including WITH GRANT OPTION on the following views:
      • SYS.USER_CONS_COLUMNS
      • SYS.USER_CONSTRAINTS
      • SYS.USER_OBJECTS
      • SYS.USER_PROCEDURES
      • SYS.USER_TAB_COLUMNS
      • SYS.USER_TABLES
      • SYS.USER_VIEWS
    • ORDS_METADATA schema is granted the following system privileges:
      • ALTER USER
      • CREATE ANY TRIGGER
      • CREATE JOB
      • CREATE PUBLIC SYNONYM
      • DROP PUBLIC SYNONYM
    • ORDS_METADATA schema is granted the necessary object privileges to migrate Application Express REST data to ORDS_METADATA tables.
    • ORDS_METADATA schema is granted ORDS_ADMINISTRATOR_ROLE, ORDS_RUNTIME_ROLE roles with administrator option.

  • PUBLIC is granted SELECT on many ORDS_METADATA tables and views.

  • PUBLIC is granted EXECUTE on PL/SQL packages that are available for users to invoke.

  • ORDS_METADATA is granted EXECUTE on the following packages if these packages are not granted EXECUTE to PUBLIC:

    • SYS.DBMS_ASSERT
    • SYS.DBMS_LOB
    • SYS.DBMS_OUTPUT
    • SYS.DBMS_SCHEDULER
    • SYS.DBMS_SESSION
    • SYS.DBMS_UTILITY
    • SYS.DEFAULT_JOB_CLASS
    • SYS.HTP
    • SYS.OWA
    • SYS.WPG_DOCLOAD

  • ORDS_METADATA is granted the necessary object privileges to migrate Application Express REST data to ORDS_METADATA tables.

Downloading, Configuring and Installing Oracle REST Data Services

The procedures in this topic apply to installing Oracle REST Data Services in a traditional (non-CDB) database.

Note:

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

To install and configure Oracle REST Data Services:

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

    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

  3. Choose one of the following installation options:

    • Advanced Installation Using Command-Line Prompts

    • Silent Installation Using a Parameter File

  4. You can reinstall or uninstall Oracle REST Data Services if required.

Related Topics

See Also:

Oracle REST Data Services Downloads

ORDS Installer Privileges Script

This section describes about the script file that provides privileges to the user to install, upgrade, validate and uninstall ORDS.

Note:

This script is used when you do not want to use SYS AS SYSDBA to install, upgrade, validate and uninstall ORDS for Oracle PDB or Oracle 11g.

Starting with ORDS 19.2 release, the Oracle REST Data Services installation archive file contains a script, ords_installer_privileges.sql which is located in the installer folder. The script provides the assigned database user the privileges to install, upgrade, validate and uninstall ORDS in Oracle Pluggable Database or Oracle 11g.

Perform the following steps:
  1. Using SQLcl or SQL*Plus, connect to Oracle PDB or 11g database with SYSDBA privileges.
  2. Execute the following script providing the database user:
    SQL> @/path/to/installer/ords_installer_privileges.sql exampleuser
SQL> exit

You must use the specified database user to install, upgrade, validate and uninstall ORDS.

Advanced Installation Using Command-Line Prompts

You can perform an advanced installation in which you are prompted for the necessary parameter values.

To perform an advanced installation, enter the following command:

java -jar ords.war install advanced

Note:

If you use a TNS connection to install ORDS, then you must specify the oracle.net.tns_admin system property on the command line that contains the folder with the tnsnames.ora file.

To perform installation using TNS connection, enter the following command:

java -Doracle.net.tns_admin=/path/to/tnsFolder -jar ords.war install advanced

Use the following on-line help command to check for additional options available for the install command: java –jar ords.war help install

During installation, Oracle REST Data Services checks if configuration files already exist in the specified configuration folder:

  • If configuration files do not exist in that folder, then they are created. For example: defaults.xml, apex_pu.xml files.

  • If configuration files from an earlier release exist in that folder, Oracle REST Data Services checks if <name>_pu.xml is present. If it is not present, then you are prompted to enter the password for the ORDS_PUBLIC_USER account. If the configuration files <name>_al.xml and <name>_rt.xml from Release 2.0.n exist, then they are preserved. (However, in Releases 2.0.n RESTful Services was optional, and therefore the files might not exist in the configuration folder.)

  • If multiple configuration files exist from a previous release (examples: apex.xml, apex_al.xml, apex_rt.xml, sales.xml, sales_al.xml, sales_rt.xml, …), and if <name>_pu.xml does not exist, then you are prompted to select the database configuration so that the Oracle REST Data Services schema can be created in that database.

The following shows an example for an advanced installation. In this example, if you accepted the default value as 1 for Enter 1 if you wish to start in standalone mode or 2 to exit [1], the remaining prompts are displayed; and if you will be using Oracle Application Express, then you must specify the APEX static resources location. 

d:\ords> java -jar ords.war install advanced

This Oracle REST Data Services instance has not yet been configured.
Please complete the following prompts

Enter the location to store configuration data: /path/to/config

Specify the database connection type to use.
Enter number for [1] Basic  [2] TNS  [3] Custom URL [1]:
Enter the name of the database server [localhost]:
Enter the database listen port [1521]:
Enter 1 to specify the database service name, or 2 to specify the database SID [1]:
Enter the database service name:orcl
Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:
Enter the database password for ORDS_PUBLIC_USER:
Confirm password:
Requires to login with administrator privileges to verify Oracle REST Data Services schema.

Enter the administrator username:EXAMPLEUSER
Enter the database password for EXAMPLEUSER:
Confirm password:
Connecting to database user: EXAMPLEUSER url: jdbc:oracle:thin:@//localhost:1521/orcl

Retrieving information.
Enter the default tablespace for ORDS_METADATA [SYSAUX]:
Enter the temporary tablespace for ORDS_METADATA [TEMP]:
Enter the default tablespace for ORDS_PUBLIC_USER [USERS]:
Enter the temporary tablespace for ORDS_PUBLIC_USER [TEMP]:
Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step.
If using Oracle Application Express or migrating from mod_plsql then you must enter 1 [1]:
Enter the PL/SQL Gateway database user name [APEX_PUBLIC_USER]:
Enter the database password for APEX_PUBLIC_USER:
Confirm password:
Enter 1 to specify passwords for Application Express RESTful Services database users (APEX_LISTENER, APEX_REST_PUBLIC_USER) or 2 to skip this step [1]:
Enter the database password for APEX_LISTENER:
Confirm password:
Enter the database password for APEX_REST_PUBLIC_USER:
Confirm password:
Enter a number to select a feature to enable: 
   [1] SQL Developer Web  (Enables all features)
   [2] REST Enabled SQL
   [3] Database API
   [4] REST Enabled SQL and Database API
   [5] None
Choose [1]:
Enter 1 if you wish to start in standalone mode or 2 to exit [1]:
Enter the APEX static resources location:/path/to/apex/images
Enter 1 if using HTTP or 2 if using HTTPS [1]:
Enter the HTTP port [8080]:   
OR
Enter 1 if using HTTP or 2 if using HTTPS [1]:2
Enter the HTTPS port [8443]:
Enter the SSL hostname:mysslhost    
Enter 1 to use the self-signed certificate or 2 if you will provide the SSL certificate [1]:
Descriptions for Advanced Installation Prompts

This section describes the options you can choose while performing advanced installation of Oracle REST Data Services schema.

Table 1-1 Advanced Installation Prompts for Installing and Configuring ORDS

Options Description 
This Oracle REST Data Services instance has not yet been configured.
Please complete the following prompts
Enter the location to store configuration data:/path/to/config

Specify the location for the ORDS configuration files. If the location does not exist, then it will be created.
Specify the database connection type to use. Enter number for [1] Basic [2] TNS [3] Custom URL [1]: Specify if you want a Basic connection, TNS connection or Custom URL connection
The following example is for a Basic Connection:
Enter the name of the database server [localhost]:

Specify the Oracle database hostname.
Enter the database listen port [1521]:

Specify the Oracle database port.

 
Enter 1 to specify the database service name, or 2 to specify the database SID [1]:
Enter the database service name:orcl

Specify the Oracle database service name, if you choose option 1. Otherwise, if you choose option 2 then, specify the Oracle database SID.
The following example is for a TNS Connection:
Enter the TNS Network Alias:orcl Specify the TNS network alias identifier.
The following example is for a Custom URL Connection:
Enter the Custom JDBC URL: jdbc:oracle:thin:@//localhost:1521/orcl Specify the custom url. 
Enter 1 if you want to verify/install Oracle REST Data Services schema 
or 2 to skip this step [1]:
Enter the database password for ORDS_PUBLIC_USER:
Confirm password:

Specify 1 to install the Oracle REST Data Services schema and create the Oracle REST Data Services proxy user, ORDS_PUBLIC_USER.

Specify the proxy user, ORDS_PUBLIC_USER and the corresponding password. 

Requires to login with administrator privileges to verify Oracle REST Data Services schema. 
Enter the administrator username:EXAMPLEUSER      
Enter the database password for EXAMPLEUSER:
Confirm password:

Specify the user with ORDS Installer privileges or the SYS AS SYSDBA account.

Specify the password of the user.

 
Enter the default tablespace for ORDS_METADATA [SYSAUX]:
Enter the temporary tablespace for ORDS_METADATA [TEMP]:

Specify the default tablespace and temporary tablespace for the Oracle REST Data Services schema, ORDS_METADATA. 

Enter the default tablespace for ORDS_PUBLIC_USER [USERS]:
Enter the temporary tablespace for ORDS_PUBLIC_USER [TEMP]

Specify the default tablespace and temporary tablespace for the Oracle REST Data Services proxy user, ORDS_PUBLIC_USER.

Table 1-2 Options for Configuring Application Express or Migrating from mod_plsql

Options Description 
Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step. If using Oracle 
Application Express or migrating from mod_plsql 
then you must enter 1 [1]:
Enter the PL/SQL Gateway database user name [APEX_PUBLIC_USER]:
Confirm password:
Enter the database password for APEX_PUBLIC_USER:

You can perform one of the following:

  • If you are using Oracle Application Express, then specify the PL/SQL gateway user as APEX_PUBLIC_USER and the corresponding database password.

  • If you are migrating from Oracle mod_plsql, then specify the PL/SQL gateway database username and database password.

  • If you are not using either Oracle Application Express or migrating from Oracle mod_plsql, then select 2 to skip this step.

 
Enter 1 to specify passwords for Application Express RESTful Services 
database user (APEX_LISTENER, APEX_REST_PUBLIC_USER) or 2 to skip this step [1]:
Enter the database password for APEX_LISTENER:
Confirm password:
Enter the database password for APEX_REST_PUBLIC_USER:
Confirm password:

If you have specified APEX_PUBLIC_USER for the PL/SQL Gateway user, then you have the option of using Application Express RESTful Services.

Specify 2 if you do not want to use Application Express RESTful Services and skip this step.

For Application Express 5.0 and above, option 1 is required. The database users are created using the script apex_rest_config.sql provided in the Application Express installation media.

Table 1-3 Enabling Features in ORDS

Options Description 
Enter a number to select a feature to enable:
   [1] SQL Developer Web  (Enables all features)
   [2] REST Enabled SQL
   [3] Database API
   [4] REST Enabled SQL and Database API
   [5] None
Choose [1]:

Specify 1 to enable all the features: SQL Developer Web, REST Enabled SQL and Database API. Specify 2 for REST Enabled SQL or 3 for Database API. Specify 4 to enable both REST Enabled SQL and Database API.

Refer to "Accessing SQL Developer Web", "REST Enabled SQL Service", and "Enabling ORDS Database API" documentation for more information.

Table 1-4 Options for Running in Standalone Mode

Options Description
Enter 1 if you wish to start in standalone mode or 2 to exit [1]:

Specify 1 to start in standalone mode using the Jetty web server that is bundled with ORDS.
Enter the APEX static resources location:/path/to/apex/images

Specify the location of the Application Express images. This prompt will appear if you have specified APEX_PUBLIC_USER for the PL/SQL Gateway user. 

Enter 1 if using HTTP or 2 if using HTTPS [1]:
Enter the HTTP port [8080]:
 Specify the HTTP port if you choose 1. 
OR
Enter 1 if using HTTP or 2 if using HTTPS [1]:2
Enter the HTTPS port [8443]:
Enter the SSL hostname:mysslhost
Enter 1 to use the self-signed certificate or 2 if you will provide the SSL certifi
cate [1]:

Specify the HTTPS port and the Secure Socket Layer (SSL) hostname if you choose 2.

You have the option of using the self-signed certificate which generates the self-signed certificate automatically.

 
OR
Enter 1 to use the self-signed certificate or 2 if you will provide the SSL certifi
cate [1]:2
Enter the path for the SSL Certificate:/path/to/sslcert
Enter the path for the SSL Certificates private
key:/path/to/sslcertprivatekey

Specify the path for the SSL certificate and the path for SSL certificate private key if you choose 2.
ORDS Parameter File

Oracle REST Data Services can be installed in either simple or silent mode without any user interaction.

You can perform either simple or silent installation for Oracle REST Data Services using the parameters specified in the params/ords_params.properties file under the location where you installed Oracle REST Data Services. This is the default Oracle REST Data Services parameter file. You can edit that file to change the default values to reflect your environment and preferences.

You can perform the installation for Oracle REST Data Services using the parameters specified in the params/ords_params.properties file under the location where you installed Oracle REST Data Services. This is the default Oracle REST Data Services parameter file. The Oracle REST Data Services parameter file consists of key or value pairs in the format key=value.

Alternatively, you have the option of specifying your own Oracle REST Data Services parameter file by including the --parameterFile option. If the --parameterFile option is not specified, the default Oracle REST Data Services parameter file is used.

Parameters Used in ORDS Parameter File
Parameters for Database Connection

This section lists the database connection parameters that must be specified in the properties file. You can specify a Basic, TNS or Custom URL connection.

Topics:

Parameters for Basic Connection

This section lists the parameters that must be specified in the properties file for basic database connection.

For basic connection, you must specify db.hostname and db.port database connection parameters. In addition, specify either db.servicename or db.sid parameters. If you are specifying a database connection to an Oracle 12.x PDB, then provide the db.servicename parameter.

Key Type Description Example
db.connectionType string Specifies the connection type. The value is basic. basic
db.hostname string Specifies the host system for the Oracle database. myhostname
db.port numeric Specifies the database listener port. 1521
db.servicename string Specifies the network service name of the database. orcl.example.com
db.sid string Specifies the name of the database. orcl
Parameters for TNS Connection

This section lists the parameters for TNS connection to install ORDS.

If you use a TNS connection to install ORDS, then you must specify the oracle.net.tns_admin system property on the command line that contains the folder of the tnsnames.ora file. The tnsnames.ora file must exist in that folder. For example: 

$ java -Doracle.net.tns_admin=/path/to/tnsFolder -jar ords.war install
    simple
Key Type Description Example
db.connectionType string Specifies the connection type. The value is tns. tns
db.tnsDirectory string Specifies the folder of where the tnsnames.ora file is located. /path/to/tnsfolder
db.tnsAliasName string Specifies the tns alias name that must exist in the tnsnames.ora file. orcl
Parameters for Custom URL Connection

This section lists the parameters for Custom URL connection to install ORDS.

Key Type Description Example
db.connectionType string Specifies the connection type. The value is customurl. customurl
db.customURL string Specifies the custom url. jdbc:oracle:thin:@//localhost:1521/orcl
Parameters for Installing Oracle REST Data Services

This section lists the parameters required for installing Oracle REST Data Services schema.

To install Oracle REST Data Services schema, following parameters must be specified:

  • Username and password of the user with ORDS Installer privileges or with SYS AS SYSDBA account.

  • ORDS_PUBLIC_USER password

  • Existing default and temporary tablespaces for the ORDS_METADATA schema and ORDS_PUBLIC_USER.

Note:

If all of the default and temporary tablespace parameters are omitted in the Oracle REST Data Services parameter file, then the Oracle database default and temporary tablespaces are used.

Table 1-5 Parameters for Installing Oracle REST Data Services

Key Type Description Example
rest.services.ords.add boolean

Specifies whether to install the Oracle REST Data Services schema. Set the value to true.

Supported values:

  • true

  • false (default)

 true
user.public.password string

Specifies the password for ORDS_PUBLIC_USER.

 password
schema.tablespace.default string

Specifies the ORDS_METADATA default tablespace. Specify an existing default tablespace.

 SYSAUX
schema.tablespace.temp string

Specifies the ORDS_METADATA temporary tablespace. Specify an existing temporary tablespace.

 TEMP
user.tablespace.default string

Specifies the ORDS_PUBLIC_USER default tablespace. Specify an existing default tablespace.

 SYSAUX
user.tablespace.temp string

Specifies the ORDS_PUBLIC_USER temporary tablespace. Specify an existing temporary tablespace.

 TEMP
bequeath.connect boolean

Specifies whether to connect as bequeath.

Supported values:

  • true

  • false (default)

 true
Parameters for Enabling SQL Developer Web

This section lists the parameters for enabling SQL Developer Web.

Table 1-6 Parameters for Enabling SQL Developer Web

Key Type Description Example
feature.sdw string
Specifies if SQL Developer Web is enabled.

Note:

For enabling SQL Developer Web, the value of restEnabledSql.active must also be true.
Default value is false. 		true
restEnabledSql.active string

Specifies if REST-Enabled SQL is enabled.

Default value is false. 		true
database.api.enabled string Specifies if the Database API is enabled. Default value is false. true
Parameters for Enabling REST-Enabled SQL

This section describes the parameter for enabling REST-Enabled SQL.

Table 1-7 Parameters for Enabling REST-Enabled SQL

Key Type Description Example
restEnabledSql.active string

Specifies if REST-Enabled SQL is enabled.

Default value is false. 		true
Parameters for Enabling Database API

This section describes the parameter for enabling Database API.

Table 1-8 Parameters for Enabling Database API

Key Type Description Example
database.api.enabled string

Specifies if Database API is enabled.

Default value is false. 		true
Parameters for Installing into the CDB

This section lists the parameters required for installing Oracle REST Data Services into the CDB and all of its PDBs.

Oracle database 12.x provides you the option of installing Oracle REST Data Services in the CDB and all of its PDBs.

Note:

Provide the CDB service name for db.servicename or sid for db.sid.

Table 1-9 Parameters for Installing into the CDB

Key Type Description Example
pdb.open.asneeded boolean
Specifies whether to open all PDBs in read write mode if their status is either closed or read only. If the value is set to true, then the following PDB parameters are ignored:

  • pdb.open.readwrite

  • pdb.skip.closed

  • pdb.skip.readonly

Supported values:

  • true

  • false (default)

 true
pdb.open.readwrite string

Specifies the list of PDB service names to open for read write mode if their status is read only.

 PDB1, PDB2, MYPDB
pdb.skip.closed boolean Specifies whether to skip PDBs that are closed.
Supported values:

  • true

  • false (default)

 true
pdb.skip.readonly boolean Specifies whether to skip PDBs with read only status.
Supported values:

  • true

  • false (default)

 true
pdb.exclude string

Specifies the list of PDB service names to exclude for install.

 PDB3, PDB4, PDB_X
Parameters for Configuring Application Express

This section lists the parameters for using Application Express.

Table 1-10 Parameters for Configuring Application Express

Key Type Description Example
plsql.gateway.add boolean

Specifies whether to configure Oracle REST Data Services for Application Express. Set this value to true.

Supported values:

  • true

  • false (default)

 true
db.username string

Specifies the PL/SQL gateway username. For Application Express, you must specify APEX_PUBLIC_USER.

 APEX_PUBLIC_USER
db.password string

Specifies the password for APEX_PUBLIC_USER. The password must match APEX_PUBLIC_USER database password.

 password
rest.services.apex.add boolean

Specifies whether to configure Oracle REST Data Services for Application Express RESTful Services.

Supported values:

  • true

  • false (default)

Set this value to true if you want to use APEX RESTful Services.

 true
user.apex.listener.password string

Specifies the password for APEX_LISTENER. If rest.services.apex.add is set to true, you must provide a password for APEX_LISTENER. The password must match APEX_LISTENER database password. Otherwise, if rest.services.apex.add is set to false, omit this parameter.

password
user.apex.restpublic.password string

Specifies the password for APEX_REST_PUBLIC_USER. If rest.services.apex.add is set to true, you must provide a password for APEX_REST_PUBLIC_USER. The password must match APEX_REST_PUBLIC_USER database password. Otherwise, if rest.services.apex.add is set to false, omit this parameter.

password
security.externalSessionTrustedOrigins String Comma separated list of origins that are trusted to make CORS requests for PL/SQL Gateway or APEX. http://example.com, https://example.com:8443

Example 1-1 Parameters to configure for Application Express and APEX RESTful Services and run in standalone mode

Following example shows parameters to install Oracle REST Data Services, configure for Application Express and APEX RESTful Services and run in standalone mode using http:

Note:

Passwords in the parameter file will be encrypted during installation. The encrypted passwords are stored in the parameter file. For example, user.public.password=@0585904F6C9B442532D5212962835D00C8. 

db.hostname=localhost
db.password=password
db.port=1521
db.servicename=orcl.example.com
db.username=APEX_PUBLIC_USER
plsql.gateway.add=true
rest.services.apex.add=true
rest.services.ords.add=true
schema.tablespace.default=SYSAUX
schema.tablespace.temp=TEMP
standalone.http.port=8080
standalone.mode=true
standalone.static.images=/path/to/images
standalone.use.https=false
user.apex.listener.password=password
user.apex.restpublic.password=password
user.public.password=password
user.tablespace.default=SYSAUX
user.tablespace.temp=TEMP

See Also:

Parameters for Running in Standalone Mode

This section lists parameters for running Oracle REST Data Services in standalone mode.

Table 1-11 Parameters for Installing Oracle REST Data Services in Standalone Mode

Key Type Description Example
standalone.mode boolean

Indicates whether to use the web application server (Jetty) that is included with Oracle REST Data Services.

Supported values:

  • true

  • false (default)

 true
standalone.http.port numeric

Specifies the HTTP listener port.

 8080
standalone.use.https boolean

Specifies whether to use https.

 true
standalone.https.port numeric

Specifies HTTPS listener port.

 8443
standalone.ssl.host string

Specifies the Secure Socket Layer (SSL) certificate hostname. You must specify this option if you are using https.

 mysecurehost
standalone.use.ssl.cert boolean

Specifies whether you will provide the SSL certificate. If this value is set to true, you must specify the standalone.ssl.cert.path and standalone.ssl.key.path.

true
standalone.ssl.cert.path string

Specifies the SSL certificate path. If you are providing the SSL certificate, you must specify the certificate location.

 /path/to/ssl/cert
standalone.ssl.key.path string

Specifies the SSL certificate key path. If you are providing the SSL certificate, you must specify the certificate key location.

 /path/to/ssl/key
standalone.static.images string

Specifies the location of Application Express images. If you are using Application Express, specify the location of Application Express images.

 /path/to/apex/images

Note:

On Microsoft Windows systems, if you specify an Application Express static images location for standalone.static.images, use the backslash character (/) before the colon, and use a forwardslash for the folder separator. For example, standalone.static.images=d\:/test/apex426/apex/images/

Example 1-2 Parameters to run in standalone mode using http

Following code snippet shows an example of the list of parameters to specify for installing Oracle REST Data Services and running in standalone mode using http:
db.hostname=localhost
db.port=1521
db.servicename=orcl.example.com
plsql.gateway.add=false
rest.services.apex.add=false
rest.services.ords.add=true
schema.tablespace.default=SYSAUX
schema.tablespace.temp=TEMP
standalone.http.port=8080
standalone.mode=true
standalone.use.https=false
user.public.password=password
user.tablespace.default=SYSAUX
user.tablespace.temp=TEMP

Example 1-3 Parameters to run in standalone mode using https and providing the ssl certificate paths

Following code snippet shows an example of the list of parameters to specify for installing and running Oracle REST Data Services in standalone mode using https and providing the ssl certificate paths:
db.hostname=localhost
db.port=1521
db.servicename=orcl.example.com
plsql.gateway.add=false
rest.services.apex.add=false
rest.services.ords.add=true
schema.tablespace.default=SYSAUX
schema.tablespace.temp=TEMP
standalone.https.port=8443
standalone.mode=true
standalone.ssl.cert.path=/path/to/ssl/cert
standalone.ssl.host=mysecurehost
standalone.ssl.key.path=/path/to/ssl/key
standalone.use.https=true
standalone.use.ssl.cert=true
user.public.password=password
user.tablespace.default=SYSAUX
user.tablespace.temp=TEMP
Miscellaneous Parameters

This section lists some miscellaneous parameters.

Table 1-12 Miscellaneous Parameters

Key Type Description Example
migrate.apex.rest boolean

Specifies whether to migrate APEX RESTful Services definitions to Oracle REST Data Services schema.

Supported values:

  • true

  • false (default)

 true
Simple Installation Using a Parameter File

Oracle REST Data Services can be installed in simple mode without any user interaction.

You can perform a simple installation of Oracle REST Data Services using an ORDS parameters file. A simple installation prompts you for the information if the required parameter does not exist in the ORDS parameter file.

Following is an example code snippet for installing Oracle REST Data Services in simple mode:
java -jar ords.war install simple
java -jar ords.war install --parameterFile /path/to/my_params.properties simple

java -jar ords.war install
java -jar ords.war install --parameterFile /path/to/my_params.properties

java -jar ords.war

Note:

Use the following on-line help command to check for additional options available for the install command: java –jar ords.war help install

Silent Installation Using a Parameter File

Oracle REST Data Services can be installed in silent mode without any user interaction.

You can perform a silent installation of Oracle REST Data Services using an ORDS parameters file. A silent installation must have the required parameters defined in the parameter file; otherwise, an error occurs.

Following is an example code snippet for installing Oracle REST Data Services in silent mode:

java -jar ords.war install --silent
java-jar ords.war install --silent --parameterFile /path/to/my_params.properties

Note:

Use the following on-line help command to check for additional options available for the install command: java –jar ords.war help install

Parameters Required for Silent Installation

This section describes the parameters required for installing Oracle REST Data Services in silent mode.

If you want to install Oracle REST Data Services in silent mode, then the required parameters must be defined in the ORDS parameter file.

Parameter Group Required Parameters Description
Database Connection Refer to "Parameters for Database Connection" section for the list of parameters. Specify Basic, TNS or Custom URL connection.
Installing ORDS rest.services.ords.add

Supported values:

  • true
  • false
 If rest.services.ords.add=true, then refer to "Parameters Used in ORDS Parameter File." section for additional parameters.
Configuring for Application Express or PL/SQL Gateway plsql.gateway.add

Supported values:

  • true
  • false
 If plsql.gateway.add=true, then refer to "Parameters for Configuring Application Express" section for additional required parameters.
Running in Standalone Mode standalone.mode

Supported values:

  • true
  • false
 If standalone.mode=true, then refer to "Parameters for Running Oracle REST Data Services in Standalone Mode" for additional required parameters.
Changing Default Configuration from the Command Line

This section describes how you can update the ORDS default configuration file.

The following set property command is used to update the ORDS default configuration file:

$ java -jar ords.war set-property <property key> <value>

ORDS must be restarted for the changes to take effect.

Example 1-4

Examples of Enabling a Feature.

The following example updates the properties in the existing defaults.xml file to enable SQL Developer Web. 

$ java -jar ords.war set-property feature.sdw true
$ java -jar ords.war set-property restEnabledSql.active true
$ java -jar ords.war set-property database.api.enabled true

Example 1-5

The following example updates the properties in the existing defaults.xml file to enable REST-Enable SQL.

$ java -jar ords.war set-property restEnabledSql.active true

Example 1-6

The following example updates the properties in the existing defaults.xml file to enable Database API.

$ java -jar ords.war set-property database.api.enabled true
Validating the Oracle REST Data Services Installation

If you want to check that the Oracle REST Data Services installation is valid, go to the directory or folder containing the ords.war file and enter the validate command in the following format: 

java -jar ords.war validate [--database <dbname>]

Note:

When you install Oracle REST Data Services, it attempts to find the Oracle Application Express (APEX) schema and creates a view. This view joins the relevant tables in the APEX schema to the tables in the Oracle REST Data Services schema. If you install Oracle REST Data Services before APEX, then Oracle REST Data Services cannot find the APEX schema and it creates a stub view in place of the missing APEX tables.

Oracle highly recommends that you install Oracle REST Data Services after APEX to ensure that the APEX objects, which Oracle REST Data Services needs to query, are present. If you install Oracle REST Data Services before APEX, then use the validate command to force Oracle REST Data Services to reconstruct the queries against the APEX schema.

If --database is specified, <dbname> is the pool name that is stored in the Oracle REST Data Services configuration files.

You are prompted for any necessary information that cannot be obtained from the configuration of pool name, such as host, port, SID or service name, and the name and password of the user with ORDS Installer privileges, or SYS AS SYSDBA user.

Note:

If the validate command is run against a CDB, then it will validate the CDB and all of its PDBs.

Note:

If you use a TNS connection to validate ORDS, then you must specify the oracle.net.tns_admin system property on the command line that contains the folder with tnsnames.ora file.

Example:

$ java -Doracle.net.tns_admin=/path/to/tnsFolder -jar ords.war validate

If You Want to Reinstall or Uninstall (Remove) Oracle REST Data Services

If you want to reinstall Oracle REST Data Services, you must first uninstall the existing Oracle REST Data Services; and before you uninstall, ensure that Oracle REST Data Services is stopped.

Uninstalling Oracle REST Data Services removes the ORDS_METADATA schema, the ORDS_PUBLIC_USER user, and Oracle REST Data Services-related database objects (including public synonyms) if they exist in the database. To uninstall (remove, or deinstall) Oracle REST Data Services, go to the directory or folder containing the ords.war file and enter the uninstall command as follows: 

java -jar ords.war uninstall

The uninstall command prompts you for some necessary information (host, port, SID or service name, username, password).

See Also:

To uninstall Oracle REST Data Services from a CDB, see Using the Multitenant Architecture with Oracle REST Data Services.

Note:

If you use a TNS connection to uninstall ORDS, then you must specify the oracle.net.tns_admin system property on the command line that contains the folder with tnsnames.ora file.

Example:

$ java -Doracle.net.tns_admin=/path/to/tnsFolder -jar ords.war uninstall

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:

About SQL Developer Oracle REST Data Services Administration

Oracle SQL Developer enables you to administer Oracle REST Data Services using a graphical user interface. To take full advantage of these administration capabilities, you must use SQL Developer Release 4.1 or later. 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

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 listed under the section,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.

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.

Running in Standalone Mode

Although Oracle REST Data Services supports the 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 and is supported in production deployments. Standalone mode, however, has minimal management capabilities when compared to most Java EE application servers and may not have adequate management capabilities for production use in some environments.

Note:

If you use a TNS connection to run ORDS in standalone mode, then you must specify the oracle.net.tns_admin system property on the command line that contains the folder with tnsnames.ora file.

Example: $ java -Doracle.net.tns_admin=/path/to/tnsFolder -jar ords.war standalone

Run the following help command to check the additional options available for the standalone command:

java -jar ords.war help standalone

Topics:

Related Topics

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 standalone

    If you have not yet completed the standalone 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:

    If you want to use RESTful services that require secure access, you should use HTTPS.

  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 select if you want Oracle REST Data Services to generate a self-signed certificate automatically or if you want to provide your own certificate. If you want to use your own certificate, provide the path for the Certificate and DER encoded related private key when prompted.

    If the private key has not already been converted to DER, see section, Converting a Private Key to DER (Linux and Unix) before you enter the values here.

    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; the default secure port 8443 is commonly used by HTTPS.

Related Topics

Converting a Private Key to DER (Linux and Unix)

Usually, you would have created a private key and a Certificate Signing Request before obtaining your signed certificate. The private key needs to be converted into DER in order for Oracle REST Data Services to read it properly.

For example, assume that the original private key was created using the OpenSSL tool with a command similar to either of the following:

openssl req -new -newkey rsa:2048 -nodes -keyout yourdomain.key -out yourdomain.csr

or

openssl genrsa -out private.em 2048

In this case, you must run a command similar to the following to convert it and remove the encryption: openssl pkcs8 -topk8 -inform PEM -outform DER -in yourdomain.key -out yourdomain.der -nocrypt 

openssl pkcs8 -topk8 -inform PEM -outform DER -in yourdomain.key -out yourdomain.der -nocrypt

After doing this, you can include the path to yourdomain.der when prompted by Oracle REST Data Services, or you can modify the following entries in conf/ords/standalone/standalone.properties: 

ssl.cert=<path to yourdomain.crt>
ssl.cert.key=<path to yourdomain.der>
ssl.host=yourdomain

Also, ensure that jetty.secure.port is set.

Stopping the Server in Standalone Mode

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

Configuring a Doc Root for Non-Application Express Static Resources

You can configure a doc root for standalone mode to deploy static resources that are outside the /i folder that is reserved for Application Express static resources.

To do so, specify the --doc-root parameter with the standalone mode command, as in the following example: 

java -jar ords.war standalone --doc-root /var/www/html

The preceding example makes any resource located within /var/www/html available under http://server:port/. For example, if the file /var/www/html/hello.txt exists, it will be accessible at http://server:port/hello.txt.

The value specified for --doc-root is stored in ${config.dir}/ords/standalone/standalone.properties in the standalone.doc.root property. If a custom doc root is not specified using --doc-root, then the default doc-root value of ${config.dir}/ords/standalone/doc_root is used. Any file placed within this folder will be available at the root context.

This approach has the following features and considerations:

  • HTML resources can be addressed without their file extension. For example, if a file named hello.html exists in the doc root, it can be accessed at the URI http://server:port/hello.

  • Attempts to address a HTML resource with its file extension are redirected to the location without an extension. For example, if the URI http://server:port/hello.html is accessed, then the client is redirected to http://server:port/hello.

    The usual practice is to serve HTML resources without their file extensions, so this feature facilitates that practice, while the redirect handles the case where the resource is addressed with its file extension.

  • Index pages for folders are supported. If a folder contains a file named index.html or index.htm, then that file is used as the index page for the folder. For example, if /var/www/html contains /abc/xyz/index.html, then accessing http://server:port/abc/xyz/ displays the contents of index.html.

  • Addressing a folder without a trailing slash causes a redirect to the URI with a trailing slash. For example, if a client accesses http://server:port/abc/xyz, then the server issues a redirect to http://server:port/abc/xyz/.

  • Resources are generated with weak etags based on the modification stamp of the file and with a Cache Control header that causes the resources to be cached for 1 hour.

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:

About Oracle WebLogic Server

You can download Oracle WebLogic Server from Oracle Technology Network.

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.

See Also:

weblogic_downloads

Downloading, Installing, and Configuring Oracle REST Data Services

You must complete this step before deploying Oracle REST Data Services on WebLogic.

Related Topics

Configuring Oracle Application Express Images

If you are using Oracle Application Express, you must create a web archive to reference the Oracle Application Express, image files. However, if you are not using Oracle Application Express, you may skip the rest of this section about 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

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.

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.

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.

    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.

Related Topics

Configuring WebLogic to Handle HTTP Basic Challenges Correctly

By default WebLogic Server attempts to intercept all HTTP Basic Authentication challenges. This default behavior needs to be disabled for Oracle REST Data Services to function correctly. This is achieved by updating the enforce-valid-basic-auth-credentials flag. The WebLogic Server Administration Console does not display the enforce-valid-basic-auth-credentials setting. You can use WebLogic Scripting Tool (WLST) commands to check, and edit the value in a running server. 

The following  WLST commands  display the domain settings:

connect('weblogic','weblogic','t3://localhost:7001')
cd('SecurityConfiguration')
cd('mydomain') 
ls()

If the domain settings displayed, contains the following entry:

-r--   EnforceValidBasicAuthCredentials             true

Then you must set this entry to false.

To set the entry to false, use the WLST commands as follows: 

connect('weblogic', 'weblogic', 't3://localhost:7001')
edit()
startEdit()
cd('SecurityConfiguration')
cd('mydomain')  
set('EnforceValidBasicAuthCredentials','false')
save()
activate()
disconnect()
exit()

Note:

WebLogic Server must be restarted for the new settings to take effect.
In the preceding example:

  • weblogic is the WebLogic user having administrative privileges

  • weblogic is the password

  • mydomain is the domain

  • The AdminServer is running on the localhost and on port 7001

Related Topics

Verifying the State and Health of ords and i

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

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

Deploying to Apache Tomcat

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

Topics:

About Apache Tomcat

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.

You can download Apache Tomcat from:

See Also:

apache_tomcat_80

Downloading, Installing, and Configuring Oracle REST Data Services

You must complete this step before deploying Oracle REST Data Services on Apache Tomcat.

Related Topics

Configuring Oracle Application Express Images

If you are using Oracle Application Express, you must create a web archive to reference the Oracle Application Express, image files. However, if you are not using Oracle Application Express, you may skip the rest of this section about 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.

Installing the Apache Tomcat Deployment

Tip:

The Oracle REST Data Services file ords.war must be available before you start this task.

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 Application Express by 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.

Related Topics

Monitoring ORDS

Standard Java runtime environment diagnostic and monitoring tools are used to gain an insight on the health of an ORDS instance running in Apache Tomcat, WebLogic Server, or a standalone mode. These tools track the memory and CPU usage, stuck threads, and other resources. ORDS provides additional insight through the ORDS instance API. The metrics available through the instance API makes it possible to check the status (valid or invalid) of the database pools and to gauge how the pools are being used. This helps in determining the actual load on the system and inform configuration changes in the future.

Topics:

Enabling the ORDS Instance API

This section explains how to enable the ORDS instance API.

To enable the ORDS instance API:
  1. Set the instance.api.enabled property to true.java -jar ords.war set-property instance.api.enabled true
  2. Restart ORDS.

Authorization for Using the ORDS Instance API

The System Administrator role is required to use the ORDS instance API. For production environments, it is recommended that a user with this role is configured through the mid-tier.

API Document

An OpenAPI description of the ORDS instance API services is available at http://<server>/ords/_/instance-api/stable/metadata-catalog/openapi.json.

Using the Instance API

The ORDS instance API service neither provides access to the database nor does it require the client to specify a database user for authentication. However, the ORDS instance returns information on the database pools. The instance API can be used as a basic health check service. To get a summary of the number of valid and invalid database pools, send a GET request to /ords/_/instance-api/stable/status.curl --user sysadmin:oracle http://<server>/ords/_/instance-api/stable/status. This service returns a count of valid and invalid pools. It also returns links to additional information with more details on the database pools cache.

ORDS can be deployed as a single instance or in a cluster. In a cluster, you must address each instance directly to get the specific information about that specific instance as the database pool statistics for one instance may differ from the other instance. However, if the load balancer routes to each instance in a round robin basis (as recommended), then every instance will have similar pool statistics.

Upgrading Oracle REST Data Services

If you want to upgrade to a new release of Oracle REST Data Services, you must do the following:

  1. Stop the Oracle REST Data Services instance.

    • If you are running Oracle REST Data Services on your application server (such as Oracle WebLogic Server, or Apache Tomcat), stop Oracle REST Data Services.

    • If you are running Oracle REST Data Services in standalone mode, refer to section, Stopping the Server in Standalone Mode.

  2. Go to the folder where you unzipped the new Oracle REST Data Services release distribution.

  3. Enter the following on the command line:

    java -jar ords.war install advanced

    or

    java -jar ords.war

  4. When prompted for the configuration folder, use the configuration folder where the Oracle REST Data Services configuration files are stored. (The configuration location will be stored in the ords.war file.)

    • If you specified an existing Oracle REST Data Services configuration folder that contains the configuration files, Oracle REST Data Services will attempt to connect to each database defined in the configuration folder and check the installed version.

    • If you specified an Oracle REST Data Services configuration folder that does not exist, you will be prompted for the database connection information, the ORDS_PUBLIC_USER credentials, and additional configuration information. Oracle REST Data Services will attempt to connect to this database and check the installed version.

When Oracle REST Data Services checks the installed version, it does the following, depending on whether an earlier 3.0.n version is already installed in the database.

  • If the installed version is an earlier 3.0.n version of Oracle REST Data Services, you are prompted for the username and password (user with ORDS Installer privileges or SYS AS SYSDBA) to enable Oracle REST Data Services to apply the in-place upgrade. The in-place upgrade will modify the existing installation to add the updated schema objects and packages. The existing metadata stored in the Oracle REST Data Services schema will remain intact.

  • If Oracle REST Data Services is not already installed in the database (or if you are upgrading from Release 2.0.n), you are prompted for the username and password (user with ORDS Installer privileges or SYS AS SYSDBA) to enable Oracle REST Data Services to perform the installation, and you will also be prompted for the default and temporary tablespaces for the ORDS_METADATA schema and ORDS_PUBLIC_USER.

When the upgrade or installation completes, you can re-deploy the ords.war file to your application server or start Oracle REST Data Services in standalone mode.

Related Topics

Using a Bequeath Connection to Install, Upgrade, Validate, or Uninstall Oracle REST Data Services

You can use the bequeath connection to install, upgrade, validate, or uninstall Oracle REST Data Services. The installer will not prompt you for the SYS username and password for the operation

In the parameter file, add the property: bequeath.connect=true

Using a bequeath connection for installing, validating, or uninstalling Oracle REST Data Services is supported on Linux and Windows systems for Oracle Database Release 12, but only on Linux systems for Oracle Database Release 11.

The command used must be run by an operating system user that is a member of the DBA group. Example of installing Oracle REST Data Services:

java -jar ords.war

Bequeath Connection Using Linux

On a Linux system, you must set the following environment variables to use the bequeath connection:

  • ORACLE_HOME

  • ORACLE_SID

  • LD_LIBRARY_PATH (to point to ORACLE_HOME/lib)

For Oracle Database Release 11 (but not for Release 12), you must specify the option -DuseOracleHome=true. Examples of installing Oracle REST Data Services on a Linux system:

  • For Oracle Database Release 11: java -DuseOracleHome=true -jar ords.war

  • For Oracle Database Release 12: java -jar ords.war

Authorizing Oracle REST Data Services to Access Oracle Data Guard Protected Users

To access the database schema objects that are protected by an Oracle Data Vault Realm, it is necessary to grant a proxy user authorization to the Oracle REST Data Services Public User.

The following example authorizes the Oracle REST Data Services Public User, ORDS_PUBLIC_USER to proxy the database HR user:
begin
  DBMS_MACADM.AUTHORIZE_PROXY_USER('ORDS_PUBLIC_USER','HR');
end;
/