User guide for the 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.
- Adding
the registry service is done in the same way as adding the other services. See
Adding Services.
- 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
- Click on the Registry Resource in the client.
- Click on the 'Resources' tab on the panel on the
left.
- Click on the 'Load Resources' button to load the
current resources into the table.
- 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:
- 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.
- Add
the SLA Service and the Trade Account Service to the list of services. Propose
an SLA.
- Create
a Registry resource.
- Create
a data stager and a job.
- 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’.
- Open
the Query Wizard.
- Select
concept ‘ReferenceSLA’ and add it to the set of concepts by pressing ‘+’.
- 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:
- Select
the relationship for navigation
- Select
sub concepts if required and specify a suitable variable for this concept
- Add
additional joins from the concept selected beforehand by pressing the ‘+’
button
- 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:
- 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.)
- 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.)
- Select
relation ‘manages’ and add variable name ‘$managed’. Press ‘+’. (What resources
are managed by this service?)
- Select
relation ‘has’ and add variable name ‘$epr’. (What are the References of these
managed resources?)
- 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:
- Select
the namespaces ‘gria’, ‘addressing’ and ‘metric’. (Used in the where clause later on.)
- 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:
- Add
where clause:
fn:contains($epr//addressing:Address,"JobService")
- 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:
- Select
variables ‘$referencesla’, ‘$slaContent’ and ‘$epr’.
- 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.
- 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:
- Select
a relationship (‘return’) that provides the domain concept you want to restrict
(left component in the brackets).
- Select
a sub concept if required.
- 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. - 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.
- 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:
- Select
return ‘isUsageOf’ and press ‘+’. (Restrict SLAs by usage information.)
- In
the new Query Wizard dialog, add variable ‘$usage’ in the ‘From’ part of the
sub query.
- Press
‘next’ until you reach the where clause specification.
- Add
the where clause:
$usage//metric[@description="disk space"]//rate > 0.0
- Press
‘finish’.
- 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.) - Press
‘finish’.
- Press
next until you reach the ‘Select’ view. (Otherwise the previous specifications
of steps done beforehand are gone.)
- 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>
- 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.
- Save
the query using the ‘File’ menu for latter usage.
- You
can reload this query latter on using the ‘File’ menu.
Icon and resource URL similar to the following pattern 'https://service:8443/gria-service-provider-mgt/services/SLAService#1234-1234-1234-1234'