8i | 9i | 10g | 11g | 12c | 13c | 18c | 19c | 21c | 23c | Misc | PL/SQL | SQL | RAC | WebLogic | Linux

Home » Articles » Misc » Here

Oracle REST Data Services (ORDS) : Installation on Tomcat (ORDS Versions 3.0 to 21.4)

This methods works for ORDS versions 3.0 to 21.4. If you want to use version ORDS 22.1 onward, use the method described here.

Oracle REST Data Services (ORDS), formerly known as the APEX Listener, allows APEX applications to be deployed without the use of Oracle HTTP Server (OHS) and mod_plsql or the Embedded PL/SQL Gateway. ORDS version 3.0 onward also includes JSON API support to work in conjunction with the JSON support in the database. ORDS can be deployed on WebLogic, Tomcat or run in standalone mode. This article describes the installation of ORDS on Tomcat 8 and 9.

Related articles.

Assumptions

Multitenant : CDB or PDB Installation

When using the multitenant architecture there are several options for how to install ORDS.

For Lone-PDB installations (a CDB with one PDB), or for CDBs with small numbers of PDBs, ORDS can be installed directly into the PDB. The db.servicename parameter will be set to the PDB service name in the properties file. This is the method I typically use as there is no additional ORDS dependency on the CDB.

If you are using many PDBs per CDB, you may prefer to install ORDS into the CDB to allow all PDBs to share the same connection pool. This will drastically reduce the number of database connections used compared to having a separate connection pool per PDB. In this case the db.servicename parameter will be set to the CDB service name in the properties file. From version 18.1 onward there are two ways of installing ORDS into the CDB. The recommended way is to set cdb.common.schema=false in the properties file, which will allow each PDB to run a different version of ORDS. Alternatively you can use cdb.common.schema=true in the properties file, which will mean all PDBs will have to use the same version of ORDS. Whichever option you choose, you will probably want to also use the db.serviceNameSuffix=.your_db_domain parameter to enable the pluggable mapping functionality. For example, you might include these settings in your installation parameter file.

db.servicename=cdb1
cdb.common.schema=false
db.serviceNameSuffix=.example.com

Alternatively, you can set the following parameters after the installation is complete. ORDS will need to be restarted after that is done.

cd /u01/ords
$JAVA_HOME/bin/java -jar ords.war set-property cdb.common.schema false
$JAVA_HOME/bin/java -jar ords.war set-property db.serviceNameSuffix ".example.com"

You can read more about the CDB installation options here.

Remember, even though the documentation doesn't speak explicitly about installing directly into the PDB, but it is a viable option.

Downloads

Download the following software. Always use the latest version available.

ORDS Installation

Check the SYS user and common public users are unlocked and you know their passwords. Remember to lock the SYS user when the installation is complete.

CONN / AS SYSDBA
ALTER USER SYS IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;
--ALTER USER SYS IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK CONTAINER=ALL;

--ALTER SESSION SET CONTAINER = pdb1;
ALTER USER APEX_LISTENER IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;
ALTER USER APEX_PUBLIC_USER IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;
ALTER USER APEX_REST_PUBLIC_USER IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;

-- The next one will fail if you've never installed ORDS before. Ignore errors.
ALTER USER ORDS_PUBLIC_USER IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;

Unzip the ORDS distribution. In this case we are doing this as the "tomcat" user on the server.

# su - tomcat
$ mkdir /u01/ords
$ cd /u01/ords
$ unzip /tmp/ords.17.4.0.348.21.07.zip

Make a directory to hold the configuration.

$ mkdir -p /u01/ords/conf

If you have any failures during the installation, remember to delete the contents of this directory before trying again.

Edit the "/u01/ords/params/ords_params.properties" file provided with the ORDS software, setting the appropriate parameters for your installation. In this case my file contents were as follows.

db.hostname=ol7-122.localdomain
db.port=1521
db.servicename=pdb1
#db.sid=
# Next 2 lines for CDB installations only.
#cdb.common.schema=false
#db.serviceNameSuffix=.your_db_domain
db.username=APEX_PUBLIC_USER
db.password=OraPassword1
migrate.apex.rest=false
plsql.gateway.add=true
rest.services.apex.add=true
rest.services.ords.add=true
schema.tablespace.default=APEX
schema.tablespace.temp=TEMP
standalone.mode=false
# Next 3 lines for standalone mode only.
#standalone.use.https=true
#standalone.http.port=8080
# ORDS19 Onward
#standalone.static.path=/home/oracle/apex/images
# Pre-ORDS19
#standalone.static.images=/home/oracle/apex/images
user.apex.listener.password=OraPassword1
user.apex.restpublic.password=OraPassword1
user.public.password=OraPassword1
user.tablespace.default=APEX
user.tablespace.temp=TEMP
sys.user=SYS
sys.password=OraPassword1
# Enable REST Enabled SQL.
restEnabledSql.active=true
# Enable SQL Developer Web. Available from 19.4 onward. Requires REST Enabled SQL.
feature.sdw=true
# Enable database APIs. Available from 19.1 onward. 
database.api.enabled=true

If you need to restart the installation for any reason, remember of clear down the config directory and check the contents of the "/u01/ords/params/ords_params.properties" file before you restart the installation. Having password entries in this file from a failed installation can cause problems.

Use the "ords.war" file to specify the configuration directory using the following command. The file name "ords.war" will result in a URL containing "/ords/". If you want a different URL, rename the WAR file accordingly. In this article I will use the original name.

$ $JAVA_HOME/bin/java -jar ords.war configdir /u01/ords/conf
Dec 17, 2017 8:50:19 AM
INFO: Set config.dir to /u01/ords/conf in: /u01/ords/ords.war
$

Configure ORDS using the following command. This is the equivalent of specifying the "install simple" command line parameters. If you've entered the parameters correctly in the parameter file there should be no prompts. If some parameters are missing or incorrect you will be prompted for a response.

$ $JAVA_HOME/bin/java -jar ords.war

Retrieving information.
Dec 17, 2017 8:50:59 AM
INFO: Updated configurations: defaults, apex, apex_pu, apex_al, apex_rt
Installing Oracle REST Data Services version 17.4.0.348.21.07
... Log file written to /u01/ords/logs/ords_install_core_2017-12-17_085059_00767.log
... Verified database prerequisites
... Created Oracle REST Data Services schema
... Created Oracle REST Data Services proxy user
... Granted privileges to Oracle REST Data Services
... Created Oracle REST Data Services database objects
... Log file written to /u01/ords/logs/ords_install_datamodel_2017-12-17_085224_00812.log
... Log file written to /u01/ords/logs/ords_install_apex_2017-12-17_085234_00725.log
Completed installation for Oracle REST Data Services version 17.4.0.348.21.07. Elapsed time: 00:01:40.123

$

If your parameter file is in an alternate location, you can use the following syntax.

$ $JAVA_HOME/bin/java -jar ords.war --parameterFile /path/to/my_params.properties --silent

Lock the SYS user.

ALTER USER SYS ACCOUNT LOCK;

Tomcat Deployment

Copy the APEX images to the Tomcat "webapps" directory.

$ mkdir $CATALINA_BASE/webapps/i/
$ cp -R /tmp/apex/images/* $CATALINA_BASE/webapps/i/

Copy the "ords.war" file to the Tomcat "webapps" directory.

$ cd /u01/ords
$ cp ords.war $CATALINA_BASE/webapps/

ORDS should now be accessible using the following type of URL.

http://<server-name>:<port>/ords/

http://ol7.localdomain:8080/ords/

Starting/Stopping ORDS Under Tomcat

ORDS is started or stopped by starting or stopping the Tomcat instance it is deployed to. Assuming you have the CATALINA_HOME environment variable set correctly, the following commands should be used.

export CATALINA_OPTS="$CATALINA_OPTS -Duser.timezone=UTC"

$ $CATALINA_HOME/bin/startup.sh
$ $CATALINA_HOME/bin/shutdown.sh

ORDS Validate

You can validate/fix the current ORDS installation using the validate option.

$ $JAVA_HOME/bin/java -jar ords.war validate
Enter the name of the database server [ol7-122.localdomain]:
Enter the database listen port [1521]:
Enter the database service name [pdb1]:
Requires SYS AS SYSDBA to verify Oracle REST Data Services schema.

Enter the database password for SYS AS SYSDBA:
Confirm password:

Retrieving information.

Oracle REST Data Services will be validated.
Validating Oracle REST Data Services schema version 18.2.0.r1831332
... Log file written to /u01/asi_test/ords/logs/ords_validate_core_2018-08-07_160549_00215.log
Completed validating Oracle REST Data Services version 18.2.0.r1831332.  Elapsed time: 00:00:06.898

$

Manual ORDS Uninstall

In recent versions you can use the following command to uninstall ORDS and provide the information when prompted.

# su - tomcat
$ cd /u01/ords
$ $JAVA_HOME/bin/java -jar ords.war uninstall
Enter the name of the database server [ol7-122.localdomain]:
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 [pdb1]:
Requires SYS AS SYSDBA to verify Oracle REST Data Services schema.

Enter the database password for SYS AS SYSDBA:
Confirm password:

Retrieving information.
Uninstalling Oracle REST Data Services
... Log file written to /u01/ords/logs/ords_uninstall_core_2018-06-14_155123_00142.log
Completed uninstall for Oracle REST Data Services. Elapsed time: 00:00:10.876

$

In older versions of ORDS you had to extract scripts to perform the uninstall in the following way.

su - tomcat
cd /u01/ords
$JAVA_HOME/bin/java -jar ords.war ords-scripts --scriptdir /tmp

Perform the uninstall from the "oracle" user using the following commands.

su - oracle
cd /tmp/scripts/uninstall/core/

sqlplus sys@pdb1 as sysdba

@ords_manual_uninstall /tmp/scripts/logs

For more information see:

Hope this helps. Regards Tim...

Back to the Top.