2 Configuring Oracle REST Data Services (Advanced)

Oracle REST Data Services supports a number of different strategies for routing requests to the appropriate database. All of these strategies rely on examining the request URL and choosing the database based on some kind of match against the URL. It is useful to recap the pertinent portions of a request URL. Consider the following URL:

https://www.example.com/ords/sales/f?p=1:1

This URL consists of the following sections:

• Protocol: https

• Host Name: www.example.com

• Context Root: /ords

  The context root is the location at which Oracle REST Data Services is deployed on the application server.

• Request Path: /sales/f?p=1.1

  This is the portion of the request URL relative to the context root.

For different applications, it may be important to route requests based on certain prefixes in the request path or certain prefixes in the full request URL.

There are two steps to configuring multiple databases:

1. Configuring the database connection information

2. Configuring which requests are routed to which database

When you first configure Oracle REST Data Services, you configure a default database connection named: apex. You can create additional database connections using the setup command.

java -jar ords.war help setup

To create a database connection type the following:

java -jar ords.war setup --database <database name>

Where:

• <database name> is the name you want to give the database connection.

You are prompted to enter the information required to configure the database. After you have configured the additional databases, define the rules for how requests are routed to the appropriate database.

You create request routing rules using the map-url command.

java -jar ords.war help map-url

If you want to route requests based just on matching a prefix in the request path portion of the URL, use the map-url command as follows:

java -jar ords.war map-url --type base-path --workspace-id <workspace name> <path prefix> <database name>

Where:

• <workspace name> is the name of the Oracle Application Express workspace where RESTful services for this connection are defined. This may be omitted if RESTful Services are not being used.

• <path prefix> is the prefix that must occur at the start of the request path.

• <database name> is the name of the database connection configured in the previous step.

If you want to route requests based on a match of the request URL prefix, use the map-url command as follows:

java -jar ords.war map-url --type base-url --workspace-id <workspace name> <url prefix> <database name>

Where:

• <workspace name> is the name of the Oracle Application Express workspace where RESTful services for this connection are defined. This may be omitted if RESTful Services are not being used.

• <url prefix> is the prefix with which the request URL must start.

• <database name> is the name of the database connection.

Oracle Database 12c Release 1 (12.1) introduces the multitenant architecture. This database architecture has a multitenant container database (CDB) that includes a root container, CDB$ROOT, a seed database, PDB$SEED, and multiple pluggable databases (PDBs). A PDB appears to users and applications as if it were a non-CDB. Each PDB is equivalent to a separate database instance in Oracle Database Release 11g.

The root container, CDB$ROOT, holds common objects that are accessible to every PDB utilizing metadata links or object links. The seed database, PDB$SEED, is used when creating a new PDB to seed the new pluggable database. The key benefit of the Oracle Database 12c multitenant architecture is that the database resources, such as CPU and memory, can be shared across all of the PDBs. This architecture also enables many databases to be treated as one for tasks such as upgrades or patches, and backups.

You can install Oracle REST Data Services into one or more pluggable databases PDBs in a multitenant database or into the container database (CDB). The installation choices are as follows:

• If you want the same version of Oracle REST Data Services available in all the PDBs, then install it into the CDB. The rest of the instructions in this topic refer to installing into the CDB.

• If you want only some PDBs to be able to use Oracle REST Data Services, or if you want different PDBs to use different versions of Oracle REST Data Services, then install into the desired PDBs. (Use the same procedure as for a non-CDB.)

When Oracle REST Data Services is installed into a CDB, it is installed in the root container, the seed container, and any existing PDBs. The root container (CDB$ROOT) includes the ORDS_METADATA schema to store the common database objects for Oracle REST Data Services packages, functions, procedures, and views. It also includes the Oracle REST Data Services public user (ORDS_PUBLIC_USER).

The seed container (PDB$SEED) includes the ORDS_METADATA schema and the Oracle REST Data Services public user. You can create a new PDB by copying PDB$SEED and creating metadata links back to the common database objects in the ORDS_METADATA schema within the CDB$ROOT. As a result, there are multiple copies of the Oracle REST Data Services tables and only single copies of the Oracle REST Data Services packages, functions, procedures, and views. Thus, each PDB has the ORDS_METADATA schema and its own copy of the Oracle REST Data Services tables, so that it can hold the metadata for the Oracle REST Data Services application within that PDB. Each PDB also has its own Oracle REST Data Services public user.

See also "Creating a PDB using the Seed" in Oracle Database Administrator's Guide.)

If you want to have all PDBs in a multitenant environment to use the same Oracle REST Data Services release and patch set, install into the CDB. (This option will not allow you to have different releases of Oracle REST Data Services in different PDBs.)

Before installing into the a CDB:

• Ensure that the PDBs are open (not mounted/closed) in read/write mode (except for PDB$SEED, which remains in read-only mode). See "Modifying the Open Mode of PDBs" in Oracle Database Administrator's Guide.

