ORDS: Installation and Configuration

1

In my job as system administrator/DBA/integrator I was challenged to implement smoketesting using REST calls. Implementing REST in combination with WebLogic is pretty easy. But then we wanted to extend smoketesting to the database. For example we wanted to know if the database version and patch level were at the required level as was used throughout the complete DTAP environment. Another example is the existence of required database services. As it turns out Oracle has a feature called ORDS – Oracle REST Data Service – to accomplish this.

With ORDS you can install it in 2 different scenario’s, in standalone mode on the database server, or in combination with an application server such as WebLogic Server, Glassfish Server, or Tomcat.

This article will give a short introduction to ORDS. It then shows you how to install ORDS feasible for a production environment using WebLogic Server 12c and an Oracle 12c database as we have done for our smoketesting application.

We’ve chosen WebLogic Server to deploy the ORDS application because we already used WebLogic’s REST feature for smoketesting the application and WebLogic resources, and for high availability reasons because we use an Oracle RAC database. Also running in stand-alone mode would lead to additional security issues for port configutions.

Terminology

REST: Representational State Transfer. It provides interoperability on the Internet between computer systems.

ORDS: Oracle REST Data Services. Oracle’s implementation of RESTful services against the database.

RESTful service: an http web service that follows the REST architecture principles. Access to and/or manipulation of web resources is done using a uniform and predefined set of stateless operators.

ORDS Overview

ORDS makes it easy to develop a REST interface/service for relational data. This relational data can be stored in either an Oracle database, an Oracle 12c JSON Document Store, or an Oracle NoSQL database.

A mid-tier Java application called ORDS, maps HTTP(S) requests (GET, PUT, POST, DELETE, …) to database transactions and returns results in a JSON format.

ORDS Request Response Flow

Installation Process

The overall process of installing and configuring ORDS is very simple.

  1. Download the ORDS software
  2. Install the ORDS software
  3. Make some setup configurational changes
  4. Run the ORDS setup
  5. Make a mapping between the URL and the ORDS application
  6. Deploy the ORDS Java application

Download the ORDS software

Downloading the ORDS software can be done from the Oracle Technology Network. I used version ords.3.0.12.263.15.32.zip. I downloaded it from Oracle Technet:
http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html

Install the ORDS software

The ORDS software is installed on the WebLogic server running the Administration console. Create an ORDS home directory and unzip the software.

Here are the steps on Linux

$ mkdir -p /u01/app/oracle/product/ords
$ cp -p ords.3.0.12.263.15.32.zip /u01/app/oracle/product/ords
$ cd /u01/app/oracle/product/ords
$ unzip ords.3.0.12.263.15.32.zip

Make some setup configurational changes

ords_params.properties File

Under the ORDS home directory a couple of subdirectories are created. One subdirectory is called params. This directory holds a file called ords_params.properties. This file holds some default parameters that are used during the installation. This file ords_params.properties, is used for silent installation. In case any parameters aren’t specified in this file, ORDS interactively asks you for the values.

In this article I go for a silent installation. Here are the default parameters and the ones I set for installing

Parameter

Default Value

Configured Value

db.hostname

dbserver01.localdomain

db.port

1521

1521

db.servicename

ords_requests

db.username

APEX_PUBLIC_USER

APEX_PUBLIC_USER

migrate.apex.rest

false

false

plsql.gateway.add

false

false

rest.services.apex.add

false

rest.services.ords.add

true

true

schema.tablespace.default

SYSAUX

ORDS

schema.tablespace.temp

TEMP

TEMP

standalone.http.port

8080

8080

user.public.password

Ords4Ever!

user.tablespace.default

USERS

ORDS

user.tablespace.temp

TEMP

TEMP

sys.user

SYS

sys.password

Oracle123

NOTE

As you see, I refer to a tablespace ORDS for the installation of the metadata objects. Don’t forget to create this tablespace before continuing.

NOTE

