How to check if ORDS is running

Oracle REST Data Services (ORDS) provides web services for an Oracle Database and allows for access to the database over the web. In a recent YouTube video I showed how to use ORDS in the new Oracle Developer DB Virtual Machine and briefly mentioned how to find the running ORDS process. Let’s go into that in more detail. In this article, we will discuss how to check if ORDS is running in a standalone ORDS deployments as well as deployments on Apache Tomcat and Oracle WebLogic Server.

  1. Checking ORDS on Standalone Deployments
  2. Checking ORDS on Apache Tomcat
  3. Checking ORDS on Oracle WebLogic Server
  4. What about Windows systems?
  5. Conclusion

Checking ORDS on Standalone Deployments

On a unix based system, the simplest way to check if ORDS is running is to use the jps command. This command will list all Java process that are currently running on the system. It is important to note that in order for jps to work, the JDK must be installed and the PATH environment variable must be set correctly. The jps command accepts a number of options and the most useful in this case are

  • -m to display the arguments passed to the main method
  • -l to display the full path name to the ords.war location. Pass that through a grep for ords to find the ords specific java process.
  • -v displays the arguments passed to the JVM.
jps -mlv | grep ords
8545 /home/oracle/ords/ords.war --config /home/oracle/ords_config serve --secure --port 443 -Doracle.dbtools.cmdline.home=/home/oracle/ords -Duser.language=en -Duser.region=US -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dnashorn.args=--no-deprecation-warning -Doracle.dbtools.cmdline.ShellCommand=ords -Duser.timezone=UTC

If ORDS is running in standalone mode, you should see a process with ords.war in the path. If this process is listed, then ORDS is running. Note that due to the -v option you also see the Java option oracle.dbtools.cmdline.home used. That should be the folder that the ords.war is found in and should also be the distribution directory. In the above example, the distribution directory is /home/oracle/ords/ and the ORDS command used to start ORDS was actually /home/oracle/ords/bin/ords --config /home/oracle/ords_config serve --secure --port 443

Another approach is to use the ps command. This command will list all processes currently running on the system. To check if ORDS is running, use the command ps -ef | grep ords.war. If you see a process with ords.war as the command, then ORDS is running.

[oracle@localhost ~]$ ps -ef | grep ords.war
oracle      8545    8516  2 21:13 pts/1    00:00:49 /home/oracle/java/jdk-11.0.17/bin/java -Doracle.dbtools.cmdline.home=/home/oracle/ords -Duser.language=en -Duser.region=US -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dnashorn.args=--no-deprecation-warning -Doracle.dbtools.cmdline.ShellCommand=ords -Duser.timezone=UTC -jar /home/oracle/ords/ords.war --config /home/oracle/ords_config serve --secure --port 443
oracle      9554    3521  0 21:42 pts/0    00:00:00 grep --color=auto ords.war

You’ll also see similar information as with the jps command but also the java executable used at start up too. Note that access to run ps is not always guaranteed and it main not be available for the user you are logged in as.

One note about the command line arguments one can see for the running Java processes. It can be seen by other users. This is one of the reasons that ORDS does not accept a password as a command line option. That password would be visible to anyone able to list the running processes. Either through jps or ps.

Checking ORDS on Apache Tomcat

If it’s enabled, use the Tomcat manager web application, or at the very least the catalina log files, to confirm that ORDS web application is deployed and started. If not, then jps on the command line is the next logical choice.

When ORDS is deployed on Apache Tomcat, you can use the jps command to check if the server is running and get further information about where the ords.war might be deployed. Run jps -mlv as before but this time grep for the catalina package.

jps -mlv | grep catalina
88 org.apache.catalina.startup.Bootstrap start --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/ --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED -Djava.util.logging.config.file=/usr/local/tomcat/conf/ -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Dconfig.url=/u01/oracle/properties/config -Djdk.tls.ephemeralDHKeySize=2048 -Djava.protocol.handler.pkgs=org.apache.catalina.webresources -Dignore.endorsed.dirs= -Dcatalina.base=/usr/local/tomcat -Dcatalina.home=/usr/local/tomcat

The above indicates that catalina.base is /usr/local/tomcat and most people use the automatic web application deployment by placing the ords.war in the $CATALINA_BASE/webapps/ directory.

ls -la /usr/local/tomcat/webapps/
total 92384
drwxr-xr-x 1 root root       62 Apr 11 06:40 .
drwxr-xr-x 1 root root       77 Apr 11 06:40 ..
drwxr-x--- 5 root root       67 Apr 11 05:38 ords
-rw-r--r-- 1 root root 94599760 Apr 10 19:45 ords.war
drwxr-xr-x 3 root root       45 Apr 11 05:38 ROOT

