ORDS, RESTful Services, and $URI

thatjeffsmith ORDS 2 Comments

Tell Others About This Story:

Someone asked:

I see reference to a ‘$URI’ in an ORDS GET Handler example, can you explain what this is?

Yes. Or, I can with the help of some of our DOCS.

The appropriate section would be:

Columns in result sets whose first character is $ are given special treatment, they are assumed to denote columns that must be transformed into URIs, these are called Hyperlink Columns. Thus naming columns with a leading $ is a way to generate hyperlinks in resources. When a Hyperlink Column is encountered it’s value is prepended with the URI of the resource in which the column is being rendered, to produce a new URI.

Ok, so if we see a column with $ – it’s going to be a link.

And then, we take the value of the column and append it to the end of the current URI.

Let’s see this in practice.

/examples/uri/ is what we’re working with

And the code behind this GET handler is VERY simple:

I need to alias my value with “$something” – ORDS then knows to treat this as a URI

Save/publish the code – now I want to call it.

Note the query results via JSON include the URI as a link.

A practical example

Maybe I want to see a list of something, so I write a SELECT * FROM something. But, I also want to include a link to each item as part of the results.

Module: /examples/
URI Pattern: uri/
Code behind the GET:

 SELECT employee_id "$uri", rn, employee_id, first_name, Job_id, hire_date, manager_id, salary, department_id
  FROM (
       SELECT employees.*
            , ROW_NUMBER() OVER (ORDER BY employee_id) rn
         FROM employees
       ) tmp

So we’re querying the EMPLOYEE ID and aliasing it with “$uri”…and then includes the other elements of my employees.

So let’s run that.

So we have the employee record itself, and the link is listed afterwards, note the link is the existing URI with the employee ID tacked onto the end of it.

If I click on one of the links, e.g. “http://localhost:8888/ords/peeps/examples/uri/101” I get a 404.

/peeps/examples/uri/ — that definitely exists – I just wrote it 🙂

But, I need one to handle the links we’re returning.

So let’s build that.

Module: /examples/
URI Pattern: uri/{empid}
Code behind the GET:

SELECT employee_id, first_name, Job_id, hire_date, manager_id, salary, department_id
FROM employees
WHERE employee_id = :empid

So let’s publish our new URI Template and Handler, and then try to click on our link again.



You can call these anything you want. But, your code will need to know what to do with it.


Related Posts Plugin for WordPress, Blogger...
Tell Others About This Story:

Comments 2

  1. Hi,
    What seems to be missing here is how to generate links to other resources. The $ notation provides an easy way to handle the current resource, but one of the great things about HATEOAS is being able to follow the links between resources. Your example includes the metadata catalog link, but I don’t see any way to generate this kind of other resource link.
    I think you’ve done a great job with ORDS so far. Its probably the best thing in the web space since the OWA toolkit.

    1. thatjeffsmith Post

Leave a Reply

Your email address will not be published. Required fields are marked *