About the Oracle REST Data Services Configuration Files

B About the Oracle REST Data Services Configuration Files

The section describes the Oracle REST Data Services configuration files.

Topics:

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.

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.

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.

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>

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>

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	This parameter is deprecated, instead use `owa.docTable` parameter.	`MYDOCTABLE`	Pool specific
`database.api.enabled`	string	Specifies whether the Database API is enabled. Supported values: true false (default)
`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.responseFormat`	string	Specifies how the HTTP error responses must be formatted. Supported values: `html` - Force all responses to be in HTML format `json` - Force all responses to be in JSON format `auto` - Automatically determines most appropriate format for the request (default).	`json`	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. Either `icap.port` or `icap.secure.port` are required to have a value.	`1344`	Global
`icap.secure.port`	numeric	Specifies the Internet Content Adaptation Protocol (ICAP) port to virus scan files. Either `icap.port` or `icap.secure.port` are required to have a value. If values for both `icap.port` and `icap.secure.port` are provided, then the value of `icap.port` is ignored.	`1344`	Global
`icap.server`	string	Specifies the Internet Content Adaptation Protocol (ICAP) server name or IP address 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 a timeout period on a statement. An abnormally long running query or script, executed by a request, may leave it in a hanging state unless a timeout is set on the statement. Setting a timeout on the statement ensures that all the queries automatically timeout if they are not completed within the specified time period. 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