[OASIS Issue Tracker] Updated: (SRAMP-42) Support pagination and ordering of query results

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

     [ http://tools.oasis-open.org/issues/browse/SRAMP-42?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Eric Wittmann updated SRAMP-42:
-------------------------------

       Proposal: https://www.oasis-open.org/apps/org/workgroup/s-ramp/download.php/46886/SRAMPTCIssueProposal42.html
    Description: 
The S-RAMP specification does not include a mechanism to allow ordering and paging of results when performing a query (both ad-hoc and stored).  A user interface that allows users to browse/filter the artifacts in the s-ramp repository will need a way to order the artifacts and page through the results.


  was:
Problem
-------
The S-RAMP specification does not include a mechanism to allow ordering and paging of results when performing a query (both ad-hoc and stored).  A user interface that allows users to browse/filter the artifacts in the s-ramp repository will need a way to order the artifacts and page through the results.

Note: The atom binding document suggests that servers may provide paging of large result sets using the standard Atom first, prev, next, and last links. However, clients would always need to start at the beginning of the feed and page through, since there is no standard.


Proposal
--------
Update the S-RAMP specification to include order by and pagination features to the sections discussing the Query API.


Solution #1 (Summary)
-----------
Update the S-RAMP Atom binding document to include order-by and range parameters in the relevant sections (sections 3.2 and 3.3.1).  These parameters would be used to indicate the order and pagination information to be used by the server when returning the Atom feed.


Solution #2 (Summary)
-----------
Modify the s-ramp query grammar to include xquery-like ordering and custom range features.


Solution #1 (Detail)
-----------
Section 3.2 (Inline Queries) describes how ad hoc queries can be executed in s-ramp.  The following are the paramaters that can be sent whether performing a GET or POST:

 * query (required, single) - contains the s-ramp query
 * propertyName (optional, multiple) - value indicates an s-ramp property that should be returned in the Atom feed (by default, no s-ramp properties would be returned)
 * xmlns:* (optional, single/unique) - a way to map a prefix to an xml namespace for use in the included xpath query

I propose we include the following additional parameters:

 * page (optional, default 0) - indicates which page of the feed to retrieve
 * pageSize (optional, default 20) - indicates the size of each page in the feed
 * orderBy (optional, default 'uuid') - indicates an s-ramp property (base or custom) to use for ordering
 * ascending (optional, default true) - indicates the order direction (true for ascending, false for descending)

Additionally, the same parameters above should be added to section 3.3 (Stored Queries), specifically when discussing the results link.

The advantage of this approach is that it's easy to implement, explicit, and only requires a change to the Atom binding document.  This is also very consistent with the Atom pagination approach, which specifies first, prev, next, and last links.


Solution #2 (Detail)
-----------
Update the S-RAMP query grammar to include optional order by and range sections.  In this case, the paging and order by information is included directly on the query itself.  For example:

/s-ramp/xsd/XsdDocument[@version = '1.0'] order by @name range(10,20)

This would indicate that the server should order the artifacts by name and return records 10 through 20 (inclusive).  The grammar changes would be something like:

s-ramp query ::= artifact-selection
              | artifact-selection 'order' 'by' order-by
              | artifact-selection 'order' 'by' order-by range-spec

artifact-selection ::= artifact-set
                    | artifact-set '[' predicate ']'
                    | artifact-set '[' predicate ']' '/' subartifact-set

order-by ::= '@' <PropertyQName>

range-spec ::= 'range' '(' Number ',' Number ')'

The advantage of this approach is that only the foundation document needs to change.  Also, the change works for both ad-hoc and stored queries. However, specifying the range in the query may make it less appealing to bind to APIs that do not need pagination.  Additionally, pagination in Atom becomes more complex, as the query itself needs to change from page to page.



PS:  we could obviously also implement a hybrid - params for paging and grammar changes for order-by.


> Support pagination and ordering of query results
> ------------------------------------------------
>
>                 Key: SRAMP-42
>                 URL: http://tools.oasis-open.org/issues/browse/SRAMP-42
>             Project: OASIS SOA Repository Artifact Model and Protocol (S-RAMP) TC
>          Issue Type: Improvement
>          Components: Atom Binding
>    Affects Versions: 1.0
>            Reporter: Randall Hauch
>            Assignee: Eric Wittmann
>             Fix For: 1.0
>
>
> The S-RAMP specification does not include a mechanism to allow ordering and paging of results when performing a query (both ad-hoc and stored).  A user interface that allows users to browse/filter the artifacts in the s-ramp repository will need a way to order the artifacts and page through the results.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira