Registry Client

Factories

After installation the new registry is ready to use. However, configuration and user management can happen beforehand or on-the-fly later on during usage of the registry. In this section we focus on the registration and discovery possibilities of the registry.

In the following classes we use a factory to instantiate discovery and registration classes.

public class XmlRegistryFactory<E> implements RegistryFactory<E> {
  public Discovery<E> createRegistryDiscoveryFacility() {        
     return new XmlDiscoveryFacility<E>();
  } 

  public Registration createRegistrationFacility() throws AccessException {
     return new XmlRegistrationFacility();
  }

  public Credential createCredentialFacility() {
     return new XmlCredentialFacility();
  }
}

The class XmlRegistryFactory that implements the RegistryFactory interface is instantiated like this:

new XmlRegistryFactory<XMLResource>();

However, it is not required to use this class, instead the user can also create the required interfaces by directly calling the appropriate classes, e.g.

Discovery<XMLResource> = new XmlDiscoveryFacility<XMLResource>();

Finally, the interface Credential is used for login and logout of a user who wants to access the registry. This interface can be used in the following way

     Registration registration = new XmlRegistrationFacility();
     Credential credential = new XmlCredentialFacility();
     /*
      * the registration interface should use the following credential...
      */
     registration.setCredential(credential);

     /*
      * user login to the registry...
      */
     credential.login("myUser", "myPass", "myGroup");    

     ...

     /*
      * logout current user...
      */
     credential.logout();

Registration of XML documents and establishing of relationships between XML documents

In the following example code we explain how to register XML documents with the registry and how to establish relationships between independent documents, whereby the relationships and concepts are defined by the RDM of the previous examples.

When registering, the user can provide a unique identifier to the registry for the document or the registry creates a unique identifier on its own. The result of a successful registration is however the identifier used for the document. These identifiers are required to create relationships between concrete XML documents.

import java.net.URI;
import java.net.URISyntaxException;
import java.util.Properties;
import uk.ac.soton.itinnovation.registry.icomponent.access.AccessException;
import uk.ac.soton.itinnovation.registry.icomponent.access.Credential;
import uk.ac.soton.itinnovation.registry.icomponent.registration.Registration;
import uk.ac.soton.itinnovation.registry.icomponent.registration.RegistrationException;
import uk.ac.soton.itinnovation.registry.icomponent.util.PropertyConstants;
import uk.ac.soton.itinnovation.registry.icomponent.util.PropertyManagement;
import uk.ac.soton.itinnovation.registry.test.factory.RegistryFactory;
import uk.ac.soton.itinnovation.registry.test.factory.StartupRegistryFactory;
import uk.ac.soton.itinnovation.registry.test.util.SupportedTechnology; 

public class RegistrationRegistryClient {
  /**
   * Registration client...
   */
  @SuppressWarnings("unchecked")
  public static void main(String[] args) throws RegistrationException, AccessException, URISyntaxException {     
     /*
      * setup registry properties...
      */
     Properties systemProps = System.getProperties();
     String configDir = systemProps.getProperty(PropertyConstants.registryConfigurationDir);
     if(configDir==null){
       String msg = "Configuration directory is not specified, "+
                    "e.g. -Dregistry.conf.dir=... ";
       throw new RuntimeException(msg);
     }     
     PropertyManagement.configurationDirectory = configDir;     

     // working with the registry...
     RegistryFactory factory = StartupRegistryFactory.createRegistryFactory(SupportedTechnology.XML);
     Registration registration = factory.createRegistrationFacility();
     Credential credential = factory.createCredentialFacility();
     registration.setCredential(credential);    

     /*
      * user login to the registry...
      */
     System.out.println("Login...");
     credential.login("myUser","myPass", "myGroup");     
     String path = "./";             
     ClassLoader classLoader = RegistrationRegistryClient.class.getClassLoader();    

     /*
      * get the document URIs...
      */
     URI[] uris = new URI[] {
       classLoader.getResource(path+"sla.xml").toURI(),
       classLoader.getResource(path+"slaConversationEPR.xml").toURI(),
       classLoader.getResource(path+"slaservice.wsdl").toURI(),
       classLoader.getResource(path+"slaServiceEPR.xml").toURI(),
       classLoader.getResource(path+"slaTemplate.xml").toURI()
     };    

     /*
      * register resources...
      */
     System.out.println("Register resources...");
     String sla = registration.registerEntity("Sla", uris[0], null);
     String slaConvEPR = registration.registerEntity("SLAConversation", uris[1], null);
     String slaService = registration.registerEntity("Service", uris[2], "slaservice.wsdl");       
     String slaServiceEPR = registration.registerEntity("RemoteSLAService", uris[3], null);
     String slaTemplate = registration.registerEntity("SlaTemplate", uris[4], null);         

     /*
      * create relationships between entities...
      */
     System.out.println("Create relationships...");
     registration.insertRelationship(sla, "derivedFrom", slaTemplate);
     registration.insertRelationship(sla, "has", slaConvEPR);
     registration.insertRelationship(slaService, "has", slaServiceEPR);
     registration.insertRelationship(slaService, "parent", sla);

     /*
      * logout current user...
      */
     System.out.println("Logout."); 
     credential.logout();
  }
}

