Oracle REST Data Services (ORDS) 22.1 : All Change!

 

You may have heard version 22.1 of Oracle REST Data Services (ORDS) has been released. For the versions between 3.0 and 21.4 the installation process was pretty much the same. From version 22.1 it’s out with the old and in with the new…

I’ve put out an installation article, but remember it’s early days for me, so I will probably be revisiting this over the coming weeks as I learn more.

The Big News

  • We no longer run commands using “ords.war” directly. Instead we use an “ords” script/executable in the “bin” subdirectory. That kind-of makes every installation or configuration article you’ve ever read wrong.
  • The above change means standalone mode is also different, so even starting and stopping ORDS has changed.
  • The configuration location is no longer written into the “ords.war” file, so you have to make sure standalone, Tomcat, WebLogic knows where to find the config.
  • The contents/structure of the configuration has changed, so once again anything you’ve read about configuration has probably changed.

It all sounds quite dramatic, and it certainly confused the hell out of me, but I think a couple of weeks down the line I will forget it was ever any other way. 🙂

I’ve updated one of my Vagrant builds to use the new version. I’ll do the others over time…

Over the next few days/weeks I’ve got to visit all my ORDS content (over 30 articles) to check how these changes have impacted it. Off the top of my head I think I’ve got about 3 rewrites to do, and some corrections of other articles.

Don’t Panic

From a usage perspective, ORDS looks the same, so there is no need to panic. It’s just one of those administration evolutions you expect in the lifetime of a product.

Cheers

Tim…

PS. I’ve been making Jeff Smith‘s life miserable regarding the documentation. Thanks for the feedback and changes Jeff. 😉

Author: Tim...

DBA, Developer, Author, Trainer.

