B About the Oracle REST Data Services Configuration Files

The section describes the Oracle REST Data Services configuration files.

Topics:

B.1 Locating Configuration Files

Use the configdir command to display the current location of the configuration files:

java -jar ords.war configdir

If the configuration folder has not yet been configured, the message: The config.dir setting is not set, is displayed. If it has been configured, the current value of the setting is displayed.

B.2 Setting the Location of the Configuration Files

To change the location of the configuration folder use the configdir command:

java -jar ords.war configdir </path/to/config>

Where:

  • </path/to/config> is the location where the configuration files are stored.

B.3 Understanding the Configuration Folder Structure

The configuration folder has the following structure:

    ./
    |
    +-defaults.xml
    +-apex.properties*
    +-url-mapping.xml
    |
    +conf/
      |      
      +-apex.xml
      +-apex_al.xml
      +-apex_rt.xml
      +-apex_pu.xml
      |
      ...
      +-(db-name).xml
      +-(db-name)_al.xml
      +-(db-name)_rt.xml
      +-(db-name)_pu.xml

Global settings that apply to all database connections are stored in defaults.xml.

Settings specific to a particular database connection (for example, the default apex connection) are stored in conf/<db-name>.xml, where <db-name> is the name of the database connection.

If the database connection uses Oracle Application Express RESTful Services, the files with names including _al.xml, _rt.xml, and _pu.xml store the configuration for the APEX_LISTENER, APEX_REST_PUBLIC_USER, and ORDS_PUBLIC_USER database users, respectively.

If the database connection uses Oracle REST Data Services RESTful Services, the file <db-name>_pu.xml stores the configuration for the ORDS_PUBLIC_USER database user.

B.4 Understanding the Configuration File Format

Configuration files use the standard Java XML properties file format, where each configuration setting contains a key and a corresponding value. The following is an example of a defaults.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    
<entry key="db.connectionType">basic</entry>
<entry key="db.hostname">localhost</entry>
<entry key="db.port">1521</entry>
<entry key="db.sid">orcl</entry>
    
<entry key="jdbc.DriverType">thin</entry>
<entry key="jdbc.InitialLimit">3</entry>
<entry key="jdbc.MinLimit">1</entry>
<entry key="jdbc.MaxLimit">10</entry>
<entry key="jdbc.MaxStatementsLimit">10</entry>
<entry key="jdbc.InactivityTimeout">1800</entry>
<entry key="jdbc.statementTimeout">900</entry>
<entry key="jdbc.MaxConnectionReuseCount">1000</entry>
    
</properties>

B.4.1 Understanding the url-mapping.xml File Format

The url-mapping.xml file stores the rules that route requests to the appropriate database when more than one database is configured. The following is an example of a url-mapping.xml file:

<pool-config xmlns="http://xmlns.oracle.com/apex/pool-config">
 <pool name="sales_db"
   base-path="/sales"
   workspace-id="sales_rest"/>
</pool-config>

B.5 Understanding Configurable Parameters

Table B-1 lists editable parameters for the defaults.xml and (db-name).xml configuration files.

Note:

Oracle recommends users to use the Oracle REST Data Services command-line interface and Oracle SQL Developer Oracle REST Data Services Administration to edit the configuration files.

Table B-1 Oracle REST Data Services Configuration Files Parameters

Key Type Description Example Setting Type

apex.docTable

string

Name of the document table used by Application Express.

Defaults to FLOWS_FILES.WWV_FLOW_FILE_OBJECTS$.

Note: For APEX 4.x and above, this parameter is not used for APEX-only applications. However, if your application uses the Oracle Web Agent (OWA) package, and not APEX, then you can use this parameter.

MYDOCTABLE

 Pool specific

cache.caching

boolean

Supported values:

  • true

  • false (default)

For caching to be enabled, this must be set to true and the procedureNameList must have a procedure.

true

 Global

cache.directory

string

The directory location for the cache files.

C:\data\cachefiles

 Global

cache.duration

string

Supported values:

  • days (default)

  • minutes

  • hours

Required for expire cache type.

