6.2. Client Management Registry Client

Introduction

This tutorial shows how to use the Client Management Registry Client.

Creating a Registry Resource

Before you can register services and other resources to the CltMgtRS, you have to create a concrete Registry Resource, in short a Registry, which is an instance of the CltMgtRS.

1. Adding the registry service is done in the same way as adding the other services. See Adding Services.
2. Click right on the registry service to open a popup menu and create a new registry resource by clicking the ‘Create new registry’ menu button:

Adding a Resource to a Registry

Resources (EPRs) can be registered with a concrete Registry using drag-and-drop on the service tree or by using the Registration interface at the ‘Resources’ tab

1. Click on the Registry Resource in the client.
2. Click on the 'Resources' tab on the panel on the left.
3. Click on the 'Load Resources' button to load the current resources into the table.
4. Click on the 'Add Resource' button and choose a resource to put in the registry.

The user of the registry is able to register EPRs of resources. However in order to make the concepts and relationships of the RDM usable, different strategies are implemented to extract additional knowledge from or related to the EPR. For instance, adding a concrete job results in adding the metadata of the application, the parent job service with its WSDL document, as well as the resources managing this job service.

N.B. when registering job resources created at a 5.0.1 Job Service, the 'applicationuri' meta information is not part of the job's EPR, therefore querying for jobs supporting a specific application like "paint" will not work correctly. This is true for all example queries containing the concept 'Application'.

After adding the resource should appear in the table, however, if you press ‘Load Resources’ again, you should also see resources that are inserted behind the scene.

Setting up the Registry for the following tutorial

In order to follow the tutorial used in this guide you have to setup the client as follows:

1. Add a Data Service and a Job Service to the list of services. These services should be managed by an SLA Service and a corresponding Trade Account Service.
2. Add the SLA Service and the Trade Account Service to the list of services. Propose an SLA.
3. Create a Registry resource.
4. Create a data stager and a job.
5. Register the data stager, the job and the proposed SLA with the Registry.

The resulting list of services should look like this:

Discovering Registered Resources

Discovery is the process of finding entities previously registered. The ‘Resources’ tab provides a simple discovery mechanism that loads all registered resources into the client. The ‘Discovery’ tab provides more sophisticated discovery possibilities using ooXmlQL queries.

In the top of the Discovery panel you have a menu that provides possibilities to load/save queries (‘File’ menu), to create new queries using a Query Wizard (‘Wizard’ menu) and to create queries based on predefined examples (‘Examples’ menu).

Note: If you execute some examples by submitting the query without setting up the registry for the examples, it might happen that they produce an error, due to missing concepts in the RDM. This is correct since some concepts are added dynamically to the RDM when concrete resources are registered, like the concept ‘Application’ or different sub concepts of the concept ‘Reference’.

In order to create your own queries, you can use the Query Wizard, explained in the next paragraph, modify provided examples or type in ooXmlQL queries directly into the corresponding text field. The ‘refresh view’ button allows you to recolor the XML-based ooXmlQL query, as well as it provides you with the information if the XML-based query is well-formed. It doesn’t check the syntax of the query at the moment.

After submitting the query to the registry resource (using ‘submit query’ button) the resulting resources are displayed in the resource view:

From here you can select discovered resources and add them to the list of services (using ‘add to services’ button). If any additional documents are discovered you can view them in an XML viewer (using ‘show additional documents’ button):

Using the Query Wizard

The Query Wizard supports the user in creating ooXmlQL queries without knowing the syntax of ooXmlQL at all. The only part of the query the user has to write down manually is the where clause, where the XPath or XQuery filter goes in. Users can open the wizard in selecting the ‘Wizard’ menu and pressing ‘Open Query Wizard…’.

Specifying the 'From' part of the query

The Query Wizard pops up with the ‘From’ part specification of the query. The ‘From’ part in ooXmlQL has the same function than ‘from’ in SQL statements. From is used to specify the concept or a set of concepts of interest.

First a requested concept and a variable for this concept have to be specified. This can be done by pressing the ‘select concept’ button. This button opens up a Concept Browser, where users can select the appropriate concept.