Discovery of registered XML documents

Discovery is the process of finding XML documents previously registered. The RC supports different kinds of discovery, like lookup, query or executing predefined queries by name. The Java program below illustrates some of these features by example. The current realisation of the RC supports XQuery, XPath and ooXmlQL as query languages. However, we illustrate only ooXmlQL, because this language supports join queries and sub queries based on the defined RDM. Using XQuery is much more complicated, because the user has to know the internal structure for building correct queries.

import java.io.StringReader;
import java.util.Properties;
import org.xmldb.api.base.XMLDBException;
import org.xmldb.api.modules.XMLResource;
import uk.ac.soton.itinnovation.registry.icomponent.access.AccessException;
import uk.ac.soton.itinnovation.registry.icomponent.access.Credential;
import uk.ac.soton.itinnovation.registry.icomponent.discovery.Discovery;
import uk.ac.soton.itinnovation.registry.icomponent.discovery.DiscoveryException;
import uk.ac.soton.itinnovation.registry.icomponent.discovery.ResultIterator;
import uk.ac.soton.itinnovation.registry.icomponent.search.object.ParameterValue;
import uk.ac.soton.itinnovation.registry.icomponent.search.parser.ParsingException;
import uk.ac.soton.itinnovation.registry.icomponent.search.parser.XmlQueryParser;
import uk.ac.soton.itinnovation.registry.icomponent.search.query.XmlQuery;
import uk.ac.soton.itinnovation.registry.icomponent.util.PropertyConstants;
import uk.ac.soton.itinnovation.registry.icomponent.util.PropertyManagement;
import uk.ac.soton.itinnovation.registry.test.factory.RegistryFactory;
import uk.ac.soton.itinnovation.registry.test.factory.StartupRegistryFactory;
import uk.ac.soton.itinnovation.registry.test.util.SupportedTechnology;

/**
 * Discovery client.
 */
public class DiscoveryRegistryClient {