• Ensure that the default and temporary tablespaces to be used by the ORDS_METADATA schema and the ORDS_PUBLIC_USER user exist and that you know the tablespace names. The installation procedure creates those users, but it does not create the tablespaces.

  Note that ORDS_METADATA and ORDS_PUBLIC_USER are also installed in the seed container, and that the default and temporary tables will have to exist in PDB$SEED. If these tablespace do not already exist there, then you will have to create the tablespaces in PDB$SEED; see "Running Oracle-Supplied SQL Scripts in a CDB" in Oracle Database Administrator's Guide.

To install Oracle REST Data Services into a CDB, follow these steps.

1. Go to the folder into which you unzipped the Oracle REST Data Services installation kit.

2. Enter the following command:

   java -jar ords.war install advanced
   

   Note:

   To use the pluggable mapping feature, see Making All PDBs Addressable by Oracle REST Data Services (Pluggable Mapping).

3. When prompted, enter the database connection information for your CDB:

   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: (for example, cdb.example.com)
   

4. Verify the Oracle REST Data Services installation:

   Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:
   

   Accept or enter 1 (the default) to install Oracle REST Data Services into the CDB and all of its PDBs.

5. Enter and confirm the ORDS_PUBLIC_USER password:

   Enter the database password for ORDS_PUBLIC_USER:
   Confirm password:
   

6. When prompted, enter additional information as needed. (See Advanced Installation Using Command-Line Prompts.)

When you use a new release of Oracle REST Data Services, upgrading its schema in the CDB and its pluggable databases (PDBs) will occur automatically when you perform a simple or advanced installation.

For example:

java -jar ords.war

If Oracle REST Data Services is already installed or upgraded, a message displays the Oracle REST Data Services schema version, and you will not be prompted for information.

If an error occurred, view the log files.

Pluggable mapping refers to the ability to make all PDBs in a CDB addressable by Oracle REST Data Services. To use this feature, follow the instructions in this topic.

If the Oracle REST Data Services configuration file includes the db.serviceNameSuffix parameter, this indicates that the Oracle REST Data Services pool points to a CDB, and that the PDBs connected to that CDB should be made addressable by Oracle REST Data Services.

The value of the db.serviceNameSuffix parameter must match the value of the DB_DOMAIN database initialization parameter, and it must start with a period (.). To set the value of the db.serviceNameSuffix parameter:

1. In SQL*Plus, connect to the root as a user with SYSDBA privileges.

2. Check the value of the DB_DOMAIN database initialization parameter.

   SQL> show parameter DB_DOMAIN
   

3. Exit SQL*Plus.

   SQL> exit
   

4. If the DB_DOMAIN value was not empty, then on the command line enter the command to create the key and value for the db.serviceNameSuffix parameter and its DB_DOMAIN. This will be used to add this entry to the Oracle REST Data Services configuration file.

   echo db.serviceNameSuffix=.value-of-DB_DOMAIN > snsuffix.properties
   

   For example, if DB_DOMAIN is set to example.com, enter the following:

   echo db.serviceNameSuffix=.example.com > snsuffix.properties
   

5. If the db.serviceNameSuffix parameter value is not defined, enter a command in the following format to add an entry to the configuration file:

   java -jar ords.war set-properties --conf pool-name snsuffix.properties
   

   Where pool-name is one of the following:

   • poolName for a PL/SQL Gateway configuration

   • poolName_pu for an Oracle REST Data Services RESTful Services configuration

   • poolName_rt for an Application Express RESTful Services configuration

   Example 1: You want to make PDBs in a CDB addressable globally. Specify defaults by entering the following command:

   java -jar ords.war set-properties --conf defaults snsuffix.properties
   

   Note:

   The approach shown in Example 1 (setting the property for all pools through the defaults.xml file) is best for most use cases.

   Example 2: You want to make PDBs in a CDB addressable for your PL/SQL Gateway, and your pool name is apex. Enter the following command:

   java -jar ords.war set-properties --conf apex snsuffix.properties
   

   For example, if the database pointed to by apex has a DB_DOMAIN value of example.com and contains the two PDBs pdb1.example.com and pdb2.example.com, the first PDB will be mapped to URLs whose path starts with /ords/pdb1/, and the second PDB will be mapped to URLs whose path starts with /ords/pdb2/.

   Example 3: You want to make PDBs in a CDB addressable for your Oracle REST Data Services RESTful Services, and your pool name is apex_pu. Enter the following command:

   java -jar ords.war set-properties --conf apex_pu snsuffix.properties
   

   Example 4: You want to make PDBs in a CDB addressable for your Application Express RESTful Services and your pool name is apex_rt. Enter the following command:

   java -jar ords.war set-properties --conf apex_rt snsuffix.properties
   

To uninstall Oracle REST Data Services from a CDB, use the uninstall command.

For example:

java -jar ords.war uninstall

Oracle REST Data Services will be removed from the CDB and its pluggable databases (PDBs).