The parameters sys.user and sys.password are removed from the ords_params.properties file after running the setup (see later on in this article)

NOTE

The password for parameter user.public.password is obscured after running the setup (see later on in this article)

NOTE

As you can see there are many parameters that refer to APEX. APEX is a great tool for rapidly developing very sophisticated applications nowadays. Although you can run ORDS together with APEX, you don’t have to. ORDS runs perfectly without an APEX installation.

Configuration Directory

I create an extra directory to hold all configuration data, called config directly under the ORDS home directory. Here all configurational data used during setup are stored.

$ mkdir config
$ java -jar ords.war configdir /u01/app/oracle/product/ords/config
$ # Check what value of configdir has been set!
$ java -jar ords.war configdir

Run the ORDS setup

After all configuration is done, you can run the setup, which installs the Oracle metadata objects necessary for running ORDS in the database. The setup creates 2 schemas called:

  • ORDS_METADATA
  • ORDS_PUBLIC_USER

The setup is run in silent mode, which uses the parameter values previously set in the ords_params.properties file.

$ mkdir -p /u01/app/oracle/logs/ORDS
$ java -jar ords.war setup –database ords –logDir /u01/app/oracle/logs/ORDS –silent

Make a mapping between the URL and the ORDS application

After running the setup, ORDS required objects are created inside the database. Now it’s time to make a mapping from the request URL to the ORDS interface in the database.

$ java -jar ords.war map-url –type base-path /ords ords

Here a mapping is made between the request URL from the client to the ORDS interface in the database. The /ords part after the base URL is used to map to a database connection resource called ords.

So the request URL will look something like this:

http://webserver01.localdomain:7001/ords/

Where http://webserver01.localdomain:7001 is the base path.

Deploy the ORDS Java application

Right now all changes and configurations are done. It’s time to deploy the ORDS Java application against the WebLogic Server. Here I use wlst to deploy the ORDS Java application, but you can do it via the Administration Console as well, whatever you like.

$ wlst.sh
$ connect(‘weblogic’,’welcome01′,’t3://webserver01.localdomain:7001′)
$ progress= deploy(‘ords’,’/u01/app/oracle/product/ords/ords.war’,’AdminServer’)
$ disconnect()
$ exit()

And your ORDS installation is ready for creating REST service!

NOTE

After deployment of the ORDS Java application, it’s state should be Active and health OK. You might need to restart the Managed Server!

Deinstallation of ORDS

As the installation of ORDS is pretty simple, deinstallation is even more simple. The installation involves the creation of 2 schemas on the database and a deployment of ORDS on the application server. The deinstall process is the reverse.

  1. Undeploy ORDS from WebLogic Server
  2. Deinstall the database schemas using

    $ java –jar ords.war uninstall

    In effect this removes the 2 schemas from the database

  3. Optionally remove the ORDS installation directories
  4. Optionally remove the ORDS tablespace from the database

References

Summary

The installation of ORDS is pretty simple. You don’t need to get any extra licenses to use ORDS. ORDS can be installed without installing APEX. You can run ORDS stand-alone, or use a J2EE webserver like WebLogic Server, Glassfish Server, or Apache Tomcat. Although you will need additional licenses for the use of these webservers.

Hope this helps!

About Author

Paul is an Oracle consultant at AMIS. Paul is an experienced Oracle DBA and solution architect. His core expertise is the Oracle Database and WebLogic Server. Recently Paul has broadened his field of expertise to Continuous Delivery and Continuous Integration.

1 Comment

  1. Asif Saleem Ghazi on

    Hi Paul,

    I am trying to install ords version 18.2.0 with Tomcat as a Web Server.
    I 100% follow all mentioned installation steps for ORDS. But I am unable to understand for Tomcat.
    Could you please share the steps for Tomcat. When i try to copy ords.war on CATALINE_HOME/webapps. Its not working and give me below error.
    404 Not Found

    Thanks
    Asif

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.