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.
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
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
This structure is a container for zero or more taxonomies. The truncated attribute indicates whether the list of taxonomies is truncated.
taxonomyInfo Locate
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.
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.
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 BEA AquaLogic Service Registry. The taxonomy consists of a tModel and optional business services and categories.
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.
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 BEA AquaLogic Service Registry. This call is stream oriented and is useful for fetching the content of very large taxonomies.
taxonomy:authInfo - This optional argument is an element that contains an authentication token.
uddi:tModelKey - required uddiKey value that represents an existing taxonomy tModel.
This API call returns a ResponseMessageAttachment with the selected taxonomy upon success.
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.
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]](../images/important.gif) | Important |
|---|---|
The unvalidatable attribute of the tModel of a checked taxonomy will be set to true, if one of the following rules is met:
| |
This API call returns the TaxonomyList upon success.
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.
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.
This API call returns the TaxonomyList on success.
| 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. | |
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 into BEA AquaLogic Service Registry.
The taxonomy properties (checked, unvalidatable, compatibilityBag, and categorizationBag) are first combined with their counterparts in the tModel's categoryBag.
![[Note]](../images/note.gif) | 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.
taxonomy:authInfo - This optional argument is an element that contains an authentication token.
taxonomy:taxonomy - A list of taxonomies to be saved.
This API call returns the TaxonomyDetail on success.
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 BEA AquaLogic Service Registry. This call is stream oriented and is useful for publishing very large taxonomies.
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>/uddi/taxonomy.
Java Locate
Systinet 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:
This structure is almost identical to taxonomy, except that the transformation argument has been added
This structure is almost identical to taxonomyInfo, except that the optional attribute isOrderedBy was added to contain the name of the comparator tModel.
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>/uddi/taxonomy55.