That directory listing shows the ords.war file and that it has been exploded by Tomcat into the ords directory. It’s not a guarantee that ORDS was deployed successfully, one would have to check the Tomcat logs, but it is a good indicator.

Checking ORDS on Oracle WebLogic Server

If it’s enabled, use the WebLogic console or WLST to confirm that ORDS web application is deployed and started.

Similar to Apache Tomcat, the Oracle WebLogic Server is a Java application so yet again, it is the jps utility that is the starting point to get information on the server(s) running and their configuration.

jps -mvl | grep weblogic
80 weblogic.Server -Dlaunch.use.env.classpath=true -Dweblogic.Name=AdminServer -Dconfig.url=/u01/oracle/properties/config -javaagent:/u01/oracle/wlserver/server/lib/debugpatch-agent.jar -da -Dwls.home=/u01/oracle/wlserver/server -Dweblogic.home=/u01/oracle/wlserver/server

The output indicates that the weblogic.home is /u01/oracle/wlserver/server. Unlike with Tomcat, one is not going to find a straight forward web application deployment directory under the weblogic.home. There’s a little more digging required to check if a server is configured to deploy ORDS and we’ll use the weblogic.Name parameter ( AdminServer in this case) to when digging deeper. The weblogic.home just indicates where the server java application is being executed from. The server runtime configuration is being picked up separately. In the majority of installations that will be in a related user_projects/domains directory found two levels up. For the above WLS instance that would be /u01/oracle/user_projects/domains/.

That directory may have the configuration for multiple domains but quite often there is just one: base_domain. From there you can get a little more information on how the server identified by the above weblogic.Name. The domain configuration is persisted in /u01/oracle/user_projects/domains/base_domain/config/config.xml and you can see there is an app-deployment configuration targetting the AdminServer.

<?xml version="1.0" encoding="UTF-8"?>
<domain xsi:schemaLocation="" xmlns="" xmlns:sec="" xmlns:wls="" xmlns:xsi="">

If you see this app-deployment configuration in place it is not a complete guarantee that ORDS successfully deployed when the server started but it is a good indication.

What about Windows systems?

The syntax for path separates might be different but the same jps utility options apply and the relative file locations will also be the same for standalone, Tomcat and WebLogic.


In summary, the jps utility, also known as the Java Virtual Machine Process Status Tool, that comes with your Java SE distribution is your friend. Just from the command line, it can guide you in discovering more about the ORDS instance running on your machine irrespective of deployment mode.

ORDS Standalone vs Tomcat vs WebLogic

When it comes to deploying Oracle REST Data Services (ORDS), there are three main options to consider: Standalone, Apache Tomcat, and Oracle WebLogic Server. Each has its own advantages and drawbacks, so it’s important to understand the differences between them before choosing a deployment option.

ORDS Standalone

ORDS Standalone is the simplest deployment option and requires no external application servers. In fact, once you have ORDS, you have all you need to get started. It uses the Eclipse Jetty server embedded in ORDS, which is suitable for development, testing and production environments. It’s easy to set up and manage. It’s simplicity makes it ideal for smaller workloads but can also scale for high availability and greater throughput when a load balancer is put in front multiple ORDS standalone instances.

To run ORDS in standalone mode: ords --config /path/to/config/ serve

One should note that although using ORDS with Apache Tomcat or Oracle WebLogic Server is supported, quite often the diagnosis process for any support issues will involve verifying if the issue also occurs with ORDS standalone.

As mentioned in a previous article about Application Process Monitoring, when running in standalone mode, ORDS loads the jars from the ords.war into memory and some Java Agents which modify jars to instrument classes at the byte level can interfere with that classloading process. Examples of Java Agents which can not be used when ORDS standalone mode is used: Oracle APM Java Agent, DynaTrace Java Monitoring.


  • Easy to set up and manage. Get started straight away!
  • Can generate a convenient self-signed certificate for HTTPS.
  • Suitable for development and testing.
  • Ideal for a variety of workloads.
  • ORDS configuration of embedded Jetty server optimised for REST services.
  • Jetty configuration is extensible using XML files.


  • Limited integration with identity and authorisation management systems.
  • Requires a load balancer for high availability.
  • Does not work with some Java Agents.

ORDS Deployment to Tomcat

