Taxonomy  Locate

The Taxonomy API provides high-level view of taxonomies and makes them easy to manage and query. This API was built according to the UDDI technical note Providing A Value Set For Use In UDDI Version 3.

Data Structures  Locate

The following structures are used by the Taxonomy API:

Categories  Locate

This structure is a container for zero or more category structures. If the taxonomy is internal, then categories are used to hold possible values of its keyedReferences.

categorizationBag  Locate

This structure is a container for one or more categorizations. It defines the containers (categoryBag, keyedReferenceGroup, identifierBag and Publisher Assertion) in which this taxonomy can be used. Possible values are categorization, categorizationGroup, identifier, and relationship. A save operation containing a keyedReference referencing a taxonomy in the wrong container will be denied with E_valueNotAllowed UDDI exception.

Category  Locate

This structure corresponds to the keyedReference. It defines the keyedReference of the taxonomy in which it is used. The keyValue must be unique. The disabled attribute is used to mark the category as either helper or deprecated, so it cannot be used as a valid option in keyedReferences. The keyName attribute serves as a label for this category.

Table 13. Attributes

NameRequired
keyNameYes
keyValueYes
disabledNo
compatibilityBag  Locate

This structure is a container for one or more compatibilities. It defines the compatibility of the taxonomy with the four basic UDDI data structures - tModel, businessEntity, businessService and bindingTemplate. If the taxonomy is not compatible with one of these UDDI structures, then a save operation containing a keyedReference referencing this taxonomy in this structure will be denied with E_valueNotAllowed UDDI exception.

taxonomy  Locate

Table 14. Attributes

NameRequired
checkNo
unvalidatableNo
briefNo

Each taxonomy is identified by its tModel.

  • The optional check attribute is used to define whether the taxonomy is checked or not. If the tModel is checked, then a validation structure must be present.

  • The unvalidatable attribute is used to mark the checked taxonomy as unvalidatable. Unvalidatable taxonomies cannot be used in keyedReferences.

  • The brief attribute is related to categories structure and its meaning depends on context, in which it is used.

taxonomyDetail  Locate

Table 15. Attributes

NameRequired
truncatedNo

This structure is a container for zero or more taxonomies. The truncated attribute indicates whether the list of taxonomies is truncated.

taxonomyInfo  Locate

Table 16. Attributes

NameRequired
checkYes
unvalidatableNo

The taxonomyInfo is an extension of the tModelInfo structure.

  • The check attribute indicates whether or not the taxonomy is checked.

  • The unvalidatable attribute is used to mark the checked taxonomy as unvalidatable. Unvalidatable taxonomies cannot be used in keyedReferences.

taxonomyInfos  Locate

This structure is a container for zero or more taxonomyInfo structures.

taxonomyList  Locate

This structure serves as a container for optional listDescription and optional taxonomyInfos structures. The truncated attribute indicates whether the list of taxonomies is truncated.

Table 17. Attributes

NameRequired
truncatedNo
validation  Locate

This structure is used to hold information for validating a checked taxonomy. The categories structure defines the list of available values for keyedReferences checked by the Internal validation service. Binding templates contains the valueset validation Web service endpoint.

Operations  Locate
delete_taxonomy  Locate

The delete_taxonomy API call is used to delete one or more taxonomies from Oracle Service Registry. The taxonomy consists of a tModel and optional business services and categories.

Arguments  Locate
  • uddi:authInfo - This optional argument is an element that contains an authentication token.

  • uddi:tModelKey - One or more required uddiKey values that represent existing taxonomy tModels.

Upon successful completion, a disposition report is returned with a single success indicator.

Permissions  Locate

This API call requires API manager permission with the name org.systinet.uddi.client.taxonomy.v3.TaxonomyApi and the action delete_taxonomy.

download_taxonomy  Locate

The download_taxonomy API call is used to fetch a selected taxonomy from Oracle Service Registry. This call is stream oriented and is useful for fetching the content of very large taxonomies.

