Taxonomy  Locate

The Oracle Service Registry Taxonomy demos demonstrates the Oracle Service Registry's Taxonomy capabilities and show how to use this API.

The Taxonomy is used to manage and query taxonomies in the Oracle Service Registry. These demos cover all API methods, so you can learn how to download, upload, save, delete, get and find taxonomies. In addition, you can manage individual values in internally checked taxonomies using the Category API.

The Oracle Service Registry contains the following demos to assist you in learning the Oracle Service Registry Taxonomy and Category APIs.

SaveTaxonomy Demonstrates how to save unchecked taxonomy, which can be used in businessEntities and tModels.

DeleteTaxonomy Demonstrates how to deletes selected taxonomy. If the taxonomy was checked, associated binding template is automatically removed too.

UploadTaxonomy Demonstrates how to upload the file containg taxonomy. This API call is usefull, when you need to process really large taxonomies, because it operates on stream of data.

DownloadTaxonomy Demonstrates how to download selected taxonomy. Again this method is stream oriented.

GetTaxonomy Demonstrates how to get details of selected taxonomy.

FindTaxonomy Demonstrates how to search for taxonomies based on given criteria.

AddCategory Demonstrates how to add new category (keyedReference value) to existing internal taxonomy.

DeleteCategory Demonstrates how to delete the category in existing internal taxonomy.

SetCategory Demonstrates how to update the category in existing internal taxonomy.

MoveCategory Demonstrates how to change the parent of the category in existing internal taxonomy.

GetCategory Demonstrates how to get the category of the internal taxonomy.

GetRootCategory Demonstrates how to get list of the top-level categories of the internal taxonomy.

GetRootPath Demonstrates how to get list of parents of selected category, from the top-level category to the selected one.

FindCategory Demonstrates how to get list of categories, that match some criterias.

Prerequisites and Preparatory Steps: Code  Locate

We expect that you have already installed the Oracle Service Registry and set the REGISTRY_HOME environment variable to the registry's installation location.

To run the Oracle Service Registry's demos, your registry must be running.

It is necessary to configure the demos. The configuration system has two levels: global and local. The properties defined at the global level may be overwritten at local level. The global properties are located in the file:

Windows: %REGISTRY_HOME%\demos\env.properties
UNIX: $REGISTRY_HOME/demos/env.properties

The values set during the installation of the Oracle Service Registry work out of box, and their modification affects all demos. If you need to redefine the value of some property for a single demo (that is, at the local level), edit env.properties. This file is located in the same directory as the file run.sh ( run.bat). Local level properties for the Taxonomy demo is loaded from the file:

Windows: %REGISTRY_HOME%\demos\advanced\taxonomy\env.properties
UNIX: $REGISTRY_HOME/demos/advanced/taxonomy/env.properties

Table 11. Properties Used in Demos

NameDefault ValueDescription
uddi.demos.user.john.namedemo_johnfirst user's name
uddi.demos.user.john.passworddemo_johnfirst user's password
uddi.demos.url.taxonomyhttp://localhost:8888/registry/uddi/taxonomythe taxonomy Web service port URL
uddi.demos.url.categoryhttp://localhost:8888/registry/uddi/categorythe category Web service port URL
uddi.demos.url.securityhttp://localhost:8888/registry/uddi/securitythe security Web service port URL

Presentation and Functional Presentation  Locate

This section describes programming pattern used in all demos using the SaveTaxonomy demo as an example. You can find its source code in the file:

Windows: %REGISTRY_HOME%\demos\advanced\taxonomy\src\demo\uddi\taxonomy\SaveTaxonomy.java
UNIX: $REGISTRY_HOME/demos/advanced/taxonomy/src/demo/uddi/taxonomy/SaveTaxonomy.java

The main method of this demo is straightforward. It gathers user's input, logs the user in the Oracle Service Registry, creates an object of Save_taxonomy, sends it to UDDI registry over SOAP and displays the result.

String user = UserInput.readString("Enter user name", "admin");
String password = UserInput.readString("Enter password", "changeit");
String name = UserInput.readString("Enter name", "Demo identifier");
String description = UserInput.readString("Enter description", "Saved by SaveTaxonomy demo");
System.out.println();

UDDI_Security_PortType security = getSecurityStub();
String authInfo = getAuthInfo(user, password, security);
Save_taxonomy save = createSaveTaxonomy(name, description, authInfo);
TaxonomyDetail result = saveTaxonomy(save);
printTaxonomyDetail(result);
discardAuthInfo(authInfo, security);

When saving taxonomy, you must first create a tModel, that will represent it. You can set your publisher assigned tModelKey and other properties. The only mandatory property is name. You don't need to specify taxonomy related keyedReferences in categoryBag, they shall be set in Taxonomy.

The Categorization is used to define usage of the taxonomy. Valid values are identifier, categorization, categorizationGroup and relationship. The compatibility marks tModel with information, in which UDDI structures it can be used.

This example creates an unchecked identifier, that can be used only in categoryBags of business entities and tModels.

