UDDI APIs  Locate

UDDI (Universal Description Discovery and Integration) is set of Web service that supports the description and discovery of Web service providers, Web services and technical fingerprints of those Web service.

The UDDI API set can be split by typical use case into two parts. The Inquiry API set is used to locate and obtain details on entries in the UDDI registry. For example to find out endpoint of given web service. The publication API set is used to publish and update information in the UDDI registry.

Principles To Use UDDI API  Locate

This section will show you how to use the Oracle Service Registry API. Examples are based on UDDI version 3 Specification.

To use Inquiry APIs you can follow these steps. The complete code fragment is shown in Example 1.

  1. Get API implementation from stub

    String url = "http://localhost:8888/registry/uddi/inquiry";
    UDDI_Inquiry_PortType inquiry = UDDIInquiryStub.getInstance(url);

  2. Collect inquiry parameters

    String serviceKey = "uddi:systinet.com:demo:hr:employeesList";
    String tModelKey = "uddi:systinet.com:demo:employeeList:binding";
    Find_binding find_binding = new Find_binding();
    find_binding.setServiceKey(serviceKey);
    find_binding.addTModelKey(tModelKey);
    find_binding.setMaxRows(new Integer(10));

  3. Call inquiry method

    BindingDetail bindingDetail = inquiry.find_binding(find_binding);

  4. Operate with inquiry result

    ListDescription listDescription = bindingDetail.getListDescription();
    if (listDescription != null) {
        int includeCount = listDescription.getIncludeCount();
        int actualCount = listDescription.getActualCount();
        int listHead = listDescription.getListHead();
        System.out.println("Displaying " + includeCount + " of " + 
            actualCount+ ", starting at position " + listHead);
    }

[Note]Note

If you get the java.lang.reflect.UndeclaredThrowableException exception, check whether Oracle Service Registry is running.

To use the publishing API, follow these steps. The complete code fragment is shown in Example 2.

  1. Get API of security stub

    String securityUrl = "http://localhost:8888/registry/uddi/security";
    UDDI_Security_PortType security = UDDISecurityStub.getInstance(securityUrl);
    String publishingUrl = "http://localhost:8888/registry/uddi/publishing";
    UDDI_Publication_PortType publishing = UDDIPublishStub.getInstance(publishingUrl);

  2. Get authentication token

    AuthToken authToken = security.get_authToken(new Get_authToken(userName, password));
    String authInfo = authToken.getAuthInfo();

  3. Create save object

    String businessKey = "uddi:systinet.com:demo:it";
    String serviceKey = ""; // serviceKey is optional
    int count = 1;
    String[] serviceNames = new String[count];
    String[] languageCodes = new String[count];
    languageCodes[0] = null; // can set an array of language codes
    serviceNames[0] = "Requests Service"; //service name
    String serviceDescription = "Saved by Example"; //service description
    BusinessService businessService = new BusinessService();
    businessService.setBusinessKey(businessKey);
    if (serviceKey != null && serviceKey.length() > 0)
        businessService.setServiceKey(serviceKey);
    businessService.addName(new Name(serviceNames[0], languageCodes[0]));
    businessService.addDescription(new Description(serviceDescription));
    Save_service save = new Save_service();
    save.addBusinessService(businessService);
    save.setAuthInfo(authInfo);

  4. Call publishing method

    ServiceDetail serviceDetail = publishing.save_service(save);

  5. Operate with publishing result

    BusinessServiceArrayList 
         businessServiceArrayList = serviceDetail.getBusinessServiceArrayList();
    int position = 1;
    for (Iterator iterator = businessServiceArrayList.iterator(); 
      iterator.hasNext();) {
        BusinessService service = (BusinessService) iterator.next();
        System.out.println("Service " + position + " : " + service.getServiceKey());
        System.out.println(service.toXML());
        position++;
    } 

  6. Discard the authentication token

    security.discard_authToken(new Discard_authToken(authInfo));

Example 1. FindBinding v3

package example.inquiry;

import org.systinet.uddi.client.v3.UDDIInquiryStub;
import org.systinet.uddi.client.v3.UDDI_Inquiry_PortType;
import org.systinet.uddi.client.v3.struct.*;

import java.util.Iterator;

public class PrincipleFindBinding {