  @SuppressWarnings("unchecked")
  public static void main(String[] args) throws DiscoveryException,AccessException, XMLDBException, ParsingException {
     /*
      * Setup registry properties...
      */
     Properties systemProps = System.getProperties();
     String configDir = systemProps.getProperty(PropertyConstants.registryConfigurationDir);
     if (configDir == null) {
       String msg = "Configuration directory is not specified, "
                  + "e.g. -Dregistry.conf.dir=... ";
       throw new RuntimeException(msg);
     }
     PropertyManagement.configurationDirectory = configDir;

     /*
      * Discovery interface
      */
     RegistryFactory<XMLResource> factory = (RegistryFactory<XMLResource>) 
          StartupRegistryFactory.createRegistryFactory(SupportedTechnology.XML);
     Discovery<XMLResource> discovery = factory.createRegistryDiscoveryFacility();
     Credential credential = factory.createCredentialFacility();
     discovery.setCredential(credential);

     /*
      * login
      */
     credential.login("myUser","myPass", "myGroup");

     /*
      * execute predefined queries...
      */
     System.out.println("execute predefined query...");
     ResultIterator<XMLResource> i = discovery.executePredefinedQuery(
           "LookupByDocId", 
           new ParameterValue[] { 
               new ParameterValue("docId", "slaservice.wsdl") 
           }
     );
     System.out.println("output of predefined query...");
     for (XMLResource r : i) {
       System.out.println(r.getContent());
     }
     System.out.println();

     /*
      * lookup by identifier...
      */
     System.out.println("lookup by identifier...");
     XMLResource r = discovery.lookup(null, "slaservice.wsdl");
     System.out.println(r.getContent());
     System.out.println();

     /*
      * discovery by ooXmlQL query...
      */
     System.out.println("query using ooXmlQL...");
     String ooXmlQueryStr = "" 
          + "<query>\n"
          + " <select>$ref</select>\n "
          + " <declare name=\"ns1\">"
          + "   http://it-innovation.soton.ac.uk/2005/grid</declare>\n"
          + " <declare name=\"addressing\">"
          + "  http://www.w3.org/2005/08/addressing</declare>\n"
          + " <from as=\"$ref\">"
          + "   <class name=\"Reference\"/>"
          + " </from>\n "
          + "</query>";

     System.out.println("Number of results: "+ query("ooXmlQL", discovery, ooXmlQueryStr));    

     /*
      * discovery by ooXmlQL query with join...
      */
     System.out.println("query using ooXmlQL with join...");
     ooXmlQueryStr = "" 
       + "<query>\n" 
       + " <select>$refAble $epr</select>\n "
       + " <declare name=\"ns1\">"
       + "  http://it-innovation.soton.ac.uk/2005/grid</declare>\n"
       + " <declare name=\"addressing\">"
       + "   http://www.w3.org/2005/08/addressing</declare>\n"
       + " <from as=\"$refAble\">" 
       + "   <union>" 
       + "     <class name=\"Service\"/>" 
       + "     <class name=\"ManagerResource\"/> " 
       + "   </union> " 
       + "   <join on=\"has\" as=\"$epr\" class=\"Reference\"/> " 
       + " </from>\n " 
//     + " <where> " 
//     + "   $epr//addressing:Metadata/ns1:type = \"SlaService\" " 
//     + " </where>" 
       + "</query>";      
     System.out.println("Number of results: "+ query("ooXmlQL with join", discovery, ooXmlQueryStr));     

     /*
      * another discovery by ooXmlQL query with join...
      */
     System.out.println("query using ooXmlQL with join...");
     ooXmlQueryStr = "" 
       + "<query>\n" 
       + " <select>$template</select>\n "
       + " <declare name=\"ns1\">"
       + "   http://it-innovation.soton.ac.uk/2005/grid</declare>\n"
       + " <declare name=\"addressing\">"
       + "   http://www.w3.org/2005/08/addressing</declare>\n"
       + " <from as=\"$epr\">" 
       + "  <class name=\"Reference\"/>" 
       +"   <join on=\"holdBy\" as=\"$refAble\" class=\"Sla\"> "
       + "     <join on=\"derivedFrom\" as=\"$template\" class=\"SlaTemplate\"/> "
       + "  </join> " 
       + " </from>\n " 
       + " <where> "
       + " $template//currency = \"EUR\" "
       + " </where>"
       + "</query>";      
     System.out.println("Number of results: " + query("ooXmlQL with join", discovery, ooXmlQueryStr)); 

     /*
      * logout
      */
     credential.logout();
  }

  
  @SuppressWarnings("unchecked")
  private static int query(String label, Discovery<XMLResource> discovery, String ooXmlQueryStr)
     throws DiscoveryException, AccessException, XMLDBException, ParsingException {
     StringReader reader = new StringReader(ooXmlQueryStr);
     XmlQuery ooXmlQuery = XmlQueryParser.readQuery(reader,discovery.getRegistryDomainModel()); 
     ResultIterator<XMLResource> i = discovery.query(ooXmlQuery);
     int number = output(label, discovery, i);
     return number;
  }