Apache Tomcat powers numerous large-scale, mission-critical web applications across a diverse range of industries and organisations. Chances are that your organisation is already running at least one Apache Tomcat servlet container. Tomcat is a popular open-source web server that is well-suited to ORDS.

It’s easy to set up, and deploying ORDS to Apache Tomcat is as simple as ords --config /path/to/config/ war $CATALINA_HOME/webapps/ords.war

Of course, that’s if your Tomcat configuration has auto deployment enabled, which is the default setting. Similar to ORDS standalone, Tomcat is configured to be reasonably secure for most use cases by default. Also, similar to ORDS standalone, for high availability a load balancer / reverse proxy must be configured to route to the servers.


  • Integration with identity and authorisation management systems, such as Active Directory, OpenID Connect, through container managed security.
  • Suitable for production workloads.
  • Easy to get started with: install Apache Tomcat, start it, generate the ords web application, done.
  • Free.


  • Involves an additional server.
  • More complex to manage than ORDS Standalone for clustering – see Tomcat Cluster documentation. Moreover, since ORDS is stateless, session serialisation, which is a common characteristic of web server clustering, that aspect of most clustered systems is not required.

ORDS Deployment to WebLogic

Oracle WebLogic Server is a unified and extensible platform for developing, deploying and running enterprise applications, such as Java, for on-premises and in the cloud. ORDS deployment to WebLogic is a very robust option. Weblogic is a powerful and reliable application server and provides advanced features such as clustering and load balancing. It’s suitable for large-scale production workloads. However, provisioning and configuring an Oracle Weblogic domain can be complicated.

The steps for deploying ORDS to WebLogic are involved and it’s best to refer to ORDS documentation.


  • Provides advanced features such as clustering and load balancing
  • Suitable for large-scale production workloads
  • Robust and reliable
  • Integration with identity and authorisation management systems, such as Active Directory, OpenID Connect, through container managed security.


  • Requires an Oracle WebLogic application server licence for production
  • Complex to set up and manage but is fairly standard for an enterprise grade application server

Decision Factors

Ultimately, the deployment option that’s best for you depends on the complexity of your integration with other systems. What your organisation already uses, and has support in place for, is also an important factor. ORDS standalone is ideal for getting started, developing and testing new services before deployment to product. It’s also suitable for production workloads. What it misses out of the box is integration with identity and authorisation management systems. That’s essentially the gap that deployment on Tomcat and Weblogic addresses. In all three cases, each mode is suitable for large-scale production workloads with appropriate load balancing in place.

Post Publishing Edits:

February 20th 2023 - Added text about some Java Agents not working with ORDS standalone.
February 25th 2023 - Added text pointing out that ORDS does not retain session state.

Multiple ORDS instances in WebLogic Server or Apache Tomcat

UPDATE! As of ORDS 22.2.0 there is a command to generate web application for deployment to Apache Tomcat or Oracle WebLogic Server. See Deploying Oracle REST Data Services. The below article is informative and perhaps worth your time to get an understanding of web application deployment but there are supported, documented steps for achieving the same thing with the ORDS product. In fact, what is in the ORDS product is better because it also caters for jar content in the /lib/ext/ folder which this article does not cover.

ORDS 22.1.0 introduced a substantial set of changes: Java 11 as minimum, new command line interface and a new configuration directory structure. In fact it is a release that introduces a whole new deployment paradigm.

Deployment Options

What we knew as Standalone Mode in previous ORDS releases still exists and is now initiated through a serve command. The embedded Eclipse Jetty web server and servlet container engine is still at the heart of this convenient way to have ORDS listen HTTP/HTTPS traffic. The significant change is how the configuration directory is determined at startup. There is no longer a requirement to modify the distributed ords.war to set the configuration directory location.

Deployment on a supported servlet container, such as Oracle WebLogic Server or Apache Tomcat, is similarly impacted by this principle that the distributed ords.war should not be modified. A new mechanism for specifying the configuration directory when the application is deployed is required. The ORDS documentation covers the standard approach for a typical setup, use a Java System Property ( -Dconfig.url=/ords_config/ ), startup your server(s) and deploy the web application.

Single Server

For some developers that may not have a full production environment scaled out for high availability, or may be restricted in the Apache Tomcat or WebLogic Server deployment options, the approach to set different servers with their own ords.war and configuration is not always feasible. With previous ORDS releases they may have had the practice of deploying multiple ORDS web applications with different contexts and configurations. At first it would appear that the new direction in ORDS 22.1.0 makes that impossible but it is not. All that is required are a few extra steps.

Bake your own