public static Save_taxonomy createSaveTaxonomy(String name, String description, String authInfo)
  throws InvalidParameterException {
    System.out.println("name = " + name);
    System.out.println("description = " + description);

    TModel tModel = new TModel();
    tModel.setName(new Name(name));
    tModel.addDescription(new Description(description));

    Taxonomy taxonomy = new Taxonomy(tModel);
    taxonomy.setCheck(Boolean.FALSE);
    taxonomy.addCategorization(Categorization.identifier);
    taxonomy.addCompatibility(Compatibility.businessEntity);
    taxonomy.addCompatibility(Compatibility.tModel);

    Save_taxonomy save = new Save_taxonomy();
    save.addTaxonomy(taxonomy);
    save.setAuthInfo(authInfo);

    return save;
}

The helper method getTaxonomyStub() returns the Taxonomy stub of the Web service listening at the URL specified by the URL_TAXONOMY property.

public static TaxonomyApi getTaxonomyStub() throws SOAPException {
    String url = DemoProperties.getProperty(URL_TAXONOMY, "http://localhost:8888/registry/uddi/taxonomy");
    System.out.print("Using Taxonomy at url " + url + " ..");
    TaxonomyApi taxonomy = TaxonomyStub.getInstance(url);
    System.out.println(" done");
    return taxonomy;
}

The Taxonomy API call save_taxonomy is performed in the method saveTaxonomy().

public static TaxonomyDetail saveTaxonomy(Save_taxonomy save)
  throws UDDIException, SOAPException {
    TaxonomyApi taxonomy = getTaxonomyStub();
    System.out.print("Save in progress ...");
    TaxonomyDetail taxonomyDetail = taxonomy.save_taxonomy(save);
    System.out.println(" done");
    return taxonomyDetail;
}
      

The returned TaxonomyDetail object is displayed in printTaxonomyDetail method.

public static void printTaxonomyDetail(TaxonomyDetail taxonomyDetail) {
    System.out.println();

    TaxonomyArrayList taxonomyArrayList = taxonomyDetail.getTaxonomyArrayList();
    int position = 1;
    for (Iterator iterator = taxonomyArrayList.iterator(); iterator.hasNext();) {
        Taxonomy taxonomy = (Taxonomy) iterator.next();
        System.out.println("Taxonomy " + position + " : " + taxonomy.getTModel().getTModelKey());
        System.out.println(taxonomy.toXML());
        System.out.println();
        System.out.println("********************************************************");
        position++;
    }
}
      

Building and Running Demos  Locate

This section shows, how to build and run the Oracle Service Registry Advanced Taxonomy demo set. Let's continue with our SaveTaxonomy demo.

  1. Be sure that the demos are properly configured and the Oracle Service Registry is up and running.

  2. Change your working directory to

    Windows: %REGISTRY_HOME%\demos\advanced\taxonomy
    UNIX: $REGISTRY_HOME/demos/advanced/taxonomy

  3. Build all demos using:

    Windows: run.bat make
    UNIX: ./run.sh make

    [Note]Note

    When compiling demos on Windows platforms, you may see the following text:

    A subdirectory or file ..\..\common\.\build\classes already exists.

    This is expected and does not indicate a problem.

  4. To get list of all available demos, run

    Windows: run.bat help
    UNIX: ./run.sh help

  5. The selected demo can be executed via command run with name of demo as parameter. For example to run the SaveTaxonomy demo, invoke

    Windows: run.bat SaveTaxonomy
    UNIX: ./run.sh SaveTaxonomy

    The output of this demo will resemble the following:

    Running SaveTaxonomy demo...
    Saving taxonomy where
    Enter user name [admin]:
    Enter password [changeit]:
    Enter name [Demo identifier]:
    Enter description [Saved by SaveTaxonomy demo]:
    
    Using Security at url https://mycomp.com:8443/registry/uddi/security .. done
    Logging in .. done
    name = Demo identifier
    description = Saved by SaveTaxonomy demo
    Using Taxonomy at url https://mycomp.com:8443/registry/uddi/taxonomy .. done
    Save in progress ... done
    
    Taxonomy 1 : uddi:5c1d5d80-a4d4-11d8-91cd-5c1d367091cd
    <taxonomy check="false" xmlns="http://systinet.com/uddi/taxonomy/v3/5.0">
      <tModel tModelKey="uddi:5c1d5d80-a4d4-11d8-91cd-5c1d367091cd"
       xmlns="urn:uddi-org:api_v3">
        <name>Demo identifier</name>
        <description>Saved by SaveTaxonomy demo</description>
        <categoryBag>
          <keyedReference tModelKey="uddi:uddi.org:categorization:types"
                          keyName="Identifier system" keyValue="identifier"/>
          <keyedReference tModelKey="uddi:systinet.com:taxonomy:compatibility"
                          keyName="Compatibility" keyValue="businessEntity"/>
          <keyedReference tModelKey="uddi:systinet.com:taxonomy:compatibility"
                          keyName="Compatibility" keyValue="tModel"/>
          <keyedReference tModelKey="uddi:uddi.org:categorization:types"
                          keyName="Unchecked value set" keyValue="unchecked"/>
        </categoryBag>
      </tModel>
      <compatibilityBag>
        <compatibility>businessEntity</compatibility>
        <compatibility>tModel</compatibility>
      </compatibilityBag>
      <categorizationBag>
        <categorization>identifier</categorization>
      </categorizationBag>
    </taxonomy>
    
    ********************************************************
    Logging out .. done
  6. To rebuild demos, execute run.bat clean (./run.sh clean) to delete the classes directory and run.bat make (./run.sh make) to rebuild the demo classes.