Note: the concepts shown in the Concept Browser are discovered dynamically from the registry service. Therefore the number of concepts can change when new concepts are generated during registration.

After specifying a concept the corresponding fields are filled in and a variable will be suggested, if not provided beforehand. From here, users can continue creating the query pressing the ‘next’ button or they can extend the ‘From’ part by adding set operations and other concepts to the ‘From’ part using the ‘+’ button, e.g.:

The registry provides three different types of set operations: union, intersect, except, which can be specified by the corresponding combo box before pressing the ‘+’ button. The ‘-‘ button allows to remove a concept from the specification.

After pressing the buttons ‘next’, ‘+’ or ‘-‘the user can see a preview of the resulting ooXmlQL on the right of the Query Wizard window.

Tutorial: The query we will define is, ‘find SLA and its managed service, where the usage of this SLA on the metric ‘disk space’ is not greater than 0.0 and the service contains the term ‘Job Service’ in its address’.

1. Open the Query Wizard.
2. Select concept ‘ReferenceSLA’ and add it to the set of concepts by pressing ‘+’.
3. Press ‘next’.

Specifying Joins

The next step in the Query Wizard after pressing the ‘next’ button is the definition of joins if this is required:

Joins provide the possibility to navigate in the RDM using defined relationships between concepts.

Note: depending on the specification of the ‘From’ part, e.g. when using set operations, it could happen that no relationships are available for building joins. For instance, the concept ‘Reference’ and the concept ‘Usage’ do not share any common relationship. Therefore combining them in the ‘From’ part will result in:

The specification of a join is as follows:

1. Select the relationship for navigation
   
   
   
2. Select sub concepts if required and specify a suitable variable for this concept
   
   
   
3. Add additional joins from the concept selected beforehand by pressing the ‘+’ button
   
   
   
4. It is further possible to specify restrictions on a join concept using the ‘set / edit sub query’ button. This opens a new dialog window for specification of the sub query.
   Note: currently specified sub query cannot be edited afterwards. Creating sub queries is explained in a latter paragraph.

The result should look like:

Tutorial:

1. Select relation ‘holdBy’ and select sub concept ‘Sla’. Add the variable name ‘$slaContent’. Press ‘+’. (Due to the ‘From’ part, we are only interested in ReferenceSLAs hold by SLAs.)
2. Select relation ‘hasParent’ and select sub concept ‘ManagerResource’. Add the variable name ‘$manager’. Press ‘+’. (An SLA is a child of a managing resource, a SLA Service.)
3. Select relation ‘manages’ and add variable name ‘$managed’. Press ‘+’. (What resources are managed by this service?)
4. Select relation ‘has’ and add variable name ‘$epr’. (What are the References of these managed resources?)
5. Press ‘next’.

Declaration of namespaces and variables

After pressing the ‘next’ button on the ‘Join’ view users are able to declare variables and namespaces. Namespaces are required in where clauses when documents that should be filtered use namespaces. In order to support the user several namespaces are predefined. Variables can be used for instance to support aggregate functions used within a where clause. The ‘+’ button allows to specify a new namespace or variable respectively. If the user ticks the check box in the ‘use’ column the corresponding namespace or variable will be included into the query.

Tutorial:

1. Select the namespaces ‘gria’, ‘addressing’ and ‘metric’. (Used in the where clause later on.)
2. Press ‘next’.

1.1.1. Specifying the where clause

Specifying the where clause in XPath or XQuery has to be done manually. Currently there is no support in fulfilling this task. In the where clause user can use all variables defined in the scope of the actual query, but not on variables defined in sub queries or the other way around. Variables that can be used include the variable used in the ‘From’ part, the variables of the ‘Join’ and the variables explicitly declared in the namespace and variable declaration step.

Additionally a sub query restriction can be defined on the concept of the ‘From’ part of the query, if the specification of the ‘From’ parts provides a common concept (see paragraph ‘Specifying Joins’). If not, the corresponding button is not selectable.

Tutorial:

1. Add where clause:
   

   fn:contains($epr//addressing:Address,"JobService")

2. Press ‘next’.

Selecting variables of the results

In a final step users are able to select the elements of the result using multiple selections on the variables. This can be done by holding Ctrl or Shift during selection. If no variable is selected, elements of the variable of ‘From’ part are automatically assumed as the result.

Tutorial:

1. Select variables ‘$referencesla’, ‘$slaContent’ and ‘$epr’.
2. Before we finish this tutorial, we want to define a restriction on the usage reports of the SLA. Press ‘back’ until you reach the view where the ‘Join’ is specified. If you go to ‘From’ part of the query, you have to start from the beginning.
3. Press ‘set / edit sub query’ at the relation ‘holdBy’ on concept ‘Sla’.

Specifying restrictions on (join and from) concepts

The ‘from’ concept as well as the ‘joins’ concepts can further restricted using sub queries. When pressing ‘set /edit sub query’ a new window pops up allows the specification of restrictions on the corresponding concept:

1. Select a relationship (‘return’) that provides the domain concept you want to restrict (left component in the brackets).
   
   
   
   
2. Select a sub concept if required.
3. Press ‘+’ button to add the restriction to the set of restrictions.
   
   
   
   This will open up a new Query Wizard dialog that allows specifying the sub query. The specification is done similar to the specification of the main query; beside there is no possibility to select variables for the result of the sub query.
4. After finishing the declaration of the sub query, the wizard will return to the restriction dialog. Here it is possible to define more sub queries and combine them using the Boolean expressions ‘and’ and ‘or’ as well as invert restrictions pressing the ‘not’ checkbox.
   
   
   
   
5. Press ‘finish’ to finish the restriction specification and return back to the parent query, e.g. the main query. Press ‘cancel’ to discard the whole restriction.

Tutorial:

1. Select return ‘isUsageOf’ and press ‘+’. (Restrict SLAs by usage information.)
2. In the new Query Wizard dialog, add variable ‘$usage’ in the ‘From’ part of the sub query.
3. Press ‘next’ until you reach the where clause specification.
4. Add the where clause:
   

   $usage//metric[@description="disk space"]//rate > 0.0

5. Press ‘finish’.
6. Select ‘not’ on ‘Usage’ return=’isUsageOf’. (Remark, in this example we could use ‘not’ directly within the where clause, like:
   

   not ($usage//metric[@description="disk space"]//rate > 0.0)

   However, ‘not’ in the interface allows you easily to invert whole Boolean expressions based on several sub queries.)
7. Press ‘finish’.
8. Press next until you reach the ‘Select’ view. (Otherwise the previous specifications of steps done beforehand are gone.)
9. Press ‘finish’.

Wizard result

After pressing the ‘finish’ button in the Query Wizard the resulting query will be inserted into the ooXmlQL query field. Here the user can finally do some modifications and save the query to the file system using the ‘File’ menu.

Tutorial:

The resulting query should look like:

<query>
  <select>$referencesla $slaContent $epr</select>
  <from as='$referencesla'>
    <class name='ReferenceSLA'/>
    <join on='holdBy' as='$slaContent' class='Sla'>
      <not>
        <query return='isUsageOf'>
          <from as='$usage'>
             <class name='Usage'/>
          </from>
          <where>
             $usage//metric[@description="disk space"]//rate > 0.0
          </where>
        </query>
      </not>
      <join on='hasParent' as='$manager' class='ManagerResource'>
        <join on='manages' as='$managed' class='ManagedResource'>
          <join on='has' as='$epr' class='Reference'>
          </join>
        </join>
      </join>
    </join>
  </from>
  <declare name='addressing'>
    http://www.w3.org/2005/08/addressing
  </declare>
  <declare name='gria'>
    http://it-innovation.soton.ac.uk/2005/grid
  </declare>
  <where>
    fn:contains($epr//addressing:Address, "JobService")
  </where>
</query>

1. Submit the query to the registry. The result should contain the SLA endpoint and the Job Service endpoint as well as the SLA as one additional document, the SLA content.
2. Save the query using the ‘File’ menu for latter usage.
3. You can reload this query latter on using the ‘File’ menu.

Next: Appendix Previous: Background - Client Management Registry Service