    public static void main(String args[]) throws Exception {

        //1. Get API implementation from stub
        String url = "http://localhost:8888/registry/uddi/inquiry";
        System.out.print("Using Inquiry at url " + url + " ..");
        UDDI_Inquiry_PortType inquiry = UDDIInquiryStub.getInstance(url);
        System.out.println(" done");

        //2. Collect inquiry parameters
        String serviceKey = "uddi:systinet.com:demo:hr:employeesList";
        String tModelKey = "uddi:systinet.com:demo:employeeList:binding";
        Find_binding find_binding = new Find_binding();
        find_binding.setServiceKey(serviceKey);
        find_binding.addTModelKey(tModelKey);
        find_binding.setMaxRows(new Integer(10));

        //3. Call inquiry method
        System.out.print("Search in progress ..");
        BindingDetail bindingDetail = inquiry.find_binding(find_binding);
        System.out.println(" done");

        //4. Operate with result
        ListDescription listDescription = bindingDetail.getListDescription();
        if (listDescription != null) {
            int includeCount = listDescription.getIncludeCount();
            int actualCount = listDescription.getActualCount();
            int listHead = listDescription.getListHead();
            System.out.println("Displaying " + includeCount + " of " + actualCount 
               + ", starting at position " + listHead);
        }

        BindingTemplateArrayList bindingTemplateArrayList 
           = bindingDetail.getBindingTemplateArrayList();
        if (bindingTemplateArrayList == null) {
            System.out.println("Nothing found");
            return;
        }

        int position = 1;
        for (Iterator iterator = bindingTemplateArrayList.iterator();
          iterator.hasNext();) {
            BindingTemplate bindingTemplate = (BindingTemplate) iterator.next();
            System.out.println("Binding " + position + " : " + 
                  bindingTemplate.getBindingKey());
            System.out.println(bindingTemplate.toXML());
            position++;
        }
    }
}

Example 2. SaveService v3

package example.publishing;

import org.systinet.uddi.InvalidParameterException;
import org.systinet.uddi.client.v3.UDDIException;
import org.systinet.uddi.client.v3.UDDIPublishStub;
import org.systinet.uddi.client.v3.UDDISecurityStub;
import org.systinet.uddi.client.v3.UDDI_Publication_PortType;
import org.systinet.uddi.client.v3.UDDI_Security_PortType;
import org.systinet.uddi.client.v3.struct.AuthToken;
import org.systinet.uddi.client.v3.struct.BusinessService;
import org.systinet.uddi.client.v3.struct.BusinessServiceArrayList;
import org.systinet.uddi.client.v3.struct.Description;
import org.systinet.uddi.client.v3.struct.Discard_authToken;
import org.systinet.uddi.client.v3.struct.DispositionReport;
import org.systinet.uddi.client.v3.struct.Get_authToken;
import org.systinet.uddi.client.v3.struct.Name;
import org.systinet.uddi.client.v3.struct.Save_service;
import org.systinet.uddi.client.v3.struct.ServiceDetail;

import javax.xml.soap.SOAPException;
import java.util.Iterator;

public class PrincipleSaveService {