  private static int output(String label, Discovery<XMLResource> discovery, ResultIterator<XMLResource> i) 
     throws XMLDBException, DiscoveryException, AccessException { 
     System.out.println("output of " + label);
     int j = 0;
     for (XMLResource r : i) {
       /*
        * get identifier of document...
        */
       String identifier = discovery.getIdentifier(r, "").toString();
       /*
        * get content...
        */     
       System.out.println(j+".");
       System.out.println("ID: "+identifier);
       System.out.println(r.getContent());
       j++;
     }     
     return j;
  }
}

Removing (unregister) of registered XML documents

The registration interface allows also removing registered XML documents from the registry.

import java.util.HashSet;
import java.util.Properties;
import org.xmldb.api.modules.XMLResource;
import uk.ac.soton.itinnovation.registry.icomponent.access.AccessException;
import uk.ac.soton.itinnovation.registry.icomponent.access.Credential;
import uk.ac.soton.itinnovation.registry.icomponent.discovery.Discovery;
import uk.ac.soton.itinnovation.registry.icomponent.discovery.DiscoveryException;
import uk.ac.soton.itinnovation.registry.icomponent.discovery.ResultIterator;
import uk.ac.soton.itinnovation.registry.icomponent.registration.Registration;
import uk.ac.soton.itinnovation.registry.icomponent.registration.RegistrationException;
import uk.ac.soton.itinnovation.registry.icomponent.util.PropertyConstants;
import uk.ac.soton.itinnovation.registry.icomponent.util.PropertyManagement;
import uk.ac.soton.itinnovation.registry.test.factory.RegistryFactory;
import uk.ac.soton.itinnovation.registry.test.factory.StartupRegistryFactory;
import uk.ac.soton.itinnovation.registry.test.util.SupportedTechnology;

/**
 * Remove entities client...
 */
public class RemoveRegistryClient {  @SuppressWarnings("unchecked")

  public static void main(String[] args) throws RegistrationException, AccessException, DiscoveryException {
     /*
      * setup registry properties...
      */
     Properties systemProps = System.getProperties();
     String configDir = systemProps.getProperty(PropertyConstants.registryConfigurationDir);
     if (configDir == null) {
       String msg = "Configuration directory is not specified, "
                  + "e.g. -Dregistry.conf.dir=... ";
       throw new RuntimeException(msg);
     }     
     PropertyManagement.configurationDirectory = configDir;    

     /*
      * registration...
      */
     RegistryFactory<XMLResource> factory = (RegistryFactory<XMLResource>)
          StartupRegistryFactory.createRegistryFactory(SupportedTechnology.XML);
     Registration registration = factory.createRegistrationFacility();
     Credential credential = factory.createCredentialFacility();
     registration.setCredential(credential);

     /*
      * discovery...
      */
     Discovery<XMLResource> discovery = factory.createRegistryDiscoveryFacility();
     discovery.setCredential(credential);

     /*
      * login...
      */
     credential.login("myUser", "myPass", "myGroup");

     /*
      * remove entity (requires identifier) ...
      */
     System.out.println("Remove slaservice.wsdl");
     registration.deleteEntity("Service", "slaservice.wsdl");    

     /*
      * look out for documents in Sla
      */
     String concept = "Sla";
     ResultIterator<XMLResource> i = discovery.lookupByConcept(concept);
     for (XMLResource r : i) {
       /*
        * get identifier of document...
        */
       HashSet<String> identifiers = discovery.getIdentifier(r, concept);
       for(String identifier : identifiers){
          System.out.println("Remove "+identifier);
          registration.deleteEntity(concept, identifier);
       }
     }    

     /*
      * remove all entities of the current user...
      */
     System.out.println("Remove all...");
     registration.deleteAllEntities();

     /*
      * logout
      */
     credential.logout();
  }
}