An example of client interaction using the GridRM XML-over-HTTP (XOH) API

Overview

The GridRMPortal SQL query interface can be used by users to navigate through the information provided by GridRM gateways. We will use the query interface as an example of how to retrieve CPU load from a given machine located at a remote gateway. As well as showing the steps that a user would take whilst using the interface, we will also show the URLs that a developer wishing to replicate the behaviour in their own customised client would need to know. Clearly, the SQL interface provides little high-level functionality, however, given the examples on this page, more complex clients can be created. For example, the GridRMPortal form interface uses the same API as used by the SQL interface, but provides higher-level features for data aggregation and presentation. Screenshots of the SQL and form interfaces are shown in figures 1 and 2, respectively.

Figure 1

Figure 2

Figures 3 and 4 show example output from the SQL and form interfaces respectively.

Image not rendered!

Figure 3: Results from a query to the SQL interface

Figure 4: Results from a query to the form interface

Creating a client

The following sections provide an example of how a developer creating a client, might interact with GridRM. This example focuses on interaction using XML-over-HTTP (XOH) and does not consider the use of jGMA. Furthermore, only anonymous requests are considered. Use of GridRM security mechanisms will be documented at a later time.

In summary, the following sections detail:

  1. How to retrieve a list of available GridRM gateways,
  2. How to connect to a gateway and issue a query,
  3. The types of queries possible,
  4. The use of cache parameters, within query strings.

Retrieve a list of available GridRM gateways

Figure 5 shows what happens when a user wishes to retrieve the list of gateways that are available to him (or her!). The syntax used in the SQL interface is: 
show gateways

Figure 5

One way to achieve the same effect using the XOH API, is for your client to connect to http://gridrm.org/gateways.xml (example .txt file here) and parse the resulting XML into a Document Object Model (DOM). Navigating the DOM will result in the client being able to obtain the URL(s) for a specified gateway(s). The bold text in the following block of XML, indicates the element and attribute that should be parsed. 

<gatewayRegistry>
    <gateway name ="DSG Workgroup Gateway" hostname="homer.dsg.port.ac.uk" ipaddress="148.197.155.23"
    url="http://148.197.155.23:8888/gridRMGateway/gw">
    <status code="operational" comment="Gateway is available."/>
    <location office="9.03" building="Mercantile House" place="Portsmouth" county="Hampshire" country="England"
    continent="Europe" lat="50:47:41N (50.7948)" long="1:05:44W (-1.0956)">
    <maps>
    <map id="global-map" long="514" lat="259"/>
    <map id="uk-map" long="393" lat="437"/>
    </maps>
    </location>
    <organisation name="The Distributed Systems Group, University of Portsmouth"
    logo="http://dsg.port.ac.uk/rjb/misc/logo/dsg/dsg_badge_white.png" />
    <admin name="Garry Smith" email="garry.smith@computer.org"/>
    <virtualOrganisations>
    <vo name="DSG"/>
    </virtualOrganisations>
    </gateway>
    .
    .
    .
    
    </gatewayRegistry>

Connect to a gateway and issue a query

We refer to the gateway URL (the previous bold text) as the gateway's base address. For example the base address for the DSG Workgroup Gateway is http://148.197.155.23:8888/gridRMGateway/gw. When constructing URLs for use with the XOH API ensure that the gateway base address is seperated from the rest of the API command like so:

<base address>/<gateway command>

For example to execute the SQL statement 'SHOW DATABASES' against the DSG gateway, the URL must be formed as:

http://148.197.155.23:8888/gridRMGateway/gw/queryDataSource?id=holly.dsg.port.ac.uk&query=SHOW%20DATABASES

An example of the XML that is produced in response is shown in the following code section:

Todo: Provide an example of the XML output.

The effect of this query is the same as using the SQL interface to i. select the DSG gateway, ii. select the holly.dsg.port.ac.uk resource (In the SQL query interface, the user would previously have entered the show datasources command to get a list of available resources), iii. select the holly.dsg.port.ac.uk resource (using the use datasource holly.dsg.port.ac.uk command), and finally issue the show databases command. Figure 6 provides an example of the steps that would have taken place in the SQL interface.

Figure 6: Using the SQL query interface to query a resource for the type of data it can provide

Types of Query

To list the resources provided by a gateway use the following command:



http://148.197.155.23:8888/gridRMGateway/gw/listDataSources

To execute a SQL query against a single resource at a gateway use the queryDataSource command. The id attribute is used to specify a resource previously discovered using the listDataSources command. For example: 

http://148.197.155.23:8888/gridRMGateway/gw/queryDataSource?id=holly.dsg.port.ac.uk&query=SHOW%20DATABASES
http://148.197.155.23:8888/gridRMGateway/gw/queryDataSource?id=holly.dsg.port.ac.uk/GLUECE_host&query=SELECT%20FROM%20Architecture
To query multiple named resources at a gateway use the following form of the command: 
http://148.197.155.23:8888/gridRMGateway/gw/queryDataSources?ids=holly.dsg.port.ac.uk;homer.dsg.port.ac.uk&db=GLUECE_host&query=SELECT%20FROM%20OperatingSystem
Note: The preceding command should not contain whitespace. For the queryDataSources command a list of resource names are specified using the ids attribute. A semicolon seperates each resource name. The db attribute is used to denote the naming schema (conceptually equivalent to a database) to use when querying multiple resources.

SQL Commands

A selection of SQL commands that can be used with the XOH API are shown in Table 1.

SQL Command Description
show datasources List all resources registered with the gateway.
show databases Retrieve a list of naming schemas supported by the selected data source driver. These are analagous to the databases one would connect to when interacting with a regular DBMS. This command will fail if a resource name is not specified in the URL.
show tables List the tables provided by the selected database. This command reveals how the speficied naming sc hema/database partitions resource data. A naming schema must be included in the URL.
desc <table name> Describe the named table. Field names, datatypes and naming schema descriptions are given.
select <[*] || [fieldname][fieldname*]> from <table name> Display data from the specified table. The wildcard '*' displays all fields. Alternatively each field name to be viewed should be given.

Table 1: SQL commands

When composing a URL to execute a SQL command, the query attribute must be used. For example:

http://148.197.155.23:8888/gridRMGateway/gw/queryDataSource?id=holly.dsg.port.ac.uk&query=SHOW%20DATABASES
NOTE: You must ensure that any spaces in the SQL command are replaced with %20 in the URL.

Cache parameters

Cache parameters can be incorporated into commands using the cacheTTL parameter. CacheTTL values can be:

less than 0 : Caching turned off for the client's request,

equal to 0 : Use cache but no specified TTL (use whatever data is in the cache),

greater than 0 : Use cache, but only get freshest data within the specified TTL.

For example: 

http://148.197.155.23:8888/gridRMGateway/gw/queryDataSources?ids=homer.dsg.port.ac.uk;holly.dsg.port.ac.uk&db=GLUECE_host&SELECT%20FROM%20OperatingSystem&cacheTTL=0

For certain commands, the inclusion of the cacheTTL makes little sense, and for those commands, the cacheTTL parameter will be silently ignored.