ORDS 3.0.8 Installation

In the last blog entry i have created two tablespace for APEX itself and executed the SQL script apexins.sql and apex_rest_config.sql. The next step is to configure and prepare the Java Servlet ords.war which we need for deployment in the Java Container “Tomcat”.

After downloading and unzipping the current ORDS version you should go to the corresponded directory, for example on my system: D:\Oracle\ORDS\ords.>
and run the ords.war command in a DOS box:

D:\Oracle\ORDS\ords.> java -jar ords.war

By the way, sometimes you can see java -jar ords.war install simple this is the default for the call of java -jar ords.war

You will be asked several parameters (questionnaire):

Determine your Configuration Directory: e.g. d:\oracle\ords
Name of the database server [localhost]: on the same host? ⇒ confirm it
DB-Listener [1521]: confirm it
Insert 1 for the Service Name, 2 for the SID [1]: press 1
Enter your Service Name: e.g. xe
Optional – Enter 1 to install/verify ORDS Schema or 2 for skip this task [1]: if you will be asked, then press 1
Password for ORDS_PUBLIC_USER: set a new password
Password confirmation for ORDS_PUBLIC_USER: confirm the password
Enter the username with SYSDBA privileges … [SYS] press Enter
Password for SYS: password
Password confirmation for SYS: confirm the password
Enter 1 if you want to use PL/SQL Gateway or
2 to skip this step …
press 1. Do not mix up the PL/SQL Gateway with the embedded PL/SQL Gateway (EPG). This is totally different.
Enter the PL/SQL Gateway user [APEX_PUBLIC_USER]: press Enter
Password for APEX_PUBLIC_USER: set a new password and make a note of it. We need it later, after the Tomcat installation.
Password confirmation for APEX_PUBLIC_USER: confirm the password
Enter 1 if you want to set passwords for APEX_LISTENER and APEX_REST_PUBLIC_USER or 2 for skipping: press 1
Password for APEX_LISTENER: same password during the installation for script apex_rest_config.sql
Password confirmation for APEX_LISTENER: confirm the password
Password for APEX_REST_PUBLIC_USER: same password during the installation for script apex_rest_config.sql
Password confirmation for APEX_REST_PUBLIC_USER: confirm the password
Enter 1 if you wish to start in standalone mode or 2 to exit [1]: press 2 for exit

Table 1: Prompts for java -jar ords.war 

With the first parameter of the ords.war questionnaire, the configuration directory has been specified. Here D:\Oracle\ORDS. A look in this directory and you can see one new folder ords with a subfolder conf and file defaults.xml . This file is for further configurations and some enhancements of the Servlet.

In directory conf are all relevant users with their encrypted passwords which you have set with the questionnaire above.

apex.xml, APEX_PUBLIC_USER The database user is used when invoking PL/SQL Gateway operations from Apex. This user establish the connection to the database and execute Apex applications. Additionally APEX_PUBLIC_USER is required to configure ORDS with Oracle APEX. The user do not invoking RESTful Services.
apex_al.xml, APEX_LISTENER The database user is used to query RESTful Services definitions stored in Oracle Apex. Please have in mind, there is a difference between querying and invoking of RESTful Services.
apex_pu.xml, ORDS_PUBLIC_USER This user is necessary if you want to use RESTful Sevices without Oracle Apex. This is possible since ORDS 3.X. Prior ORDS 3.X RESTful Web Services required Oracle APEX.  This is not longer needed but consider Oracle as a database is required. ORDS_PUBLIC_USER and ORDS_METADATA will be installed during the call of java -jar ords.war
apex_rt.xml, APEX_REST_PUBLIC_USER The database user is used when invoking RESTful services in Apex. Furthermore the user is necessary for all kinds of static application/workspace files deposit in Apex, if ORDS is your web listener.

Table 2: encrypted password files and created users for ords.war installation

The unzipped ORDS directory has two more important files. These are ords_params.properties in subfolder params:

and ords.war, which is deposit in the unzipped folder itself:

The ords_params.properties will be filled with some information which i have inserted during the questionnaire of the call java -jar ords.war. You can accomplish a silent installation or repeat some installation steps later on with this file.

Further ords.war commands

Suppose you want to set new passwords. With the deletion of e.g., apex_pu.xml from conf directory, you can set a new ORDS_PUBLIC_USER password. With the deletion of apex.xml, you can set the password for APEX_PUBLIC_USER, and so on for the others (apex_al.xml and apex_rt.xml). For this purpose execute the call:

java -jar ords.war setup

you will be asked several parameters. In other words, don’t worry if you have forgotten a password for a certain user or if the XML-files above (look table 2) have been deleted or changed. You can recreate it every time.

May be you want to reinstall the ORDS option from scratch and additionally set certain tablespaces for the Schemas ORDS_METADATA and ORDS_PUBLIC_USER (the default is SYSAUX and USERS). In this case delete the following lines in ords_params.properties.

  • schema.tablespace.default=...
  • schema.tablespace.temp=...
  • user.tablespace.default=...
  • user.tablespace.temp=...

and reinstall ORDS again. For this purpose make at first an uninstall via:

java -jar ords.war uninstall

You have to enter host, port, service name and a sysdba user. Please have attention, both ORDS schemas with their corresponding objects will be deleted. But it doesn’t matter if you are in the setup phase or you want to play around on this topic and furthermore with the next installation, all basic objects will be created as before. Therefore the next step is the advanced installation process:

java -jar ords.war install advanced

Beside the questionnaire above of table 1, you will be prompted for default and temp tablespaces for ORDS_METADATA and ORDS_PUBLIC_USER. This is the chance to insert another tablespace as default, but remember the tablespace name has to exist, otherwise you will get an error.

Don’t worry about user-schema ORDS_METADATA. This schema has been established with the ords.war call. Password for ORDS_METADATA is an arbitrary string. Here is a short excerpt of the file ords_create_schema.sql which will be called with java -jar ords.war [setup | install | install simple | install advanced] and creates schema ORDS_METADATA.


pwd  := 'X' || sys.dbms_random.string('X', 29);
EXECUTE immediate 'create user ^ORDSSCHEMA identified by ' || pwd ||
                  '  password expire account lock';

Another important ords.war command is:

java -jar ords.war configdir

With this call you find out your current configuration directory.

If you want to set a new config directory, for instance c:\ords3\ then execute the following:

java -jar ords.war configdir c:\ords3

After all, with the commands java -jar ords.war [setup | install | install simple | install advanced] we have configured/prepared the ords.war Java Servlet and with the Tomcat installation, what i do as next, the ords.war file has to be copied into Tomcat’s .\webapps folder.

Leave a Reply