    public static void main(String[] args) throws UDDIException, 
             InvalidParameterException, SOAPException {

        String userName = "demo_john";
        String password = "demo_john";

        //1. Get API implementation from stub
        String securityUrl = "http://localhost:8888/registry/uddi/security";
        System.out.print("Using Security at url " + securityUrl + " ..");
        UDDI_Security_PortType security = UDDISecurityStub.getInstance(securityUrl);
        System.out.println(" done");
        String publishingUrl = "http://localhost:8888/registry/uddi/publishing";
        System.out.print("Using Publishing at url " + publishingUrl + " ..");
        UDDI_Publication_PortType publishing = UDDIPublishStub.getInstance(publishingUrl);
        System.out.println(" done");

        //2. Get authentication token
        System.out.print("Logging in ..");
        AuthToken authToken = 
            security.get_authToken(new Get_authToken(userName, password));
        System.out.println(" done");
        String authInfo = authToken.getAuthInfo();

        //3. Create save object
        String businessKey = "uddi:systinet.com:demo:it";
        String serviceKey = ""; // serviceKey is optional
        int count = 1;
        String[] serviceNames = new String[count];
        String[] languageCodes = new String[count];
        languageCodes[0] = null; // can set an array of language codes
        serviceNames[0] = "Requests Service"; //service name
        String serviceDescription = "Saved by Example"; //service description
        BusinessService businessService = new BusinessService();
        businessService.setBusinessKey(businessKey);
        if (serviceKey != null && serviceKey.length() > 0)
            businessService.setServiceKey(serviceKey);
        businessService.addName(new Name(serviceNames[0], languageCodes[0]));
        businessService.addDescription(new Description(serviceDescription));

        Save_service save = new Save_service();
        save.addBusinessService(businessService);
        save.setAuthInfo(authInfo);

        //4. Call publishing method
        System.out.print("Save in progress ...");
        ServiceDetail serviceDetail = publishing.save_service(save);
        System.out.println(" done");

        //5. Operate with publishing result
        BusinessServiceArrayList businessServiceArrayList = 
             serviceDetail.getBusinessServiceArrayList();
        int position = 1;
        for (Iterator iterator = businessServiceArrayList.iterator();
          iterator.hasNext();) {
            BusinessService service = (BusinessService) iterator.next();
            System.out.println("Service " + position + " : "
               + service.getServiceKey());
            System.out.println(service.toXML());
            position++;
        }
        //6. Discard authentication token
        System.out.print("Logging out ..");
        security.discard_authToken(new Discard_authToken(authInfo));
        System.out.println(" done");
    }
}

UDDI Version 1  Locate

The UDDI version 1 Specification has provided a foundation for next versions.

Inquire  Locate
Publish  Locate

UDDI Version 2  Locate

The UDDI version 2 Specification has introduced many improvements of existing concepts and new features like service projections.

Inquiry  Locate
Publish  Locate

UDDI Version 3  Locate

The UDDI version 3 Specification is a major step in providing industry standard for building and querying XML web services registries useful in both public and private deployments.

Inquiry  Locate

Publication  Locate
Security  Locate
Custody  Locate

The Custody and Ownership Transfer API is used to transfer UDDI structures between UDDI nodes and to change their ownership. One use case is when the publisher wishes to transfer responsibility for a selected UDDI structure to another user, typically after a business reorganization.

Subscription  Locate

The Subscription API is a service that asynchronously sends notification to users who have registered an interest in changes to a registry. These users have a range of options in specifying matching criteria so that they receive only the information in which they are interested.

UDDI Version 3 Extension  Locate

UDDI Version 3 Extensions are extensions of the UDDI Version 3 Specification. The following data structures are used by APIs for the Registry Control and APIs that will be approved as official technical notes of the UDDI specification.

Data Structures  Locate
businessEntityExt  Locate

Table 4. Attributes

NameRequired
businessKeyOptional

This structure is used by the Registry Control for performance enhancements. The structure is an extension of businessEntity, the added element is uddi:assertionStatusItem that points to the related businessEntity,

businessInfoExt  Locate

Table 5. Attributes

NameRequired
businessKeyOptional

This structure is an extension of the businessInfo structure; the added element is uddi_ext:contactInfos.

contactInfo  Locate

Table 6. Attributes

NameRequired
useTypeOptional

This structure represents a person name for the businessInfoExt.

contactInfos  Locate

Table 7. Attributes

NameRequired
useTypeOptional

This structure holds a list of contactInfos.

operationalInfoExt  Locate

Table 8. Attributes

NameRequired
entityKeyRequired
entityKeyV2Optional

This structure is an extension of the operationalInfo structure, the added element is uddi:name. The entityKeyV2 holds UDDI v2 key values.

qualifiedKeyedReference  Locate

Table 9. Attributes

NameRequired
tModelKeyRequired
keyNameOptional
keyValueRequired

This structure holds findQualifiers that are used in Range Queries.

registeredInfoExt  Locate

Table 10. Attributes

NameRequired
truncatedOptional

This structure is used by ACL functionality. The added elements are uddi:serviceInfos and uddi:bindingTemplates that point to UDDI entities the user does not own but has privileges to modify.

serviceInfoExt  Locate

Table 11. Attributes

NameRequired
serviceKeyRequired
businessKeyRequired