38 thoughts on “Oracle REST Data Services (ORDS) 22.1 : All Change!”

  2. Eric: Things have got to move forward. As ORDS has become more popular, certain aspects of its administration stick out as being not so good. This change makes the experience more consistent and better IMHO. It’s annoying to have to rewrite stuff, but I’m OK with it, provided it is for the better. Remember, usage of the product remains the same. It’s only installations that have changed.

  3. I was kidding! I know more people probably go to your site than Oracle’s for help!

  4. Hello! I have followed your instructions and installed ords 22.1 + tomcat on windows. Something must be wrong because ords throws 404 error when you start it.
    I have already checked that on the same machine/windows version: ords 22.1 standalone works and ords 21.4 + tomcat works. Could you please check the windows build and provide instructions on your article?
    Maybe there is a bug…
    Thank you in advance…
    Regards

  5. Geo: I don’t use Windows for servers. I suspect you’ve not set the JAVA_OPTS environment variable, so ORDS under Tomcat doesn’t know where the config is. Check the Tomcat logs to see if the pools are initiated during the startup.

  6. I had an endless list of problems since switching from Apache based OHS to ORDS.
    I don’t know if it is just me, but I found it incredibly difficult to understand the documentation and create the required scripts to configure and install ORDS without user interaction.
    I was delighted to read that in 22.1 finally a proper cli is available but unfortunately things did not improve at all and I’m struggling as always.
    I basically only use the plsql-gateway and apex or any other components and am trying to setup a development environment using the standalone server and a production environment using tomcat.
    My latest config attempt looks something like this and only results in a 404 when trying to start my app at http://127.0.0.1:8080/ords/lj_unittest

    export ORDS_CONFIG=config
    ords install –config-only –feature-db-api false –feature-rest-enabled-sql false –feature-sdw false –db-pool lj-unittest –db-hostname 127.0.0.1 –db-port 1521 –db-servicename TEST –gateway-mode direct –gateway-user LJ_UNITTEST –password-stdin $ORDS_CONFIG/databases/lj-unittest/paths
    ords serve

    Any hint on what I’m missing would be most appreciated.
    I also did not find any explanation in the documentation on how to exactly use the –gateway-mode option.

  7. As soon as I ran “java -jar ords.war install simple” trying to install ORDS V22 I got the “Error: A JNI error has occurred…” because I was trying to use JDK 1.8. That was when I realized I needed to read the documentation. ha. ORDS V22+ needs either Java 11 or 17. I figured I’d just need to research how to migrate to latest JDK v17. But now I read your notes and seems alot more has changed besides just requiring newer JDK. Time to put on my reading glasses.

  10. Tim: could you elaborate on your plsql gateway example. Why is the —admin-user argument needed and why is –gateway-mode set to proxied?

  11. Dieter: We are setting up a new connection, so we need –admin-user to connect to a privileged account, so that the necessary stuff can be done behind the scenes.

    The –gateway-mode is set to proxied, because ORDS will need to run as PLSQLUSER, to the ORDS_PUBLIC_USER will need to proxy to that account. This is similar to the way ORDS_PUBLIC_USER proxies to APEX_PUBLIC_USER when it is fronting APEX. It’s just another PL/SQL application…

    The easiest way to get to grips with this is to create a little test system and play around with it. Trying to work directly on a real system can be distracting. I’ve literally gone through all my articles testing them, to make sure I understand the impact of what I have tried.

    Cheers

    Tim…

  12. Tim: Do I need to specify an admin user because ORDS 22.1 now wants to run something in the database. Until now, this was not needed when only using the PLSQL gateway and would you know what exactly is run/installed? I’m still struggling to understand why I need the ORDS_PUBLIC_USER and then proxy to the actual one. Is this not what the –gateway-mode direct is for or what else would it be used for.

  13. Hi.

    There is a DIRECT option for running PL/SQL, but I don’t use it. I run stuff the same what APEX runs it. If I have time I’ll give it a go later and add it to the article. No promises.

    Cheers

    Tim…

  15. So I’m facing the 404 error as well – Tomcat logs state: No pools configured yet

    I’ve set an environment variable called JAVA_OPTS with a value of -Dconfig.url=C:\Oracle\config\ords\

    APEX runs fine in standalone mode. Have copied images from APEX/Images to Webapps/i and also the ords.war file into the Webapps folder and deployed under Tomcat Manager. Do you know if there’s something in this ords.war file that refers to a config directory, I’m assuming not a guess it’s all done from the environment variables from 22.1 onwards, i.e. ORDS_CONFIG

    Thanks!!

  16. Fixed it!!!

    JAVA_OPTS wasn’t working (on Windows 10), so I set up the variable name as JAVA_TOOL_OPTIONS and worked right away – AMAZING!!

  17. Ben: The reference to the ORDS config is no longer written into the ords.war, so the location must be specified in another manner. It looks like you cracked it with JAVA_TOOL_OPTIONS. I’ll put something in my post for anyone else running on Windows.

    Cheers

    Tim…

  18. I am setting up a Single machine to house database 21c, ords, graph server and Spatial server on Linux 8 and Java 11 (I also have Java 17. Can use this one box for my Test/Development environment? I have 64G RAM.
    Any suggestions on configuration? I use a Windows desktop to connect to the database, apex, spatial and graph.

    Regards

  19. Amin: If you were talking about a production system, I would say don’t have it all on the same server. Since it’s for Dev/Test you can do what you like. There are examples of Oracle and ORDS installations on my website. I know nothing spatial and graph, so I can’t help you there. Also, I rarely use Windows. Or I should say I always use Windows, but I always use virtual machines running Oracle Linux to run Oracle software. 🙂

  20. Just when I thought I’d got hold of how to install/run v21 I have now been forced to learn v22 (due to a bug in v21 installing into pluggable databases)!
    I have installed a basic setup (OS=AIX) – no database pools (just default) and using the standalone mode – but keep getting the 404 error.
    Any ideas what I’m doing wrong or misunderstanding?

    — For the ORDS install I ran :
    cd $ORACLE_HOME/ords
    mkdir /oracle/hcmgrpu1/ords22_config
    export PATH=$PATH:$ORACLE_HOME/ords/bin
    export ORDS_CONFIG=/oracle/hcmgrpu1/ords22_config
    ords install

    — I chose basic database connection type and gave the following values :
    Enter the database host name [localhost]: uathcmora01.foschini.co.za
    Enter the database listen port [1521]:
    Enter the database service name [hcmcdbu1]: hcmgrpu1

    — I then ran the following config commands (and /oracle/hcmgrpu1/ords22_config/global/settings.xml was created) :
    ords config set standalone.static.path /oracle/hcmgrpu1/19.3.0/apex/images
    ords config set standalone.http.port 8090
    ords config set standalone.context.path /ords

    — I then started ORDS using :
    ords serve

    But URL “http://uathcmora01.foschini.co.za:8090/ords” keeps giving 404 Not Found. Nothing appears in the ‘ords serve’ console.

  22. This is the output from the install where I input values :

    ords install

    ORDS: Release 22.2 Production on Thu Jul 07 10:40:25 2022

    Copyright (c) 2010, 2022, Oracle.

    Configuration:
    /oracle/hcmgrpu1/ords22_config/

    The configuration folder /oracle/hcmgrpu1/ords22_config does not contain any configuration files.

    Oracle REST Data Services – Interactive Install

    Enter a number to select the type of installation
    [1] Install or upgrade ORDS in the database only
    [2] Create or update a database pool and install/upgrade ORDS in the database
    [3] Create or update a database pool only
    Choose [2]: 1
    Enter a number to select the database connection type to use
    [1] Basic (host name, port, service name)
    [2] TNS (TNS alias, TNS directory)
    [3] Custom database URL
    Choose [1]: 1
    Enter the database host name [localhost]: uathcmora01.foschini.co.za
    Enter the database listen port [1521]:
    Enter the database service name [hcmcdbu1]: hcmgrpu1
    Provide database user name with administrator privileges.
    Enter the administrator username: sys
    Enter the database password for SYS AS SYSDBA:
    Connecting to database user: SYS AS SYSDBA url: jdbc:oracle:thin:@//uathcmora01.foschini.co.za:1521/hcmgrpu1

    Retrieving information.
    Enter the default tablespace for ORDS_METADATA and ORDS_PUBLIC_USER [SYSAUX]:
    Enter the temporary tablespace for ORDS_METADATA and ORDS_PUBLIC_USER [TEMP]: APEX_TEMP
    Enter the database password for ORDS_PUBLIC_USER:
    Confirm password:
    2022-07-07T10:42:15.254Z INFO Installing Oracle REST Data Services version 22.2.0.r1721758 in hcmgrpu1
    ————————————————————
    Date : 07 Jul 2022 10:42:15
    Release : Oracle REST Data Services 22.2.0.r1721758
    Type : ORDS Install
    Database : Oracle Database 19c Enterprise Edition
    DB Version : 19.14.0.0.0

  23. OK. My next through would be to check that APEX_PUBLIC_USER is unlocked. ORDS will proxy to it, but it needs to be unlocked for it to work.

  26. I don’t see any log files in $ORACLE_HOME/ords nor in the config directory (/oracle/hcmgrpu1/ords22_config), nor in $ORACLE_HOME/apex.

  27. I see that when I run ‘ords serve’ the console displays :
    HTTP and HTTP/2 cleartext listening on host: 0.0.0.0 port: 8090

    I supplied ‘uathcmora01.foschini.co.za’ when I ran ords install, so why is it listening on host 0.0.0.0? Should there be an entry in settings.xml for host?

  28. Can you repeat the install and use the “–log-folder” option, so you know where the logs are bring written. 🙂

    I don’t think 0.0.0.0 is a problem. This usually means it will accept requests from any local IP address, including the real IP address and 127.0.0.1.

    Question: Is the 404 a browser message, or are you seeing an ORDS page telling you it is a 404? I just want to know if you are actually connecting to ORDS when you make the call. 🙂

    Cheers

    Tim…

  32. Hi Tim

    So I did the following :

    ords uninstall
    mkdir /oracle/hcmgrpu1/ords22_logs
    ords install –interactive –log-folder /oracle/hcmgrpu1/ords22_logs

    Log file /oracle/hcmgrpu1/ords22_logs/ords_install_2022-07-11_120520_38136.log was created.

    ords serve

    No new files in logs directory.

    Launched http://uathcmora01.foschini.co.za:8090/ords/ in a new browser. Got 404 error again, but no new files in the logs directory.

  33. Hi.

    I’m really not sure what to say then. It looks like you have done everything OK to me. Don’t really know what to say, other than post it on the ORDS community site and one of the ORDS folks will see it. I’ve not seen this with any new installations or upgrades…

    Cheers

    Tim…

  34. Thanks for your assistance Tim.
    I’ve got a SR open with Oracle but the engineer doesn’t seem to be close to a resolution.

  35. Paul: Personally I would always suggest installing in silent mode, like I show here.

    https://oracle-base.com/articles/misc/oracle-rest-data-services-ords-installation-on-tomcat-22-onward#ords-installation

    The reason is you can record all the options you picked, and can show anyone else exactly what you did. Added to that, you can check your build scripts into source control. 🙂

    There are examples of the different types of installation here.

    https://oracle-base.com/articles/misc/oracle-rest-data-services-ords-configure-multiple-databases-22-onward

    Cheers

    Tim…

  37. Hi Tim

    Finally got success! Oracle suggested using Option 2 in the install (rather than Option 1) :
    [2] Create or update a database pool and install/upgrade ORDS in the database
    and that worked.

    Regards
    Paul

Comments are closed.