For deploying to Apache Tomcat or WebLogic Server you can make your own, separate web application with the config.url baked in. Moreover, you can call it whatever makes sense in your context.

Heres a Python script to do that for you:

This script produces a new web application archive file with the jars from the distributed ords.war and web.xml deployment descriptor has the configuration directory path set. That way, wherever it is deployed, it will refer to the specified configuration directory.

Usage: create_deploy_war <source ords.war> <destination war filename> <configuration directory>

For example, if I want to have two ORDS instances deployed called tom and jerry with two separate configuration directories and I have extracted the ORDS 22.1.0 to /opt/oracle/ords- The jerry web application will be configured with a default pool pointing to an Oracle 19c database. The tom web application will be configured with a default pool pointing to an Oracle 21c database. We will show both web applications have these configurations by using the REST Enabled SQL service in ORDS to return database version information. Before that, the web application files must first be created…

./ /opt/oracle/ords- /scratch/ords_webapps/tom.jar /scratch/ords_configs/tom/
./ /opt/oracle/ords- /scratch/ords_webapps/jerry.jar /scratch/ords_configs/jerry/

That will produce two web application war files in /scratch/ords_webapps/ and I can then deploy them…

Oracle WebLogic Server

Two ORDS web applications deployed to a single WebLogic Server
curl -u hr:hr http://localhost:7001/jerry/hr/_/sql

   "database_major_version" : 19,
   "database_minor_version" : 0,
   "database_product_name" : "Oracle",
   "database_product_version" : "Oracle Database 19c Enterprise Edition Release - Production\nVersion",
   "env" : {
      "defaultTimeZone" : "GMT",
      "ordsVersion" : "22.1.0.r1051723"
curl -u hr:hr http://localhost:7001/tom/hr/_/sql

   "database_major_version" : 21,
   "database_minor_version" : 0,
   "database_product_name" : "Oracle",
   "database_product_version" : "Oracle Database 21c Enterprise Edition Release - Production\nVersion",
   "env" : {
      "defaultTimeZone" : "GMT",
      "ordsVersion" : "22.1.0.r1051723"

As you can see from the above, the different web applications have different context paths and are configured to use two different databases.

Apache Tomcat

Two ORDS web applications deployed to Apache Tomcat
curl -u hr:hr http://localhost:8080/jerry/hr/_/sql

   "database_major_version" : 19,
   "database_minor_version" : 0,
   "database_product_name" : "Oracle",
   "database_product_version" : "Oracle Database 19c Enterprise Edition Release - Production\nVersion",
   "env" : {
      "defaultTimeZone" : "GMT",
      "ordsVersion" : "22.1.0.r1051723"
curl -u hr:hr http://localhost:8080/tom/hr/_/sql

   "database_major_version" : 21,
   "database_minor_version" : 0,
   "database_product_name" : "Oracle",
   "database_product_version" : "Oracle Database 21c Enterprise Edition Release - Production\nVersion",
   "env" : {
      "defaultTimeZone" : "GMT",
      "ordsVersion" : "22.1.0.r1051723"

Similar behaviour with Apache Tomcat with two different web applications with their own, separate, configuration.


What I have demonstrated is a script which produces a new web application for deployment in Apache Tomcat or WebLogic Server. The script is written for Python 2 because that’s the version distributed with Oracle WebLogic Server. It creates a new web application based on the distributed ords.war but without the META-INF content. That content includes a signature digest of the web.xml which will be invalid when the new deployment descriptor is written to the new WAR file.

This is what makes it possible to have multiple ORDS instances deployed to the same server all with different configuration directories.

Loosely typed interfaces – The Normalizer Pattern and Oracle SOA Suite

When getting two or more systems working together, the making a connection part is generally the easiest, identity propagation is a bit trickier, but many times, the syntax and semantics of one system is at odds with another one. Over the decades this has been manifest in many ways and thankfully there are tools and techniques to work through them. A collation of such techniques is Enterprise Integration Patterns. The book, along with the associated website, is worthy of a dedicated article or two, and is not the real subject of this article. One message transformation pattern the book describes is the Normalizer Pattern where different formats for essentially the same object are catered for.
An example where this form of message translation becomes necessary is when using a service with a loosely typed interface. This can often happen when an existing system or utility (such as a batch / command processor) gets exposed as a web service. The request / response payload is little more than a collection of key / value pairs. There are a couple of ways to cater for this using Oracle SOA Suite 11g which I will outline in this article. One has full tool support. The other, a solution using XSLT, is not fully supported, but has an advantage in that the XSLT can be used both with the BPEL and Mediator components.

Troublesome Payloads
The challenge is to get something that is strongly typed into something that is loosely typed

Strongly Typed Loosely Typed

Pam Beech


Pam Beech




Now this is quite a simple example and the real world has a lot more complicated cases out there. Ones that would involve number formatting, character encoding, attribute concatenation, and so on. For the purposes of this exercise however, it is ideal to illustrate the point. All the files in this example are free and available for you to use, modify or incorporate into your own solution as you see fit. The example was produced and tested using Oracle Fusion Middleware That is JDeveloper Studio and WebLogic Server 11gR1. To reduce the number of files and dependencies involved, the example is a simple service (BPELProcessExample.wsdl) that takes a strongly typed request payload and returns a loosely typed response payload. The SOA composite project contains two BPEL processes that provide slightly different implementations for this same WSDL.

BPEL assign with copy and insertAfter
You can cater for the key / value pair structure by repeatedly appending a new ‘property’ element and then, using an XPATH predicate to specify which ‘property’ element is the target, copying the desired values. In the BPEL process this can all be done in a single ‘assign’ command, using the insertAfter instruction from the Oracle BPEL extension library. The BPEL designer supports this approach, and it is used extensively in production systems around the globe. It can get difficult to maintain and hard to read if the payload is large though. If dealing with a large payload see if you can split the copy / insertAfter instructions into two or more ‘assign’ commands. Ideally, you would give these ‘assign’ commands logical names such as ‘assign_part_1_admin_details’ and ‘assign_part_2_finance_details’. What is a large payload in this case then? Well, I would say that if you have more than 10 key value pairs you should be seriously thinking about splitting them up and if you have more than 20, you should be definitely splitting them up. Remember, you might be familiar with the structure and understand how it is constructed, but what about the college graduate brought in by the consulting firm in a months time, or even you having to come back to this in 6 months time? Go on, make the maintenance a bit easier for everyone and break that assign behemoth into manageable chunks!

BPEL transform with XSLT
If experienced in dealing with XML documents then this approach will probably be very familiar to you. Extensible Stylesheet Language Transformations is used to convert XML data into some other format, which may also be XML data. In this case the stylesheet explicitly describes the target XML structure, making it somewhat easier to read than the BPEL assign approach described earlier. For example…


The ‘client’ is a namespace prefix for the schema and in this SOA composite example the request and response happen to be defined in the same schema. This is easier to read, even if one is not all that familiar with XSL. For large payloads it is not necessary to split up the transformation as one might consider for the BPEL assign, but it could be done. The single transformation file could have a whole set of templates. However, the XSL Mapper does not support this approach yet, so if using this approach you will have to work in the Source editor, not the Design mode. Since this is using XSLT, the same XSL file can be used by the Mediator too, so it is not only a BPEL solution.

Which one is right for me?
As one can see from the diagrams there is not much difference in the BPEL designer between the two examples and the decision on which technique to use would be based on factors which are different from company to company, but clearly use of the XSL mapper is an important factor.
The complete example application with SOA composite is available at

ModuleException http:101216 on WebLogic

A number of people have asked about the ‘ModuleException: [HTTP:101216]Servlet:’ error I came across as part of the multi-platform Dice Service example. The experiences are covered in three (first problem, second problem, solved) separate articles which I will collate and summerise here.

Use ant to build web app
Some JEE 5 containers allow you to define your annotated classes and then drop them in an ‘autodeploy’ folder. Not with WebLogic Server v10 though, an ant script is required to do some more work on the web application. Interestingly, the WLS documentation does not refer to autodeploy for web services, in fact according to the WLS Web Service documentation a weblogic ant task ‘JwscTask’ is needed to compile the annotated web service and produce the necessary WAR and EAR for deployment.

Without the JwscTask, simply dropping a JAX-WS web app in the deplopyment folder will give you an deployment error like this:

The deployment error is:
[HTTP:101216]Servlet: "DiceServicePort"
failed to preload on startup in Web application:
javax.servlet.ServletException: Servlet class:
'soastation.jaxwsdice.Dice' does not implement

Tell JwscTask the type
Not only is an ant script required to invoke but when using it with JAX-WS web services you must set the type attribute. The guidelines in the WLS documentation states that the ant tasks need to have a type=”JAXWS” attribute set. Without this, WLS will treat the web service as a JAX-RPC service.

To deploy JAX-WS web services on WebLogic Server v10 use JwscTask, with type=”JASWS”, in an ant script. Of course, if you are going to the effort of putting an ant script together to build the web application, it might as well have it deploy the web app too.