This structure is an extension of serviceInfo. It is used by the web interface for performance enhancements. The added elements are uddi:description and uddi:bindingTemplates.

Find Qualifiers  Locate

UDDI V3 Specification permits vendors to define new find qualifiers. Table 12, “Summary of Additional Find Qualifiers in Oracle Service Registry ” summarizes the additional find qualifiers in Oracle Service Registry and the find_xx operations that support them. See Inquiry for more information on inquiry API operations.

Each short name in Table 12, “Summary of Additional Find Qualifiers in Oracle Service Registry ” links to a subsection that follows. Note that the tModel key is the short name prefixed with uddi:systinet.com:findQualifier:.

Table 12. Summary of Additional Find Qualifiers in Oracle Service Registry

Short NameSupporting Operations
find_businessfind_servicefind_bindingfind_tModelfind_relatedBusinesses
deletedTModels    
foreignEntities 
keyNameMatch
myEntities 
omitKeyNameMatch
omitKeyValueMatch
omitTModelKeyMatch
tModelKeyApproximateMatch
deletedTModels  Locate

This find qualifier returns only hidden tModels, hence enabling administrators to locate and permanently delete garbage tModels.

Note that the registry settings determine whether delete_tModel:

  • just hides the tModel from find_tModel operations (default behaviour required by the specification);

  • really deletes the tModel, provided there are no dependencies on it;

See Administrator's Guide, Node.

tModel Keyuddi:systinet.com:findQualifier:deletedTModels
Supporting Operationsfind_tModel.
foreignEntities  Locate

This find qualifier restricts results to entities that do not belong to the caller.

[Note]Note

This qualifier does not make any sense for an anonymous caller because all entities will be returned in the query.

tModel Keyuddi:systinet.com:findQualifier:foreignEntities
Supporting OperationsAll find_xx operations except find_relatedBusinesses.
keyNameMatch  Locate

This find qualifier changes default rules for matching keyedReferences. By default keyNames are only compared when the General Keywords tModelKey is specified. This find qualifier enforces comparison of keyNames.

The keyNameMatch and omitKeyNameMatch findQualifiers are mutually exclusive.

tModel Keyuddi:systinet.com:findQualifier:keyNameMatch
Supporting OperationsAll find_xx operations.
myEntities  Locate

This find qualifier restricts results to entities that belong to the caller.

[Note]Note

This qualifier does not make any sense for an anonymous caller. All entities would be returned in that case.

tModel Keyuddi:systinet.com:findQualifier:myEntities
Supporting OperationsAll find_xx operations except find_relatedBusinesses.
omitKeyNameMatch  Locate

This find qualifier changes default rules for matching keyedReferences. By default keyNames are only compared when the General Keywords tModelKey is specified. This find qualifier skips comparison of keyNames.

The keyNameMatch and omitKeyNameMatch findQualifiers are mutually exclusive.

tModel Keyuddi:systinet.com:findQualifier:omitKeyNameMatch
Supporting OperationsAll find_xx operations.
omitKeyValueMatch  Locate

This find qualifier changes default rules for matching keyedReferences. By default keyValues are compared. This find qualifier skips comparison of keyValues.

The omitKeyValueMatch and omitTModelKeyMatch findQualifiers are mutually exclusive.

tModel Keyuddi:systinet.com:findQualifier:omitKeyValueMatch
Supporting OperationsAll find_xx operations.
omitTModelKeyMatch  Locate

This find qualifier changes default rules for matching keyedReferences. By default tModelKeys are compared. This find qualifier skips comparison of tModelKeys.

The omitKeyValueMatch and omitTModelKeyMatch findQualifiers are mutually exclusive.

tModel Keyuddi:systinet.com:findQualifier:omitTModelKeyMatch
Supporting OperationsAll find_xx operations.
tModelKeyApproximateMatch  Locate

This find qualifier changes the default rules for matching keyedReferences. By default tModelKeys are compared without wildcards and case insensitively. This find qualifier enables a tModelKey in a query to include wildcards:

  • '%' interpreted as zero or more arbitrary characters;

  • '_' interpreted as an arbitrary character.

The behavior is similar to the approximateMatch find qualifier.

tModel Keyuddi:systinet.com:findQualifier:tModelKeyApproximateMatch
Supporting OperationsAll find_xx operations.