days

 Global

cache.expiration

numeric

Required for expire cache type.

Defaults to 7.

7

 Global

cache.maxEntries

numeric

Required for lru cache type.

Defaults to 500.

500

 Global

cache.monitorInterval

numeric

Interval time is specified in minutes.

If the cache type is expire, Oracle REST Data Services, checks the cache every NN minutes for files that have expired. For example, if the monitorInterval is 60, then it checks the cache every 60 minutes.

Defaults to 60.

60

 Global

cache.procedureNameList

string

Specifies the procedure names to allow for caching of their files.

Procedure names can contain the wildcard characters asterisk (*) or question mark (?). Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character.

Each procedure name must be separated by a comma.

p, download_file

 Global

cache.type

string

Supported values:

  • expire

  • lru (default)

lru

 Global

db.connectionType

string

The type of connection. Supported values:

  • basic

  • tns

  • customurl

basic

 Pool specific

db.customURL

string

The JDBC URL connection to connect to the database.

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP) (HOST=myhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ora111.example.com)))

 Pool specific

db.hostname

string

The host system for the Oracle database.

myhostname

 Pool specific

db.password

string

The password of the specified database user. Include an exclamation at the beginning of the password so that it can be stored encrypted.

!password4user

 Pool specific

db.port

numeric

The database listener port.

1521

 Pool specific

db.servicename

string

The network service name of the database.

ora111.example.com

 Pool specific

db.serviceNameSuffix

string

Indicates that the pool points to a CDB, and that the PDBs connected to that CDB should be made addressable by Oracle REST Data Services (see Making All PDBs Addressable by Oracle REST Data Services (Pluggable Mapping)).

apex_pu

 Pool specific

db.sid

string

The name of the database.

ora111

 Pool specific

db.tnsAliasName

string

The TNS alias name that matches the name in the tnsnames.ora file.

MY_TNSALIAS

 Pool specific

db.tnsDirectory

string

The directory location of your tnsnames.ora file.

C:\ORACLE\NETWORK\ADMIN

 Pool specific

db.username

string

The name of the database user for the connection.

APEX_PUBLIC_USER

 Pool specific

debug.debugger

boolean

Indicate whether to display debugging messages on the application server console.

Supported values:

  • true

  • false (default)

false

 Global

debug.printDebugToScreen

boolean

Indicate whether to display error messages on the browser.

Supported values:

  • true

  • false (default)

false

 Global

error.keepErrorMessages

boolean

Indicate whether to retain the error messages.

Supported values:

  • true

  • false (default)

true

 Global

error.maxEntries

numeric

Specifies the total number of error messages to retain.

Defaults to 50.

50

 Global

error.externalPath

string

Specifies the path to a folder that contains the custom error page.

/path/to/error/pages/folder/

 Global

icap.port

numeric

Specifies the Internet Content Adaptation Protocol (ICAP) Port to virus scan files.

The icap.port is required to have a value.

5555

 Global

icap.server

string

Specifies the Internet Content Adaptation Protocol (ICAP) Server name to virus scan files.

The icap.server is required to have a value.

servername

 Global

jdbc.DriverType

string

The JDBC driver type. Supported values:

  • thin

  • oci8

thin

 Pool specific

jdbc.InactivityTimeout

numeric

Specifies how long an available connection can remain idle before it is closed. The inactivity connection timeout is in seconds.

Defaults to 1800.

1800

 Pool specific

jdbc.InitialLimit

numeric

Specifies the initial size for the number of connections that will be created.

Defaults to 3. (The default is low, and should probably be set higher in most production environments.)

10

 Pool specific

jdbc.MaxConnectionReuseCount

numeric

Specifies the maximum number of times to reuse a connection before it is discarded and replaced with a new connection.

Defaults to 1000.

1000

 Pool specific

jdbc.MaxLimit

numeric

Specifies the maximum number of connections.

Defaults to 10. (Might be too low for some production environments.)

20

 Pool specific

misc.pagination.maxRows

numeric

