Pre-General Availability: 2017-09-04

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.

Tip:

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

apex.docTable

string

Name of the document table used by Application Express.

Defaults to FLOWS_FILES.WWV_FLOW_FILE_OBJECTS$.

MYDOCTABLE

apex.excel2collection

boolean

Indicate whether to place your Excel files into an Oracle Application Express collection.

Supported values:

  • true

  • false (default)

If value is true, then either apex.excel2collection.onecollection or apex.excel2collection.useSheetName should be set to true.

false

apex.excel2collection.name

string

The name of the apex collection. The name is required if apex.excel2collection.onecollection is true.

mycollection

apex.excel2collection.onecollection

boolean

Indicate whether to put all Excel worksheets into a single collection.

Supported values:

  • true

  • false (default)

false

apex.excel2collection.useSheetName

boolean

Indicate whether to create a collection for each Excel worksheet, and uses each worksheet name for the corresponding collection name.

Supported values:

  • true

  • false (default)

false

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

cache.directory

string

The directory location for the cache files.

C:\data\cachefiles

cache.duration

string

Supported values:

  • days (default)

  • minutes

  • hours

Required for expire cache type.

days

cache.expiration

numeric

Required for expire cache type.

Defaults to 7.

7

cache.maxEntries

numeric

Required for lru cache type.

Defaults to 500.

500

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

cache.procedureNameList

string

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

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

Each procedure name must be separated by a comma.

p, download_file

cache.type

string

Supported values:

  • expire

  • lru (default)

lru

db.connectionType

string

The type of connection. Supported values:

  • basic

  • tns

  • customurl

basic

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)))

db.hostname

string

The host system for the Oracle database.

myhostname

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

db.port

numeric

The database listener port.

1521

db.servicename

string

The network service name of the database.

ora111.example.com

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

db.sid

string

The name of the database.

ora111

db.tnsAliasName

string

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

MY_TNSALIAS

db.tnsDirectory

string

The directory location of your tnsnames.ora file.

C:\ORACLE\NETWORK\ADMIN

db.username

string

The name of the database user for the connection.

APEX_PUBLIC_USER

debug.debugger

boolean

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

Supported values:

  • true

  • false (default)

false

debug.printDebugToScreen

boolean

Indicate whether to display error messages on the browser.

Supported values:

  • true

  • false (default)

false

error.keepErrorMessages

boolean

Indicate whether to retain the error messages.

Supported values:

  • true

  • false (default)

true

error.maxEntries

numeric

Specify the total number of error messages to retain.

Defaults to 50.

50

icap.port

numeric

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

The icap.port is required to have a value.

5555

icap.server

string

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

The icap.server is required to have a value.

servername

jdbc.DriverType

string

The JDBC driver type. Supported values:

  • thin

  • oci8

thin

jdbc.InactivityTimeout

numeric

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

Defaults to 1800.

1800

jdbc.InitialLimit

numeric

Specify 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

jdbc.MaxConnectionReuseCount

numeric

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

Defaults to 1000.

1000

jdbc.MaxLimit

numeric

Specify the maximum number of connections.

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

20

jdbc.maxRows

numeric

Specify 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

jdbc.MaxStatementsLimit

numeric

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

Defaults to 10.

10

jdbc.MinLimit

numeric

Specify the minimum number of connections.

Defaults to 1.

1

jdbc.statementTimeout

numeric

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

Defaults to 900.

900

log.logging

boolean

Indicate whether to retain the log messages.

Supported values:

  • true

  • false (default)

true

log.maxEntries

numeric

Specify the total number of log messages to retain.

Defaults to 50.

50

log.procedure

boolean

Indicate whether procedures are to be logged.

Supported values:

  • true

  • false (default)

false

misc.defaultPage

string

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

apex

procedure.postProcess

string

Specify 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

procedure.preProcess

string

Specify 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

security.disableDefaultExclusionList

boolean

Supported values:

  • true

  • false (default)

false

security.exclusionList

string

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

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

Note: Separate multiple patterns using commas.

customer_account,bank*, employe?

security.inclusionList

string

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

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

Note: Separate multiple patterns using commas.

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

security.maxEntries

numeric

Specify the maximum cache size.

Defaults to 2000.

2000

security.requestValidationFunction

string

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

CHECK_VALID_PROCEDURE

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

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

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

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.