Arguments  Locate
  • taxonomy:authInfo - This optional argument is an element that contains an authentication token.

  • uddi:tModelKey - required uddiKey value that represents an existing taxonomy tModel.

Returns  Locate

This API call returns a ResponseMessageAttachment with the selected taxonomy upon success.

Permissions  Locate

This API call requires the API manager permission with name org.systinet.uddi.client.taxonomy.v3.TaxonomyApi and the action download_taxonomy.

find_taxonomy  Locate

The find_taxonomy API call is used to find all taxonomies in a registry that match given criteria. This call is an extension of the UDDI v3 find_tModel API call.

Table 18. Attributes

NameRequired
checkNo
unvalidatableNo
Arguments  Locate
  • uddi:authInfo - This optional argument is an element that contains an authentication token.

  • uddi:findQualifiers - The collection of findQualifier used to alter default behavior.

  • uddi:name - The string value represents the name of tModel to be found.

  • uddi:identifierBag - The list of keyedReferences from tModel IdentifierBag.

  • uddi:categoryBag - The list of keyedReferences from tModel categoryBag.

  • taxonomy:compatibilityBag - An optional list of Compatibilities.

  • taxonomy:categorizationBag - An optional list of Categorizations.

  • check - Optional boolean value that limits returned data to checked (or unchecked) taxonomies only.

  • unvalidatable - Optional boolean value that limits returned data to unvalidatable taxonomies only.

[Important]Important

The unvalidatable attribute of the tModel of a checked taxonomy will be set to true, if one of the following rules is met:

  • The tModel of a checked taxonomy does not contain the validatedBy keyedReference

  • The bindingTemplate from keyedReferences does not exists or is not readable because of ACLs.

Returns  Locate

This API call returns the TaxonomyList upon success.

Permissions  Locate

This API call requires API user permission org.systinet.uddi.client.taxonomy.v3.TaxonomyApi and the action find_taxonomy.

get_taxonomy  Locate

The get_taxonomy API call returns the Taxonomy structure corresponding to each of the tModelKey values specified.

Table 19. Attributes

NameRequired
briefNo
Arguments  Locate
  • uddi:authInfo - This optional argument is an element that contains an authentication token.

  • uddi:tModelKey - Required uddiKey value representing an existing taxonomy tModel.

  • brief - Requests not to fetch the categories element. Note that only the API manager can set this attribute to false.

Returns  Locate

This API call returns the TaxonomyList on success.

[Important]Important

If the tModel of a checked taxonomy does not contain the validatedBy keyedReference, the taxonomy's unvalidatable attribute will be set to true and the validation structure will be missing.

Permissions  Locate

This API call requires the API user permission org.systinet.uddi.client.taxonomy.v3.TaxonomyApi and the action get_taxonomy.

save_taxonomy  Locate

The save_taxonomy API call is used to publish taxonomies to Oracle Service Registry.

The taxonomy properties (checked, unvalidatable, compatibilityBag, and categorizationBag) are first combined with their counterparts in the tModel's categoryBag.

[Note]Note

It is an error to specify a validation structure for an unchecked taxonomy. If the taxonomy contains a validation structure, it is automatically set to be checked. If the taxonomy is neither checked nor unchecked, it will be saved as unchecked. If a checked taxonomy does not have a validation structure, the taxonomy is saved with the unvalidatable attribute set to true.

If the categories structure is defined in the validation structure, then the taxonomy will be checked by the Internal validation service. The bindingTemplates are optional; if they are specified, then their AccessPoint must point to the Internal validation service's Web service endpoint.

If the categories structure is not defined in the validation structure, then there must be at least one bindingTemplate. The bindingTemplate must implement valueset validation API (either uddi:uddi.org:v3_valueSetValidation, uddi:systinet.com:v2_validateValues or uddi:systinet.com:v1_validateValues). There must be a valid AccessPoint.