Specifies the maximum number of rows that will be returned from a query when processing a RESTful service and that will be returned from a nested cursor in a result set. Affects all RESTful services generated through a SQL query, regardless of whether the resource is paginated.

Defaults to 500.

300

 Pool specific

jdbc.MaxStatementsLimit

numeric

Specifies the maximum number of statements to cache for each connection.

Defaults to 10.

10

 Pool specific

jdbc.MinLimit

numeric

Specifies the minimum number of connections.

Defaults to 1.

1

 Pool specific

jdbc.statementTimeout

numeric

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

Defaults to 900.

900

 Pool specific

log.logging

boolean

Indicate whether to retain the log messages.

Supported values:

  • true

  • false (default)

true

 Global

log.maxEntries

numeric

Specifies the total number of log messages to retain.

Defaults to 50.

50

 Global

log.procedure

boolean

Indicate whether procedures are to be logged.

Supported values:

  • true

  • false (default)

false

 Global

misc.defaultPage

string

The default page to display. The Oracle REST Data Services home page, apex, is commonly used.

apex

 Pool specific

procedure.postProcess

string

Specifies the procedure name(s) to execute after executing the procedure specified on the URL. Multiple procedure names must be separated by commas.

SCHEMA1.SUBMIT.REQUEST,FINISHTASK

 Pool specific

procedure.preProcess

string

Specifies the procedure name(s) to execute prior to executing the procedure specified on the URL. Multiple procedure names must be separated by commas.

SCOTT.PREPROC1, INITIALIZE, PKG1.PROC

 Pool specific

security.disableDefaultExclusionList

boolean

If this value is set to true, then the Oracle REST Data Services internal exclusion list is not enforced.

Note: The Oracle REST Data Services internal exclusion list blocks the users from accessing the following:
  • sys.*
  • dbms_*
  • utl_*
  • owa_*
  • owa.*
  • htp.*
  • htf.*
  • wpg_docload.*

Supported values:

  • true
  • false (default)

Oracle recommends that you do not set this value to true. That is, do not disable the default internal exclusion list. The only possible exception is temporarily disabling the internal exclusion list for debugging purposes.

false

 Global

security.exclusionList

string

Specifies a pattern for procedures, packages, or schema names which are forbidden to be directly executed from a browser.

Procedure names can contain the wildcard characters asterisk (*) or question mark (?). Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character.

Note: Separate multiple patterns using commas.

customer_account,bank*, employe?

 Global

security.inclusionList

string

Specifies a pattern for procedures, packages, or schema names which are allowed to be directly executed from a browser.

Procedure names can contain the wildcard characters asterisk (*) or question mark (?). Use an asterisk (*) to substitute zero or more characters and a question mark (?) to substitute for any one character.

Note: Separate multiple patterns using commas.

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

 Global

security.maxEntries

numeric

Specifies the maximum cache size.

Defaults to 2000.

2000

 Global

security.requestValidationFunction

string

Specifies a validation function to determine if the requested procedure in the URL should be allowed or disallowed for processing. The function should return true if the procedure is allowed; otherwise, return false.

CHECK_VALID_PROCEDURE

 Global

security.verifySSL

boolean

Indicate whether HTTPS is available in your environment.

Supported values:

  • true (default)

  • false

If you change the value to false, see Using OAuth2 in Non-HTTPS Environments.

true

 Global

soda.defaultLimit

string

When using the SODA REST API, specifies the default number of documents returned for a GET request on a collection when a limit is not specified in the URL. Must be a positive integer, or "unlimited" for no limit.

Defaults to 100.

75

 Pool specific

soda.maxLimit

string

When using the SODA REST API, specifies the maximum number of documents that will be returned for a GET request on a collection URL, regardless of any limit specified in the URL. Must be a positive integer, or "unlimited" for no limit.

Defaults to 1000.

700

 Pool specific

restEnabledSql.active

boolean
Indicate whether the REST-Enabled SQL service is active. Supported values:

  • true

  • false (default)

true

 Pool specific

See Also:

For more information, see Configuring and Installing Oracle REST Data Services and "Oracle REST Data Services Administration" in Oracle SQL Developer User's Guide.