User Guide

Grimoires

Always refer to the documentation under "docs/" of the Grimoires package.

GShell

The Grimoires-GT4SecureClient package contains a GShell able to talk with GRIMOIRES in GT4 in a way compliant with GT4 authentication and authorization implmentation.

For the usage of GShell, please refer to "User Guide - GShell" and "Functional Specification - GShell" in Grimoires documentation.

The usage of GShell in a secure mode is discussed in the security guide.

GrimoiresProxy

GrimoiresProxy is a high-level user-friendly client-side API. It is used, for instance, to build GShell.

For the usage of GrimoiresProxy, please refer to the JavaDoc and "HOWTO - GrimoiresProxy" in Grimoires documentation.

UDDI browser

UDDI browser is a GUI-based client for standard UDDI registries. UDDI browser can be used to interact with GRIMOIRES UDDI compatible interfaces.

For the usage of UDDI browser, please refer to "User Guide - UDDI Browser" in Grimoires documentation.

Grimoires-WSRF

Basically, Grimoires-WSRF provides three WS interfaces

  • Entry. It is associated with a number of WS-Resources. Each of them corresponds to one annotated registry entity, such as UDDI business/service, WSDL operation/message part. Through the entry interface, users can manipulate individual registry entities through the standard operations defined in WS-ResourceProperties, WS-ResourceLifetime, WS-BasicNotification.
  • Query. It is associated with one "huge" WS-Resource, which is equivalent to the collection of all resources associated with the entry interface. The only operation permitted on this huge resource is the query operation defined in WS-ResourceProperties. Through the query interface, users are able to query over the GRIMOIRES registry as a whole.
  • Factory. Through this interface, new registry entities can be created as resources associated with the entry interface. This interface is not covered by the WSRF specifications.

Please also read this paper for a better idea of Grimoires-WSRF.

For reference, please look at the WSDL descriptions that formally define the WS interfaces of Grimoires-WSRF. Under "schema/grimoires/wsrf",

  • GrimoiresWSRFEntry.wsdl: for the entry interface
  • GrimoiresWSRFQuery.wsdl: for the query interface
  • GrimoiresWSRFFactory.wsdl: for the factory interface

Query

To find a registry entity whose name contains "ecs" through the WSRF Query interface, on Windows, run "functest/query-by-name.bat ecs".

The content of query-by-name.bat is 

wsrf-query -d -s http://localhost:8080/wsrf/services/grimoires/wsrf/query 
		"//*[local-name()='AnnotatedRegistryEntity']
		/*/*/*[local-name()='name'][contains(.,'%1')]/../../..
		/*[local-name()='EndpointReference']" > temp.epr

It saves the endpoint reference of the found WS-Resource to temp.epr.

Now we use "functest/get-entry.bat" to retrieve the resource properties document of the found resource. The content of get-entry.bat is as simple as:

wsrf-query -e temp.epr
It returns somethink like
......
<ns2:businessEntity businessKey="1e938e7d-ef3b-4cc4-af25-cb9e82545868">
<ns2:name>ecs</ns2:name>
</ns2:businessEntity>
......

"functest/query-by-metadata.bat" is to find a resource with specified metadata type (_metadata_type_).

wsrf-query -d -s http://localhost:8080/wsrf/services/grimoires/wsrf/query 
"/*[namespace-uri()='http://www.grimoires.org/namespaces/wsrf/query']
[local-name()='GrimoiresWSRFQueryResourceProperties']
/*[namespace-uri()='http://www.grimoires.org/namespaces/wsrf/query']
[local-name()='AnnotatedRegistryEntity']
/*[namespace-uri()='http://www.grimoires.org/metadata.xsd'][local-name()='metadata']
/*[namespace-uri()='http://www.grimoires.org/metadata.xsd'][local-name()='metadataType']
[contains(.,'_metadata_type_')]
/../../*[namespace-uri()='http://schemas.xmlsoap.org/ws/2004/03/addressing']
[local-name()='EndpointReference']"

Update

Say there is a business named "ecs" in the registry. It is without description.

Run "query-by-name.bat ecs".

Run "get-entry.bat > ecs.xml".

Now we get an "ecs.xml" which is the current resource properties document of the resource corresponding to the business named "ecs".

Edit ecs.xml:

Remove

<ns1:TerminationTime xsi:nil="true"/>
<ns1:CurrentTime>......</ns1:CurrentTime>

If notification is in place, also remove the notification-related resource properties.

Now Add <ns2:description>Electronics and Computer Scienece</ns2:description> after the <ns2:name> element.

run "wsrf-update-property -e temp.epr ecs.xml".

Now it updates the WS-Resource. The update will be saved into the triple store as well.

Create

There should be a "grimoires-create-entity" command in $GLOBUS_LOCATION/bin, which is installed by "ant BuildFactoryClient" as in the installation guide for Grimoires-WSRF.

Prepare a "new.xml" as follows:

<ns1:RegistryEntity xmlns:ns2="urn:uddi-org:api_v2" xmlns:ns1="http://www.grimoires.org/namespaces/wsrf/entry">
	<ns2:businessEntity>
		<ns2:name>new</ns2:name>
		<ns2:description>a new business</ns2:description>
	</ns2:businessEntity>
</ns1:RegistryEntity>

Run "functest/create.bat new.xml". The content of "create.bat" is

grimoires-create-entity -s http://localhost:8080/wsrf/services/grimoires/wsrf/factory %1

Now the "new" business is created, and also exposed as a WS-Resource.

Delete

Immediate termination

Say we want delete the "new" business created above.

Run "query-by-name new" to get the endpoint of the "new" business WS-Resource.

Run "wsrf-destroy -e temp.epr".

Scheduled termination
 

Say we want to delete the "new" business in 5 seconds.

Run "query-by-name new" to get the endpoint of the "new" business WS-Resource.

Run "wsrf-set-termination-time -e temp.epr 5" which destroys the WS-Resource in 5 seconds.

Subscribe for notification

Resource property notification

Say we want subscribe for notification in changes on the resource properties document of an "ecs" business.

Run "query-by-name ecs". It saves the endpoint reference for the resource to "temp.epr".

Run "functest/subscribe.bat"

wsn-subscribe -e query1.epr {http://www.grimoires.org/namespaces/wsrf/entry}AnnotatedRegistryEntity

On another console, you may update the "ecs" business. In the console running subscribe.bat, a message will pop up.

Note there is no notification if the WS-Resource is destroyed.

Termination notification

"functest/subscribe2.bat"

wsn-subscribe -e temp.epr {http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}ResourceTermination

It will get notification when the subscribed resource is deleted by either immediate termination or scheduled termination.