C About the Oracle REST Data Services Configuration Files

The section describes the Oracle REST Data Services configuration files.

Topics:

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

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

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

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

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

C.5 Understanding Configurable Parameters

Table C-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 C-1 Oracle REST Data Services Configuration Files Parameters

Key Type Description Example Setting Type

apex.docTable

string

This parameter is deprecated, instead use owa.docTable 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

Specifies 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

Specifies the host system for the Oracle database.

myhostname

Pool specific

db.password

string

Specifies 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

Specifies the database listener port.

1521

Pool specific

db.servicename

string

Specifies the network service name of the database.

ora111.example.com

Pool specific

db.serviceNameSuffix

string

Specifies 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

Specifies the name of the database.

ora111

Pool specific

db.tnsAliasName

string

Specifies 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

Specifies the name of the database user for the connection.

APEX_PUBLIC_USER

Pool specific

debug.printDebugToScreen

boolean

Specifies whether to display error messages on the browser.

Supported values:

  • true

  • false (default)

false

Global

error.keepErrorMessages

boolean

Specifies 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

Specifies 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

jdbc.auth.enabled

boolean

Specifies if the PL/SQL Gateway calls can be authenticated using database users. If the value is true then this feature is enabled. If the value is false, then this feature is disabled. The default value is false. Oracle recommends not to use this feature. This feature used only to facilitate customers migrating from mod_plsql.

false

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

Specifies 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

Specifies whether procedures are to be logged.

Supported values:

  • true

  • false (default)

false

Global

misc.defaultPage

string

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

apex

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

300

Pool specific

owa.docTable

string

Specifies the name of the document table used by the file upload.

Defaults to FLOWS_FILES.WWV_FLOW_FILE_OBJECTS$ value.

Note:

For APEX 4.x and above this parameter should not be used.

MYDOCTABLE

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

procedure.rest.preHook

string

Specifies the function to be invoked prior to dispatching each Oracle REST Data Services based REST Service. The function can perform configuration of the database session, perform additional validation or authorization of the request. If the function returns true, then processing of the request continues. If the function returns false, then processing of the request is aborted and an HTTP 403 Forbidden status is returned.

MYAPP.VALIDATE_REST_CALL

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 number of cached procedure validations. Defaults to 2000. Set this value to 0 to force the validation procedure to be invoked on each request.

2000

Global

security.requestAuthenticationFunction

string

Specifies an authentication 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, it should return false. If it returns false, Oracle REST Data Services will return WWW-Authenticate in the response header.

owa_custom.authorize

Pool specific

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

Pool specific

security.verifySSL

boolean

Specifies 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

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