The Hitchhiker’s Guide to interfacing with Registry Services – Part 2: Queries

Body

In part 1 of this entry, I outlined the concepts and steps required to get data inside Registry Services. I also revealed Registry Services’ party trick, which lies in its ability to recognize seemingly disjoint information from different sources as representing the same entity in the outside world.

It has been enough days to let you build that first application, at which point you must be wondering “How do I read that collection of reconciled resource records? Where do I start?”

Collections, collections, collections…

1. Sorry about the riff on the real state rule, but it is all about collections. There is a collection for service providers, a collection for registration records, a collection for resource records, a collection for resource shapes, you get the idea…actually you get the whole picture as these are the four collections of data in Registry Services.
    
2. Uniform Resource Location, Location, Location.
   
   I know, people can be badly hurt for paraphrasing a real state rule twice within the same article. That is the kind of realization that makes me appreciate the remoteness of online writing. Some may even point out I should have used URI instead of URL, but it would ruin the pun in ways that only a proper discussion about URIs versus URLs could.
   
   Each of the Registry Services collections exists behind a public URI, so all you need to get started are the URIs for these collections. The URIs can be retrieved by accessing the “Link” header in the response to an HTTP HEAD request to the Registry Services base URI, as described in the InfoCenter page titled "Locating Resource Registry access points" .
    
3. URI trade ups. This is not a formal term, don’t bother to look it up, but in the RDF world you usually have one URI in hands to start your queries. You then query that URI to fetch the underlying RDF content, inspect those contents using your knowledge of its RDF types and properties, find other URIs, then repeat that cycle until you find exactly the information you need.
   
   The flow is identical to randomly browsing the web, except that you click the URIs on a screen until your find information about cute cats, which is exactly the information you do not need.
   
   What you do need is the answer to your next question.
    

…which collection do I want?
 

1. If you are planning to implement one of those awesome integration scenarios seen at Pulse 2013, where people start to navigate resources from your own UI, then are shown the details about the resource coming from another application, you want to start with the Resource Record collection.
   
   You can query the Resource Record collection for the record associated with the item clicked in your own application. If you remember from the previous entry, Resource Records are created from the reconciled view of Registration Records from different sources, and as such, they contain URIs pointing at those Registration Records.
   
   With those URIs in hand, it is a simple matter of issuing a last round of HTTP GET requests to retrieve their content from the original application. You may decide to try and render the data yourself or may also be very interested in the OSLC UI Preview specification (http://open-services.net/bin/view/Main/OslcCoreUiPreview) . Rendering the data yourself is likely to yield a more cohesive user interface, but it will also exact a penalty in your ability to visually integrate data from other service providers outside your control.
    
2. If you are on the absolute bleeding edge of loosely coupled integration, such as trying to locate a completely unknown Service Provider that could handle a query for a certain type of resource, you will start with the Service Provider collection.
   
   You can query the Service Provider collection with a filter, indicating the OSLC domain for the service provider and the type of resource you are trying to query. An OSLC domain is something like “Performance Management” or “Asset Management”. The complete list of OSLC domains can be found in the OSLC specifications page (http://open-services.net/specifications/) .
   
   As one example, you could query all service providers that are in the Performance Management domain (http://open-services.net/ns/perfmon#) and also have a query capability that can handle Computer Systems (http://open-services.net/ns/crtv#ComputerSystem) . Keep on reading for a concrete example of that query.
   Note: You could also create a proprietary domain for your own development, but there are several OSLC standard experts who would love to get involved and remind you about the power of loosely coupled integration stemming from people knowing what each other is doing (see, it is this kind of plug that keeps their anger at bay over my ruffian simplifications in this two-part article) .
   
    

My application can’t handle that much data at once…

1. First of all, congratulations, at this point you have a working client application, maybe based on the sample applications shipped with Registry Services, maybe based on one of the samples in the Registry Services wiki, or maybe even based on my previous posting “Iterating through response pages queried from Registry Services using Java”.
   
   If your applications is receiving too much data, in all likelihood you issued your HTTP GET request against a collection, because no individual record has to be large enough to crash an application. As Ford Prefect once said: “Even if you prove it to me, I won’t believe you.”
   
   Now that we established beyond doubt that you are querying a collection, you have three mechanisms to limit the amount of data retrieved by your application: filtering, pagination, and content selection.
   
   Filtering limits the number of resources returned in a query, and are specified with an oslc.where parameters in the query URI. Filtering works on all but Resource Shape collections in the current Registry Services implementation.
   
   Pagination chunks responses in pages and returns each page with a pointer to the next page. Pagination is controlled through the oslc.paging and oslc.pageSize parameters in the query URI. Right now, pagination is only supported for the Registration Record and Resource Record collections.
   
   Content selection is a way to instruct the server about how much of a given resource should be retrieved during a query, and it is done through the oslc.select parameter in the query URI. The OSLC query specification allows for a wide range of selections, but Registry Services implements only a subset: whether you want the entire record data or just the URIs.
    

… can I see some examples?
 

1. Yes, right after you bookmark the official reference in the Jazz for Service Management InfoCenter, in the topic titled ”Registry Services queries”.
    
2. There is an extremely helpful support page authored by my colleagues Fabiana Rocha and Joe Ross (the latter of which, incidentally, is the architect for Registry Services) at /support/pages/node/487745. You could search for “Useful Registry Services Queries” in there to skip directly to the queries, but you would also be missing the best explanation about reconciliation this side of a brain transplant from one of them (and for that you would be behind me in a city block-long line anyway) .
    
3. For Web developers, stay tuned, as I am authoring another round of entries with examples using Javascript that will showcase all aspects covered in this series.

---

This is the last part of a very short series, which is also as far as I can abuse references to HHGTTG before Mr. Adam’s relatives come collect their royalties. 

Before you ask “Would it save you a lot of time if I just gave up and went mad now?” (and that was my last HHGTTG reference) , we are here to answer whatever questions you may have, either as a comment to a blog entry or as a new thread in the Registry Services forum.

We still would love to learn more about what you may be building around Registry Services and also about other topics you would like to see covered in this space.