FYI: This was all done on a MacBook, so...this may differ on a PC or Linux machine. Apologies m'Lord...
UPDATE: Here are some helpful references for Windows/PC and macOS/Linux, too!
Since I’ve written this article, I’ve done some more digging. Some version of this will go into our documentation. I’m just not sure how much! But here are some of my findings:
“…searching for an ORDS and JVM Process ID.” Can be done with:
Here are the options I’ve found to “kill” an ORDS process:
Use the kill command followed by the ORDS PID (i.e., Process ID) and the related JVM (i.e., Java Virtual Machine) PID
Press the Control + C keys in the same terminal session that ORDS is running in (assuming it remains uninterrupted)
It looks like we’ve included in our docs how to start ORDS (with the ords serve command), but we leave it up to you to figure out how to close down/kill/terminate an ORDS process.
FYI: As I'm writing this PSA, I'm also filing a ticket to update our docs too 🤓!
Some observations
First approach
The Control + C key option is the simplest option. But this might be the most impractical. If you start ORDS in Standalone mode (using the embedded Jetty server), then you might have ORDS running in its own terminal tab, kind of like this:
Oh…my second ORDS pool is invalid because I need to switch out the Cloud Wallet…not related to this article, though 😬
Assuming this is the case, while ORDS is running in a separate tab, you can issue the ps command to review a list of the running processes:
Afterward, you can return to where ORDS is running and press and hold the Control key followed by the C key. You’ll see a new shell prompt appear:
There isn’t any real feedback (maybe we should change that). But if you issue the ps If you run the command in a new tab, you’ll see that both the ORDS and Java processes have been “killed.” This signifies that ORDS and the JVM are dead—RIP 🪦.
Second approach
If you exit out of a terminal session but ORDS is still running (which, in practice, is entirely possible), you’ll have to search for the appropriate PIDs. The easiest way I’ve found is to issue the ps command (like you saw before) and then issue the kill command plus the relevant PIDs.
I’m unsure if you need to “kill” the Java process and ORDS. I assume that you do. The only basis I have for this assumption is that when you use the first approach (see above), both the JVM and ORDS are killed. So, I’m attempting to mimic what automatically happens when using the Control + C option.
Issuing the kill command results in the following message (which you’ll see, assuming the original ORDS terminal window is still viewable):
And if you reissue the ps command, you’ll see both the ORDS and JVM PIDs have disappeared:
Summary
Since I’ve only tested this in ORDS Standalone mode, I can’t comment on Apache Tomcat or Weblogic. I’m assuming they both function very similarly. But if you are using ORDS as both an admin (to get it up and running) and a developer, then some of these commands (that we take for granted) may not be obvious to you. So, as rudimentary and fundamental as this article appears, I hope it helps at least one person early on in their database or ORDS journey.
Call to Action
And if you haven’t seen it by now (and why should you? I haven’t plugged it yet), we’ve made a YouTube playlist to accompany one of our more popular ORDS LiveLabs. You can find the LiveLab here.
And here’s the complete playlist:
Enjoy 🤗
That’s all for now, folks!
Follow
And don’t forget to follow, like, subscribe, share, taunt, troll, or stalk me!
In response to various support requests and internal feedback, we've expanded on the existing ORDS Status Codes (the current list can be found here)!
Why? The TL;DR is that in many cases, the error or exception caught was being "bucketed" into a category of codes, like a 400 Bad Request or a 500 Internal Service Error. While true, we can be more explicit with some of these error codes. Now, we just have to ask, at what level do we stop?!
Ahem, this sounds like our entire dev team is lazy; it’s quite the opposite. Let me illustrate what’s actually going on with an example from one of our related tickets.
Say a user receives a 503 Service Unavailable server error response. In their Java logs (trace files, access logs, etc.), they also observe an oracle.net.ns.NetException error. While classifying this as a 503 is accurate, we can do better. For instance, you may encounter an oracle.net.ns.NetException with any of the following ORA codes:
In this example, moving forward, instead of receiving a 503, you’ll now receive a 571 server error response.
We’ve done this for several other scenarios, too! Why keep everything generic, as a 503, when we can be more discrete and specific with the information provided? It makes no sense. So, by shifting some of these exceptions to unique response codes, we make it easier for you to identify what is happening.
What if everything was either 200, 400, or 500? Could you imagine?! It would be nearly impossible to quickly identify what is happening in your stack.
ORDS Central Configuration
ORDS now supports deployment in a Central Configuration type deployment.
This one is big. The short version is that we’ve made it so you can dynamically start up and shut down individual ORDS “nodes.” This requires three main pieces, but I’ll try to be brief.
This all assumes you’ve already configured ORDS globally (i.e., you have a global.xml file) as well as your database pools (i.e., the default.xml, database_pool_one.xml, database_pool_two.xml, etc. files). But the idea is such that you’ll have stored in a central Vault/Secrets storage/Key Store your:
ORDS global configuration – which will be in a JSON format (basically a JSON version of the global.xml file)
ORDS database pool configuration/s – the individual configuration files for your ORDS “nodes” (again, just JSON versions of your database-pool.xml files)
A mechanism for the ORDS_PUBLIC_USER to authenticate with the Vault or Keystore (this could also be something as simple as an ORDS webhook that has been protected with an OAuth2.0 client)
*And a conditional fourth item, the makestore or orapki utilities (for creating SSO Wallets).
One way to “do” this (we’ve tested this internally; we just can’t, and won’t endorse, a “one-size fits all” method) is to store your “secrets” in a vault-type service and retrieve them securely and dynamically.
NOTE: The vault contains "secrets," including your global configuration and database pool files. Each of those secrets might be behind an OAuth 2.0-protected endpoint/s.
Separately, and before starting up ORDS, you’d create an SSO Wallet with the credentials for the ORDS_PUBLIC_USER, its password, and additional hostname information (all can be found in our documentation). You’d also choose where to store that Wallet.
Then, before launching ORDS, you’d include two Java options:
Your wallet location (so when ORDS starts up, it is aware of the location of the Wallet and the credentials) and
The REST endpoint (the URI) for your global configuration
Authentication can take several forms here. You can use Basic Authentication (but…don’t, even though we support it, perhaps for testing, but please don’t use it for production), JWTs, or OAuth 2.0. Once the ORDS_PUBLIC_USER has authenticated with its credentials/token, ORDS can acquire its global configuration.
When that HTTP request comes across ORDS, the database pool name can be passed as a header value (we can also read the database pool name if it is appended to the beginning of the URL) and used as a “search” value to retrieve the relevant database_pool-config.json file.
That is ORDS Central Configuration in a nutshell. And since I lost you, I’ll have to write a follow-up blog on this. I don’t blame you; conceptually, it’s tough to envision, but it’s pretty simple in practice. The basic components are laid out in our documents.
OCI Monitoring of ORDS
ORDS now provides a create_alarms.sh script to create ORDS alarms using OCI Monitoring Services, which can be found in the [ords product folder]/examples/ords-metrics directory.
How shall I explain this without getting in trouble with our legal department…? This is being rolled out globally right now for the Oracle Autonomous database. Before this ORDS release, errors or exceptions would be caught and streamed to an OCI metrics dashboard. And you might have seen an ORDS-related exception with a 404 or a 503. Unfortunately, the root-cause analysis would have already been off to a bad start. Because most of these exceptions aren’t just 404s or 503s. There had yet to be a mechanism to make some of these exceptions more discrete. And that is where this create_alarms.sh script enters the chat.
If you review the now-included create_alarms.sh file, you can get an idea of what will now be streamed to your OCI Metrics/Monitoring Explorer. We’ve made it so the ORDS access logs and more appropriate response codes can be streamed to OCI. This makes root-cause analysis and troubleshooting far more straightforward. So if you elect to configure a customer-managed ORDS node, then be sure to take advantage of this new capability.
A new standalone configuration option
New standalone.access.log.retainDays configuration option for ORDS standalone.
Users can now customize the number of days before access log files are overwritten. The default is 90 days, but you can now select the exact number. This, along with numerous other standalone settings can be found in the Understanding Configurable Settings appendix of our ORDS Installation and Configuration Guide.
Java options in the ORDS CLI
Users may now include Java Options parameters when executing ORDS CLI commands.
For instance, a user may execute the following command:
In the above example, you’ve told ORDS to start up, and then, first thing, go to the target URL to retrieve ORDS’ global configuration settings.
You may wonder about JAVA_OPTIONS and JDK_JAVA_OPTIONS; how are those settings impacted? Well, here are some essential details:
ords --java-options only apply to the current ORDS execution.
In order of precedence, options will be picked up like this:
JAVA_OPTIONS are of the highest precedence >>> then >>> ords --java-options >>> then >>> JDK_JAVA_OPTIONS
INFO: Where conflicts arise, ORDS will pick up and use the left-most option.
Jetty 10.0.21
ORDS standalone updates the embedded Jetty Web Sever version 10.0.21.
There’s not much to say here, but if you’d like to learn more about Jetty, I’m including the Operations and Programming guides. When using ORDS in standalone mode, the idea is that Jetty is just there—and it just works.
We’ve architected Standalone mode so that any ORDS configuration can be achieved via the ORDS CLI or by directly manipulating the XML configuration files (while you can do this, you shouldn’t; you might mess up one of the properties in the files). Designing ORDS Standalone mode this way makes it so you don’t really need to do anything Jetty-related. I’m just including the docs if you want something to read on your lunch break 🤪.
Database Actions’ Data Pump
Data Pump allows you to delete jobs and their files from within the Database Actions Data Pump UI. And the Data Pump Import Wizard features some major upgrades and visual enhancements.
Users who have DBMS credentials to access Oracle Cloud Services (via the DBMS_CLOUD.CREATE_CREDENTIAL PL/SQL procedure) can now perform Data Pump Imports from OCI Buckets (previously, it was Resource Principals only). And we’ve added the following abilities/changes:
Buckets from any Compartment level are now accessible
Auto-generated Import Patterns for DMP Files are now included
Automatic mapping for Schemas and Tablespaces is now present
A new “Append Timestamp to Log and Job Names” toggle option has been added
NDJSON files
Users can now import Newline Delimited JSON (NDJSON) or .ndjson files into the SQL Worksheet.
This actually arose from a bug we encountered. After some investigation, the user attempted to import a “Newline Delimited” JSON document. I’m not familiar with this document type, but cursory research reveals the following:
There is currently no standard for transporting instances of JSON text within a stream protocol apart from [Websockets], which is unnecessarily complex for non-browser applications.
A common use case for NDJSON is delivering multiple instances of JSON text through streaming protocols like TCP or UNIX Pipes. It can also store semi-structured data.
If you’d like to learn more about this specification, I recommend visiting this site. It doesn’t seem affiliated with the project, but it is very informative compared to the official NDJSON GitHub page.
Are you using NDJSON now? Or did you just learn of its existence? Do you think you’d start using it, or do you have any use for it? Let me know. I’m curious about the potential applications.
New Walkthroughs (Tours) for Charts and Data Modeler
Updates to the Database Actions Launchpad.
We continue to refine the Launchpad, and these are but two more examples. The Data Modeler and Charts pages have Walkthrough Tours (and documentation too):
What are your thoughts on the new Launchpad? Do you use the “pin” feature? Is it intuitive? What else could we include or improve? Or is it perfect (it’s perfect, isn’t it? …I knew it!)
Java
ORDS requires Oracle Java or Oracle GraalVM Enterprise Edition 11, 17, or 21 to run ORDS 24.2.
If you intend to do anything GraphQL-related, use GraalVM 17. Instructions for downloading can be found here. Just make sure you set your JAVA_HOME to GraalVM 17 so that when ORDS starts up, it does so with GraalVM 17! At this time, ORDS GraphQL support only works with GraalVM 17.
I’m kidding, there’s more. But if you don’t feel like reading anymore, bookmark this post and return when you’re ready.
Assuming you have ORDS installed, you too can execute the ords config list --include-defaults command to reveal almost all the configuration settings for your ORDS installation.
Here is what my configuration looks like:
Executing the ords config list --include-defaults command.
Configuration settings: what am I seeing?
This command is a quick way to see all the settings from your .XML configuration files (i.e., the settings.xml and pool.xml files), including other settings automatically configured for you when you first ran the ords interactive installer.
In short: All your default settings and any that you may have added or changed are on one screen.
Read on to explore further…
Version, config folder location, and pool information
I've broken the configuration settings into sections. Anywhere you see red arrows, are just areas of intrigue (personally); however THIS LIST IS NOT EXHAUSTIVE.
I use this first section as an easy, convenient way to determine the ORDS version I’m running. Additionally, you can verify the location of your configuration folder (in case you forget). You can also verify the database pool (default is the default name for the pool unless you modify the name) you are using.
ORDS version, configuration folder location, and database pool information.
If you want to learn more about the ORDS pools, visit this link and this link.
💡I only have single install, that is why I see default as the default database pool.
Pool and global settings
Not much here that you probably already don’t know. However, in the future I will look at the features associated with the database.api.management.services.disabled = false property (also, I think the way this is written is a referred to as a “logical negation”, and it hurts my brain to read).
General ORDS settings.
Read more about this service here. But in short (and once you’ve created the requisite user), you can explore various services such as:
DBCA Jobs, available methods: DELETE, GET and POST
DBCA Templates GET
Oracle Home Environment GET
PDB Lifecycle DELETE, GET, POST
Open Service Broker DELETE, GET, and PUT
Debug and Error
My settings are false (these are the default settings). But if I were to, for instance, set debug.printDebugToScreen = true, I would then be able to see any error messages in the browser.
ORDS debug and error settings.
I can change the responseFormat to always display as JSON, HTML, or AUTO (i.e., Automatically determine the most appropriate format).
ℹ️ Note: Must explore this further and report back after I've sufficiently tinkered.
Did you know you can create custom HTTP error pages in ORDS? These two error.properties appear to be associated in some way. So if you were two create custom error pages, you’d probably need to consider the format as well. Nonetheless, could you imagine the fun you could have coming up with something totally unique to your application?
I'm definitely adding this to my "Productive Procrastination" list 🤣!
GraphQL and SQL Developer Web
ORDS supports GraphQL now; did you know?! I just set up my local installation (it wasn’t too bad once I figured out how to properly set my Java to GraalVM 😑), so I can start learning GraphQL queries.
GraphQL and ORDS settings.
Did you know ORDS ships with the GraphiQL IDE now? Learn how to set it up here.
Cookies and ICAP
I honestly wouldn’t have known ORDS could offload virus scanning to ICAP (Internet Content Adaptation Protocol) servers unless I looked at what was actually in the configuration settings. I’m not sure if I’ll configure this anytime soon, but maybe you will.
Want to bore yourself? Read more about ICAP in this RFC 3507 memo.
Java Database Connectivity (JDBC)
I am NOT going to spend much time here. I still need toggle these parameters and experiment more. However, I will point out that the default setting for maximum JDBC connections is 20 (jdbc.MaxLimit setting).
Java Database Connectivity and ORDS settings.
jdbc.MaxLimit=20 is probably too low for a production environment. I’ve left it as-is because it’s just me, and I’m doing everything locally in my Podman container.
Suppose you need to familiarize yourself with JDBC or Universal Connection Pools (UCPs)? In that case, we should both read the introduction sections of the following guides:
I have spent little time with MongoDB, but from what I understand, the Oracle Database API for MongoDB translates the MongoDB wire protocol into SQL statements executed by the Oracle.
ORDS and the MongoDB API settings.
What I’m inferring from our docs is that once you’ve migrated your data from a MongoDB into a supported Oracle database, you (or your application) can keep talking “MongoDB speak,” and at least in this case, ORDS will be able to interpret this Mongospeak and query the database on your behalf 🤯!
If this describes you or your use-case, you’re in luck; I found some excellent resources!
You’ll notice, no red arrows here. I have yet to spend much time with this section. However, I want to draw your attention to the security.jwks.[etc...] and security.jwt.[etc...] properties.
ORDS security settings.
In ORDS 23.3, we introduced JSON Web Tokens (JWTs) support, so these properties very much concern that new functionality.
In short, we've allowed you to incorporate JWT authentication provided through third parties into your APIs.
The nice thing about ORDS is that you can use the embedded Jetty server as a local web server for testing. This section shows most of the essential settings for running Jetty in “Standalone mode.”
ORDS standalone Jetty Server settings.
I use the term “testing” because our docs state, “the default configuration of Jetty is optimized for the most common ORDS use cases.”I interpret this as, “This is designed to expose you to Jetty (and make it easy to get you up and running), but you’ll probably need to adjust this according to your own requirements.”
The only things I want to point out here are the standalone.doc.root and standalone.static.context.path properties. These settings will look familiar if you’ve ever performed an APEX installation (available here, for free, BTW).
However, if you want to deploy custom HTML, CSS, and image files, you can configure this for ORDS. We have an overview in our docs here.
I think I've just stumbled upon another fun Friday afternoon project 😍!
Okay, that’s it for now. Thank you for choosing to waste your time with me.
What’s the point of this post?
There was no point to this post. I’m constantly wasting time researching technology and techniques I don’t need to know. However, in this case, I’ve hopefully:
left you with at least one helpful ORDS command-line command (ords config list --include-defaults), and
provided you with some helpful explanations and resources on what is contained in your ORDS installation (again, this list is NOTexhaustive)
And if you found this post helpful, please share it!
Follow
And don’t forget to follow, like, subscribe, share, taunt, troll, or stalk me!
What is new in Oracle REST Data Services 24.2?