If the serviceKey is given, then this businessService must be part of the Operational business entity (uddi:systinet.com:uddinodebusinessKey). During the save_taxonomy operation, the businessService will be overwritten.

Arguments  Locate
  • taxonomy:authInfo - This optional argument is an element that contains an authentication token.

  • taxonomy:taxonomy - A list of taxonomies to be saved.

Returns  Locate

This API call returns the TaxonomyDetail on success.

Permissions  Locate

This API call requires the API manager permission org.systinet.uddi.client.taxonomy.v3.TaxonomyApi and the action save_taxonomy.

upload_taxonomy  Locate

The upload_taxonomy API call is used to publish a Taxonomy into Oracle Service Registry. This call is stream oriented and is useful for publishing very large taxonomies.

Permissions  Locate

This API call requires the API manager permission named org.systinet.uddi.client.taxonomy.v3.TaxonomyApi and the action upload_taxonomy.

Persistence Format  Locate

The taxonomy persistence format is used by taxonomy Download/Upload operations. Following is an example of the taxonomy persistence format:

<taxonomy xmlns="http://systinet.com/uddi/taxonomy/v3/5.0" 
    xmlns:uddi="urn:uddi-org:api_v3"
         check="true">
    <tModel tModelKey="uddi:foo.com:demo:myTaxonomy">
        <uddi:name>My taxonomy</uddi:name>
        <uddi:description>Category system</uddi:description>
    </tModel>
    <compatibilityBag>
        <compatibility>businessEntity</compatibility>
    </compatibilityBag>
    <categorizationBag>
        <categorization>categorization</categorization>
    </categorizationBag>
    <validation>
        <bindingTemplate bindingKey="" serviceKey="" xmlns="urn:uddi-org:api_v3">
            <accessPoint useType="endPoint">
               http://www.foo.com/MyValidationService.wsdl
            </accessPoint>
            <tModelInstanceDetails>
                <tModelInstanceInfo 
                    tModelKey="uddi:uddi.org:v3_valueSetValidation"/>
                <tModelInstanceInfo 
                    tModelKey="uddi:systinet.com:demo:myTaxonomy"/>
            </tModelInstanceDetails>
        </bindingTemplate>
    </validation>
</taxonomy>

This format reflects the taxonomy.xsd XML Schema Definition file. For more information, see the data structure of taxonomy.

WSDL  Locate

You can find the WSDL specification in the file taxonomy.wsdl.

API Endpoint  Locate

You can find the Taxonomy API endpoint at http://<host name>:<port>/<context>/uddi/taxonomy.

Java  Locate

Java API is generated from Taxonomy WSDL. You are encouraged to browse org.systinet.uddi.client.taxonomy.v3.TaxonomyApi and to read and try Taxonomy demos.

Taxonomy 5.5 Extension  Locate

This section describes the taxonomy 5.5. extension intended for Range queries functionality implementation.

Data Structures  Locate

The following structures are used by the Taxonomy 5.5 API:

Taxonomy  Locate

Table 20. Attributes

NameRequired
checkNo
unvalidatableNo
briefNo

This structure is almost identical to taxonomy, except that the transformation argument has been added

taxonomyInfo  Locate

Table 21. Attributes

NameRequired
checkYes
tModelKeyyes
unvalidatableNo
isOrderedByNo

This structure is almost identical to taxonomyInfo, except that the optional attribute isOrderedBy was added to contain the name of the comparator tModel.

transformation  Locate

This structure holds a reference to a transformation service implementation. For more information about the transformation service, please see Administrator's Guide, Custom Ordinal Types.

  • uddi:tModel - The tModel that represents a comparator taxonomy.

  • uddi:bindingTemplate - This argument holds the reference of the transformation service implementation. The accessPoint element of the bindingTemplate includes the name of the java class implementation of the sevice with the prefix class:.

  • uddi:tModelKey The key of the tModel that represents the transformation.

API Endpoint  Locate

You can find the Taxonomy 5.5 API endpoint at http://<host name>:<port>/<context>/uddi/taxonomy55.