10
Discovering and Publishing Web Services

Oracle9iAS Containers for Java2 Enterprise Edition (J2EE), or OC4J, provides a Universal Discovery Description and Integration (UDDI) Web Services registry in which Web Services provider administrators in an enterprise environment can publish their Web Services for use by Web Services consumers (programmers). Web Services consumers can use the UDDI inquiry interface to discover these published Web Services by browsing, searching, and drilling down in the UDDI registry to select one or more Web Services from among those registered to be used in their applications for a particular enterprise process.

For example, a Web Services provider administrator working with programmers who have completed a Web Services implementation using the J2EE stack (either EJBs, JavaBeans, JSP, or servlets) and exposing the implementation as a Simple Open Access Protocol (SOAP)-based Web Services, can publish the Web Services by providing all the metadata and pointers to the interface specification in the UDDI registry. In this way, the Web Services provider administrator publishes the availability of these Web Services for the Web Services consumer to discover and select for use in their own applications.

UDDI Registration

The information provided in a UDDI registration can be used to perform three types of searches:

• White pages search -- containing address, contact, and known identifiers. For example, search for a business that you already know something about, such as its name or some unique ID.

• Yellow pages topical search -- containing industrial categorizations based on standard classifications, such as NAICS, ISO-3166, and UNSPSC.

• Green pages service search -- containing technical information about Web Services that are exposed by a business, including references to specifications of interfaces for Web Services, as well as support for pointers to various file and URL-based discovery mechanisms.

UDDI uses standards-based technologies, such as common Internet protocols (TCP/IP and HTTP), XML, and SOAP, which is a specification for using XML in simple message-based exchanges. UDDI is a standard Web Services description format and Web Services discovery protocol; a UDDI registry can contain metadata for any type of service, with best practices already defined for those described by Web Services Description Language (WSDL).

UDDI Registry

The UDDI registry consists of the following four data structure types that group information to facilitate rapid location and understanding of registration information:

• businessEntity -- the top-level, logical parent data structure; contains descriptive information about the business that publishes information about Web Services, such as business services, categories, contacts, discovery URLs, and identifier and category information that is useful for performing searches.

• businessService -- the logical child of a single businessEntity data structure as well as the logical parent of a bindingTemplate structure; contains descriptive business service information about a particular family of technical services including its name, brief description, technical service description, and category information that is useful for performing searches.

• bindingTemplate -- the logical child of a single businessService data structure; contains technical information about a Web Services entry point and references to interface specifications.

tModel -- descriptions of specifications for Web Services or classifications that form the basis for technical fingerprints; represents the technical specification of the Web Services, in order to facilitate Web Services consumer searching for registered Web Services that are compatible with a particular technical specification. That is, based on the descriptions of the specifications for Web Services in the tModel structure, Web Services consumers can easily identify other compatible Web Services.

Figure 10-1 shows the UDDI information model and the relationships among its four data structure types.

Figure 10-1 UDDI Information Model Showing the Relationship Among the Four Main Data Structure Types

Text description of the illustration uddidstp.gif

Because UDDI makes use of XML and SOAP, each of these data structure types contains a number of elements and attributes that further serve to describe a business or have a technical purpose. See UDDI Data Structure Reference V1.0 Open Draft Specification 30 September 2000 and UDDI Programmer's API 1.0 Open Draft Specification 30 September 2000 for a complete description of the UDDI service description framework, including its XML schema, and the approximately 20 request messages and 10 response messages that comprise the request/response XML SOAP message interface that is used to perform publishing and inquiry functions against the UDDI business registry.

Oracle UDDI Enterprise Web Services Registry

This section describes a subset of features that provide UDDI support for Web Services deployed in OC4J as the Oracle9iAS Release 2 UDDI enterprise implementation of OC4J Web Services and the UDDI enterprise-wide Web Services registry.

The Oracle UDDI registry support for Web Services deployed in OC4J is composed of two parts:

• Web Services discovery -- consumers can use the Inquiry API available for Java programmers to implement their own Web Services discovery tool to search, locate, and drill down to discover OC4J Web Services in the Oracle UDDI registry, as well as in any other accessible UDDI Version 1.0 Web Services registry. See Using the Inquiry API for more information about using the Inquiry API and locating the Javadoc documentation that describes the Inquiry API.

• Web Services publishing -- Web Services provider administrators can publish OC4J Web Services into the enterprise-wide Oracle UDDI Web Services registry using the Application Server: iAS: OC4J home: Deployed Applications: Deploy Application Wizard provided through Oracle Enterprise Manager. This wizard takes you through the steps necessary to deploy a J2EE application on the OC4J container, and in this process, there is a step where you can publish Web Services (Web Services servlets contained in the EAR file) to the Oracle UDDI registry.

  Web Services provider administrators can also update published Web Services by searching, locating, and drilling down to OC4J Web Services using the Application Server: iAS: OC4J home: Administration: Related Links: UDDI Registry link provided through Oracle Enterprise Manager.

Web Services Discovery

Web Services are discovered in the Oracle UDDI Registry by browsing the registry using tools or using the Inquiry API.

Using Tools

Consumers can create their own inquiry browse tool or use third-party tools to browse and drill down for information about Web Services from the Oracle UDDI registry as well as from any other accessible UDDI Version 1.0 Web Services registry. Consumers can use the Inquiry API available for Java programmers to implement their own Web Services discovery interface.

Using the Inquiry API

The Inquiry API lets consumers search for the available registered Web Services by providing find (browse and drill-down) calls and get calls for locating and getting information in each of the four data structures shown in Figure 10-1.

The Inquiry API allows consumers to discover and use Web Services using the Java language. Programs can be written in any language and can use the SOAP protocol to discover Web Services. The Java API is provided as a convenience for Java programmers. The URL for the UDDI registry is http://<ias-http-server-host-name><ias-port-number>/uddi/inquiry, where <ias-http-server-host-name> is where the Oracle HTTP Server powered by Apache is installed and <ias-port-number> is the port number for the Oracle HTTP Server.

The Inquiry API is located in the Oracle9iAS installation directory, <ORACLE_HOME>/ds/uddi/ for UNIX and <ORACLE_HOME>\ds\uddi\ for Windows. The API documentation that describes how to use this Inquiry API can be found on the Oracle9iAS Documentation Library as UDDI Client API Reference (Javadoc) under Oracle9iAS Web Services, which is located under the J2EE and Internet applications tab.

A set of sample demo files are located in the following directory:

<ORACLE_HOME>/ds/uddi/demo/demo.zip for UNIX

<ORACLE_HOME>\ds\uddi\demo\demo.zip for Windows

Within the demo.zip file is a Java program file, UddiInquiryExample.java, that provides Java programmers with a starting point that demonstrates the key constructs and the sequence in using the Oracle UDDI client library.

The program example does the following:

• Gets an instance of a SoapTransportLiaison. This is an implementation that handles the details of communication between the UDDI client and server using the SOAP protocol and some underlying transport protocol (in this case HTTP).

  SoapTransportLiaison transport = new OracleSoapHttpTransportLiaison();
  
  

• Calls a helper method to set up proxy information, if necessary. You can specify HTTP proxy information for accessing the UDDI registry on the command line, using parameters, such as -Dhttp.proxyHost=<hostname> -Dhttp.proxyPort=<portnum>.

  setHttpProxy((SoapHttpTransportLiaison)transport);
  
  

• Uses the SoapTransportLiaison and the URL of a UDDI inquiry registry to initialize an instance of the UddiClient, which connects to the specified UDDI registry. The UddiClient instance is the primary interface by which clients send requests to the UDDI registry.

  UddiClient uddiClient = new UddiClient(szInquiryUrl, null, transport);
  
  

• Uses the UddiClient to perform a find business request. Specifically, it finds all business entities that start with the letter T and prints out the response. Note that input parameters and return values are objects that precisely mimic the XML elements defined in the UDDI specification.

  // Find a business with a name that starts with "T"
  String szBizToFind = "T";
  System.out.println("\nListing businesses starting with " + szBizToFind);
  // Actual find business operation: 
  // First null means no specialized FindQualifier.
  // Second null means no max number of entries in response. 
  // (For example, maxRows attribute is absent.)
  BusinessList bl = uddiClient.findBusiness(szBizToFind, null, null);
  // Print the response.
  System.out.println("The response is: ");
  List listBusinessInfo = bl.getBusinessInfos().getUddiElementList();
  for (int i = 0; i < listBusinessInfo.size(); i++) {
       BusinessInfo businessInfo = (BusinessInfo)listBusinessInfo.get(i);
       System.out.println(businessInfo.getName());
       System.out.println(businessInfo.getFirstDescription());
  
  

• Uses the UddiClient to get a UddiElementFactory instance. This factory should always be used to create any UDDI objects needed for inquiries.

  UddiElementFactory uddiEltFactory = uddiClient.getUddiElementFactory();
  
  

• Uses the UddiElementFactory instance to create a CategoryBag and its KeyedReference, which will be used for searching.

  CategoryBag cb = (CategoryBag)uddiEltFactory.createCategoryBag();
  KeyedReference kr =
  (KeyedReference)uddiEltFactory.createKeyedReference();
  kr.setTModelKey(szCategoryTModelKey);
  kr.setKeyValue(szCategoryKeyValue);
  kr.setKeyName("");
  cb.addUddiElement(kr);
  
  

• Uses the UddiClient to perform a find service request. Specifically, it finds a maximum of 30 services, which are classified as application service providers (code 81.11.21.06.00) under the UNSPSC classification in any business entities (no businessKey is specified).

  ServiceList serviceList =
        uddiClient.findService("", cb, null, new Integer(30));
  
  

• Uses the UddiElementFactory instance to retrieve an XmlWriter object. To view the raw XML data represented by an object, which extends UddiElement, marshall the element content to the writer and then flush and close the writer.

  XmlWriter writerXmlWriter = uddiEltFactory.createWriterXmlWriter(
        new PrintWriter(System.out));
  serviceList.marshall(writerXmlWriter);
  writerXmlWriter.flush();
  writerXmlWriter.close();
  
  

• Closes the UddiClient instance when finished to release resources.

  uddiClient.close();
  
  

• Provides URLs (in comments) to the Oracle UDDI registry and four public UDDI registries.

Web Services Publishing

Web Services are published in the Oracle UDDI Registry by using Oracle Enterprise Manager or using the Publishing API.

Using Oracle Enterprise Manager

Using Oracle Enterprise Manager, Web Services provider administrators can publish Web Services in the Oracle UDDI Registry in two ways:

• Navigate to the Application Server: iAS: OC4J home: Deployed Applications: Deploy Application Wizard. The Deploy Application Wizard takes you through the process of deploying a J2EE application on the OC4J container by assembling the needed application and module deployment descriptors as an Enterprise Archive (EAR) file. See Oracle9iAS Containers for J2EE User's Guide for information about EAR file-based deployment of J2EE Web applications.

  The second-to-last step, the Publish Web Services step, of the Deploy Applications Wizard lets Web Services provider administrators publish Web Services (servlets) that are found in the EAR file. Any Web Services servlet in an application that you want to access must be published to the Oracle UDDI Registry to one or more desired categories within one or more of the classifications provided. Any unpublished Web Services in an application appears with the status of Not Published and when the Web Services is published, the status changes to Published.

• Navigate to the Application Server: iAS: OC4J home: UDDI Registry: Web Services Details window. The Web Services Details window lets Web Services provider administrators publish J2EE applications to the UDDI Registry after entering all required Service Details and tModel Details information.

Web Services provider administrators can update the discovered published Web Services. They find these published Web Services through the Oracle Enterprise Manager Discovery tool using the UDDI Registry link in the Related Links column within the Administration section of the OC4J: home window from the Application Server: iAS: window.

Oracle UDDI Registry

The Oracle UDDI Registry uses the following three standard classifications:

• North American Industry Classification System (NAICS)

  This is a classification system for each industry and corresponding code. For more information about NAICS, see the Web site at

   http://www.census.gov/epcd/www/naics.html
  
  

• Universal Standard Products and Services Codes (UNSPSC)

  This is the first coding system to classify both products and services for use throughout the global marketplace. For more information about UNSPSC, see the Web site at

   http://eccma.org/unspsc/
  
  

• ISO-3166 Geographic classification (ISO-3166)

  This a list of all country names and each corresponding two-character code element. For more information about ISO-3166, see the Web site at

   http://www.din.de/gremien/nas/nabd/iso3166ma/
  
  

When Web Services provider administrators publishes Web Services, they can select the classification and the category to which they want to register the Web Services. They have the option of publishing their Web Services to any or all three of these classifications and to as many categories and subcategories as they wish within each classification.

See Also: "Database Character Set and Built-in ISO-3166 Classification"

Using the Oracle Enterprise Manager Deploy Applications Wizard

Web Services provider administrators can publish Web Services using the Oracle Enterprise Manager Deploy Applications Wizard. They do this as follows:

1. Invoke Oracle Enterprise Manager and navigate to the Application Server: iAS window and then to the OC4J: home window. Locate the Deployed Applications section within the OC4J: home window and click Deploy Application to invoke the Deploy Application wizard.

2. Step through each window of the Deploy Application wizard and provide the essential information for each step.

3. At the Publish Web Services window, select the desired Web Services to register from the list of Web Services known to the application whose status is Not Published by clicking its corresponding radio button in the Select column, and click Publish to continue to the Web Services Details window.

4. At the Web Services Details window, review, edit, or enter the information as needed in each of the fields in the Service Details section and in the tModel Details section.
   1. To add categories for either the Web Services or the tModel sections, click Browse UDDI Registry and browse to the desired classification and drill down as needed through each desired category noting all desired category names and values.

   2. Click Add Category to add an empty row of category information.

   3. Select the desired classification, then enter the value code and its corresponding category name for the desired category.

   4. Click Add Category again to create another empty category row.

   5. Select the desired classification, enter the value code and its corresponding category name for the desired category.

   6. Repeat this process (Steps d and e) as many times as it takes to add all the categories to which to register this Web Services.

   7. After entering all the necessary information on the Web Services Details window they are ready to publish the Web Services to the Oracle UDDI Registry, click OK. You return to the Publish Web Services window.

5. Back at the Publish Web Services window, select another Web Services to publish and repeat this entire process again as described in Steps 3 and 4.

6. After publishing all Web Services for this application, click Next to continue to the Summary window where all the application deployment information can be reviewed.

7. If there are no further changes, click Deploy to deploy the J2EE application on the OC4J container. Doing this returns you to the Oracle Enterprise Manager OC4J Home page. Then, to repeat the process of deploying another J2EE application on the OC4J container, click Deploy Application.

After deployment, metadata describing the Web Services that you chose to publish has been added to the UDDI registry.

Using the Oracle Enterprise Manager Web Services Details Window

Web Services provider administrators can publish Web Services using the Oracle Enterprise Manager Web Services Details window. They do this as follows:

1. Invoke Oracle Enterprise Manager and navigate to the Application Server: iAS window and then to the OC4J: home window. Locate the UDDI Registry link in the Related Links column within the Administration section of the OC4J: home window.

   Click the UDDI Registry link.

2. The UDDI Registry window lets the administrator select one of the three standard classifications: NAICS, UNSPSC, or ISO-3166 by clicking its link or lets you publish Web Services by selecting the Administration link.

   Click the Administration link.

3. At the Web Services Details window, enter the required information in each of the fields in the Service Details section and in the tModel Details section.
   1. Enter the service name, service description, and service URL to the Servlet in the Service Details section.

   2. Enter the tModel name, tModel description, and the URL to the WSDL document in the tModel Details section.

   3. To add categories for either the Web Services or the tModel sections, click Browse UDDI Registry and browse to the desired classification and drill down as needed through each desired category, noting all desired category names and values.

   4. Click Add Category to add an empty row of category information.

   5. Select the desired classification, then enter the value code and its corresponding category name for the desired category.

   6. Click Add Category again to create another empty category row.

   7. Select the desired classification, enter the value code and its corresponding category name for the desired category.

   8. Repeat this process (Steps d and e) as many times as needed to add all the categories to which to register this Web Services.

   9. After entering all required information on the Web Services Details window, publish the Web Services to the Oracle UDDI Registry by clicking Apply. This returns you to the UDDI Registry window where you can choose to publish another J2EE application to the UDDI registry by following the same steps again, beginning at Step 2.

Updating Published Web Services in the UDDI Registry

Oracle Enterprise Manager provides a user interface for Web Services provider administrators to browse, drill down, and get information about Web Services published for categories in the Oracle UDDI Registry. Web Services provider administrators can update the discovered published Web Services. They find these published Web Services through the Oracle Enterprise Manager Discovery tool using the UDDI Registry link within the Administration section of the OC4J: home window from the Application Server: iAS window.

To update published Web Services using Oracle Enterprise Manager to discover that Web Services, do the following:

1. Invoke Oracle Enterprise Manager and navigate to the Application Server: iAS window and then to the OC4J: home window. Locate the UDDI Registry link in the Related Links column within the Administration section of the OC4J: home window.

   Click the UDDI Registry link.

2. The UDDI Registry window lets the administrator select one of the three standard classification: NAICS, UNSPSC, or ISO-3166 by clicking its link. The UDDI Registry window lets the administrator browse any of the three classifications and discover published Web Services associated with any category or subcategory.

   Click the desired classification link.

3. The UDDI Registry: <Classification Name> window lets the administrator drill down from category to subcategory to discover published Web Services associated with any category or subcategory. Each classification is organized in a hierarchical tree. Navigate down a particular branch by clicking the category name to determine all its subcategory names, and so forth. As you navigate down a branch, also note the change in the category code value.

   Navigate to the desired category or subcategory by successively clicking the desired category links.

4. The Web Services: <Category Name> window lets the administrator continue to drill down through the categories or you can view all Web Services published in a particular category by selecting the corresponding radio button in the Select column for that category and clicking View Services.

   Select the corresponding radio button in the Select column for the desired category and click View Services.

5. The Web Services window lists all Web Services published for that category name. For each Web Services listed for the selected category, its corresponding service name, service key, and business key are also listed. If no Web Services is published for a selected category or subcategory, none is listed.

   To view the complete details of a particular published Web Services listed for a category, either click its service name link or select its corresponding radio button in the Select column and click View Details.

   Click the desired service name link.

6. The Web Services Details window displays detailed information for the selected Web Services published in the Oracle UDDI Registry. This information includes:
   • Service Details

     Service details include information such as the Web Services name, Web Services description, and the URL of the Web Services access point.

     Category

     Category information includes the classification and the corresponding code value and its category name.

   • tModel Details

     tModel details include information that describes the interface that the Web Services implements, such as the tModel name, tModel description, and URL to the interface specification, typically a WSDL document.

     Category

     Category information includes the classification and the corresponding code value and its category name.

     Category information can be added or deleted for both the Service Details and tModel Details sections. You can browse the Oracle UDDI Registry (click Browse UDDI Registry) looking for categories in which to register this Web Services. You can add categories (click Add Category) to which both this Web Services and tModel are to be registered. You can remove categories (click Delete) to which this Web Services and tModel are registered.

     Service and tModel detail information can be modified by moving the cursor to the appropriate field and making the necessary changes.

     After making all selections or completing all changes for this Web Services, click Apply to save your changes.

     If you have made changes to any field and you decide you want to return to the original set of values for all selections, click Revert. The window refreshes with the original set of values for all selections as if you had just begun your current session.

     Make your modifications and click Apply to save your changes.

7. To discover and update other published Web Services for the same category, at the top of the Web Services Details window, select the desired Web Services:<Classification Name> link to return to the desired Web Services:<Classification Name> window. At this window, select another Web Services to view in more detail, make any necessary changes, and finally click Apply to save your changes.

   Alternatively, you can select the UDDI Registry link at the top of the Web Services Details window to return to the UDDI Registry window where you can navigate to another classification to discover Web Services for other categories. At each desired category, select the desired Web Services to view its details, make any necessary changes, and finally click Apply to save your changes.

Using the Publishing API

Note: The publishing API was released as the UDDI v1.0 Compliance Patch Kit available on Metalink as Patch number 2367149. This Patch Kit must be installed for Oracle9iAS release 2 (9.0.2) and Oracle9iAS release 3 (9.0.3) for server-side support of the publishing API.

The UDDI publishing API lets programmers, following authentication, publish Web Services by providing save and delete calls for each of the four key UDDI data structures (businessEntity, businessService, bindingTemplate, and tModel).

The publishing API allows programmers to publish Web Services using the Java language. Programs can be written in any language and use the SOAP protocol to publish Web Services. The Java API is provided as a convenience for Java programmers.

The Publishing API is located in the Oracle9iAS installation directory, <ORACLE_ HOME>/ds/uddi/ for UNIX and <ORACLE_HOME>\ds\uddi\ for Windows. The API documentation that describes how to use this publishing API can be found on the Oracle9iAS Documentation Library CD-ROM as UDDI Client API Reference (Javadoc) under Oracle9iAS Web Services, which is located under the J2EE and Internet Applications tab.

A set of sample demo files are located in the <ORACLE_ HOME>/ds/uddi/demo.zip file for UNIX and the ORACLE_ HOME>\ds\uddi\demo.zip file for Windows.

Within the demo.zip file is a Java program file, UddiPublishingExample.java, that provides Java programmers with a starting point that demonstrates the key constructs and the sequence in using the Oracle UDDI client library.

The program example does the following:

• Gets an instance of a SoapTransportLiaison. This is an implementation that handles the details of communication between the UDDI client and server using the SOAP protocol and some underlying transport protocol (in this case HTTP).

  SoapTransportLiaison transport = 
       new OracleSoapHttpTransportLiaison();
  
  

• Uses the SoapTransportLiaison and the URL of a UDDI publishing registry to initialize an instance of the UddiClient, which connects to the specified UDDI registry. The UddiClient instance is the primary interface by which clients send requests to the UDDI registry. Authentication is done by the transport layer (HTTP BASIC in this example).

  TransportAuthenticationLiason auth = 
      new TransportAuthenticationLiason();
  UddiClient uddiClient = 
      new UddiClient(null, szPublishingUrl, transport, auth);
  
  

• Performs authentication. You should make this call before doing any publishing.

  UddiClient.authenticate();
  
  

• Uses the UddiClient to get a UddiElementFactory instance. This factory should always be used to create any UDDI objects needed.

  UddiElementFactory uddiEltFactory = 
       uddiClient.getUddiElementFactory();
  
  

• Performs various publishing operations that include creating and saving a tModel, a businessEntity, a businessService, and a bindingTemplate data structure for the purpose of creating a business that provides a Google-interface-compatible service.

• Creates a tModel data structure that represents a Google-compatible service by using the UddiElementFactory instance.

  TModel tModel = (TModel)uddiEltFactory.createTModel();   
  tModel.setName("urn:google.com:search-interface");
  
  

  • Creates and includes the OverviewDoc data structure in the tModel data structure by using the UddiElementFactory instance.

    OverviewDoc overviewDocTm =
     (OverviewDoc)uddiEltFactory.createOverviewDoc(); 
         tModel.setOverviewDoc(overviewDocTm);
    overviewDocTm.setOverviewURL("http://api.google.com/GoogleSearch.wsdl");
    
    

  • In the tModel data structure, uses the UddiElementFactory instance to create a CategoryBag data structure and its KeyedReference, which will be used for searching. Classify the tModel data structure as a SOAP/WSDL-based interface and put it under the "applicable service providers" category.

    CategoryBag catBagTm =
     (CategoryBag)uddiEltFactory.createCategoryBag(); 
    tModel.setCategoryBag(catBagTm);
    
    KeyedReference krTm1 = 
    (KeyedReference)uddiEltFactory.createKeyedReference();
    
    catBagTm.addUddiElement(krTm1);
    krTm1.setTModelKey(CoreTModelConstants.TAXONOMY_KEY_UDDI_TYPE);
    krTm1.setKeyName("wsdlSpec");
    krTm1.setKeyValue("wsdlSpec");
    
    KeyedReference krTm2 =
     (KeyedReference)uddiEltFactory.createKeyedReference();
    catBagTm.addUddiElement(krTm2);
    krTm2.setTModelKey(CoreTModelConstants.TAXONOMY_KEY_UDDI_TYPE);
    krTm2.setKeyName("wsdlSpec");
    krTm2.setKeyValue("wsdlSpec");
    
    KeyedReference krTm3 =
     (KeyedReference)uddiEltFactory.createKeyedReference();
    catBagTm.addUddiElement(krTm3);
    krTm3.setTModelKey(CoreTModelConstants.TAXONOMY_KEY_UNSPSC_7_3);
    krTm3.setKeyName("application service providers");
    krTm3.setKeyValue("81.11.21.06.00");
    
    

• Publishes the Google search interface tModel business operation.

  System.out.println("\nPublish the google search interface tModel.");
  TModel tMSaved = uddiClient.saveTModel(tModel);
  String szGoogleTModelKey = tMSaved.getTModelKey();
  System.out.println("The tModel is saved with tModelKey assigned to be " + 
                        szGoogleTModelKey);
  
  

• Creates a businessEntity data structure that represents a Google-compatible service by using the UddiElementFactory instance.

  BusinessEntity businessEntity = 
    (BusinessEntity)uddiEltFactory.createBusinessEntity();
  businessEntity.setName("ACME search Inc.");
  
  

  In the businessEntity data structure, uses the UddiElementFactory instance to create a CategoryBag data structure and its KeyedReference data structure, which will be used for searching. Classify the businessEntity data structure under the "information services and data processing services" category.

  KeyedReference krBe1 = 
   (KeyedReference)uddiEltFactory.createKeyedReference();
  catBagBe.addUddiElement(krBe1);
  krBe1.setTModelKey(CoreTModelConstants.TAXONOMY_KEY_NAICS_1997);
  krBe1.setKeyName("Information Services and Data Processing Services");
  krBe1.setKeyValue("514");
  
  

• Creates a businessService data structure that represents a Google-compatible service by using the UddiElementFactory instance.

  BusinessServices businessServices =
  (BusinessServices)uddiEltFactory.createBusinessServices();
  businessEntity.setBusinessServices(businessServices);
  BusinessService businessService = 
  (BusinessService)uddiEltFactory.createBusinessService();
  businessServices.addUddiElement(businessService);
  businessService.setName("ACME Web Search service");
  
  

  In the businessService data structure, uses the UddiElementFactory instance to create a CategoryBag data structure and its KeyedReference data structure, which will be used for searching. Classify the businessService data structure under the "application service providers" category.

  CategoryBag catBagBs = 
   (CategoryBag)uddiEltFactory.createCategoryBag();
  businessService.setCategoryBag(catBagBs);
  KeyedReference krBs1 = 
   (KeyedReference)uddiEltFactory.createKeyedReference();
  catBagBs.addUddiElement(krBs1);
  krBs1.setTModelKey(CoreTModelConstants.TAXONOMY_KEY_UNSPSC_7_3);
  krBs1.setKeyName("application service 
  providers");krBs1.setKeyValue("81.11.21.06.00");
  
  

• Creates the bindingTemplates data structure that represent a Google-compatible service by using the UddiElementFactory instance.

  BindingTemplates bindingTemplates = 
   (BindingTemplates)uddiEltFactory.createBindingTemplates();
  businessService.setBindingTemplates(bindingTemplates);
  BindingTemplate bindingTemplate = 
   (BindingTemplate)uddiEltFactory.createBindingTemplate();
  bindingTemplates.addUddiElement(bindingTemplate);
  
  

  • Creates and includes the access point in the bindingTemplates data structure by using the UddiElementFactory instance.

    AccessPoint accessPoint =
    (AccessPoint)uddiEltFactory.createAccessPoint();
    bindingTemplate.setAccessPoint(accessPoint);
    accessPoint.setUrlType("http");
    accessPoint.setContent("http://foobar.net/search-g");
    
    

  • Creates and includes the tModel instance details in the bindingTemplates data structure by using the UddiElementFactory instance.

    TModelInstanceDetails tModelInstanceDetails =
    (TModelInstanceDetails)uddiEltFactory.createTModelInstanceDetails();
    bindingTemplate.setTModelInstanceDetails(tModelInstanceDetails);
    
    

  • Declares that the bindingTemplate data structure implements the Google search interface.

    TModelInstanceInfo tModelInstanceInfo =
     (TModelInstanceInfo)uddiEltFactory.createTModelInstanceInfo();
    tModelInstanceDetails.addUddiElement(tModelInstanceInfo);
    tModelInstanceInfo.setTModelKey(szGoogleTModelKey);
    
    

• Publishes the businessEntity data structure and its containing businessService and bindingTemplate data structures.

  System.out.println("Publish the ACME Search Inc. businessEntity...");
  BusinessEntity bESaved = uddiClient.saveBusiness(businessEntity);
  System.out.println("The saved businessEntity (in XML) is:");
  
  

• Uses the UddiElementFactory instance to retrieve an XmlWriter object. To view the raw XML data represented by an object, which extends UddiElement, marshall the element content to the writer and then flush and close the writer.

  XmlWriter writerXmlWriter = 
   uddiEltFactory.createWriterXmlWriter(new PrintWriter(System.out));
  bESaved.marshall(writerXmlWriter);
  writerXmlWriter.flush();
  writerXmlWriter.close();
  
  

• Closes the UddiClient instance when finished to release resources and to log out from the registry.

  uddiClient.close();
  

UDDI Registry Administration

The following sections describe new UDDI registry administration features.

User Management

Oracle9iAS Release 2 UDDI Registry has two types of users, as defined by two different J2EE security roles.

• uddipublisher: Users with the uddipublisher security role can access the publishing end point and save UDDI entities in the registry.

• uddiadmin: Users with the uddiadmin security role can access the publishing end point and perform administrative activities.

User management, including operations such as creation, deletion, suspension, role management, and so forth, is handled by OC4J Java Authentication and Authorization (JAAS) service. Refer to Oracle9iAS Containers for J2EE Services Guide for more information.

There is a set of additional UDDI-specific user operations. See User Account Management for more information about UDDI registry administration.

Performance Monitoring and Tuning

On the back end of an Oracle database, UDDI servlets, and the associated JDBC connection pools can all be monitored using Oracle Enterprise Manager and other standard database monitoring and tuning utilities.

In an OC4J standalone environment, performance information is typically available at

http://<oc4j-host-name>:<port-number>/dmsoc4j/Spy

Data Backup and Restore Operations

Registry data backup and restore operations can be done by using the standard Oracle database backup and restore operations.

Using the Command-Line Tool uddiadmin.jar

The command-line tool uddiadmin.jar is located in the ds/uddi/lib/uddiadmin.jar file for UNIX and in the ds\uddi\lib\uddiadmin.jar file for Windows. Administrators can use this tool for various administrative activities. In general, the command-line tool takes the command-line parameters of the following form:

java -jar uddiadmin.jar <registry publishing URL> <username> <password>
 [-verbose] <action to perform and additional parameters>

The user name is ias_admin and the password is ias_admin.

Note that the -verbose option will cause stack trace information to be printed out when an exception is encountered.

Server Configuration through Import Operation and Built-in Validated Category Management describe the administrative uses of this command-line tool.

Server Configuration

The following parameters are used for server configuration operations. See Server Configuration Parameters Reference Information for more information about these configuration parameters.

Parameter: <registry publishing URL> <username> <password> [-verbose] -getProperties

Description: Lists the current registry configuration parameters.

For example:

java -jar uddiadmin.jar <registry publishing URL> <username> <password>

[-verbose] -getProperties

Parameter: <registry publishing URL> <username> <password> [-verbose] -setProperty <name>=<value>

Description: Changes the value of the named configuration parameter. The UDDI registry J2EE application needs to be restarted for the parameters to take effect.

User Account Management

In general, user management is handled by the OC4J JAAS service. This section describes UDDI-registry-specific operations that are not handled by the OC4J JAAS service. The following parameters are used for user account management:

Parameter: <registry publishing URL> <username> <password> [-verbose] -getUsers

Description: Lists all existing users who have entities in the registry.

For example:

java -jar uddiadmin.jar <registry publishing URL> <username> <password>

[-verbose] -getUsers

Parameter: <registry publishing URL> <username> <password> [-verbose] -getUserDetail <username_to_retrieve>

Description: Retrieves the details of the named user, currently the authorizedName of each user.

Administrative Entity Management

The following parameters are used for administrative entity management.

Parameter: <registry publishing URL> <username> <password> [-verbose] -deleteEntity [-businessKey <businessKey> | -serviceKey <serviceKey> | -bindingKey <bindingKey> | -tModelKey <tModelKey>]

Description: Deletes the named entity irrespective of the owner of the entity. Note that this operation performs a nonpermanent delete (hide) operation in the case of a tModel entity.

Parameter: <registry publishing URL> <username> <password> [-verbose] -destroyTModel <tModelKey>

Description: Permanently deletes the named tModel from the registry (as opposed to the UDDI-defined delete_tModel call, which is just hiding the tModel).

Parameter: <registry publishing URL> <username> <password> [-verbose] -changeOwner <new username> [-businessKey <businessKey> | -tModelKey <tModelKey>]

Description: Changes the ownership of the named entity to the new specified user.

Import Operation

The following parameter is used for importing entities:

Parameter: <registry publishing URL> <username> <password> [-verbose] -import [-businesses <filename> | -tmodels <filename>]

Description: Imports all businessEntity or tModel data structures in the named file. For importing the businessEntity data structure, the named file (<filename>) for importing should contain a UDDI businessDetail XML document. For importing tModels, the named file should contain a UDDI tModelDetail XML document. By importing them, the entityKeys (such as, businessKey, serviceKey, bindingKey, tModelKey) are preserved. The operatorName and authorizedName fields, however, are not preserved. The operatorName field will be replaced by the operatorName configuration parameter of the registry. The owner of the imported entities is the administrator; hence, the authorizedName field will be the authorizedName of the administrator.

The import parameter is particularly useful in importing the well-known service interface specification tModel and classification tModel data structures from some authoritative sources.

Because the entity keys are preserved, administrators should be careful in evaluating the source of the entities to ensure that there will not be a collision in entity keys.

Database Configuration

The following sections describe some database-specific configuration information.

Database Character Set Should Be UTF-8

The database character set should be UTF-8 to accommodate all possible characters. However, if a customer knows for sure that the data to be stored in the registry contains characters of a specific country or region (such as western Europe), the customer may use the appropriate database character set.

Functional Index Should Be Enabled

The functional index must be enabled to support index-based case-insensitive search. The following init.ora parameters are involved: query_rewrite_enabled=true

In addition, the cost-based optimizer must be turned on for analyzing all tables or indexes in the UDDISYS schema. For example:

execute dbms_stats.gather_schema_stats(ownname=>'UDDISYS',cascade=>true);

Accuracy of Modified Timestamps of UDDI Entities

The accuracy of modified timestamps of UDDI entities is dependent on the version and compatibility of the database. If the database compatibility is release 9.0.1 or higher, the modified timestamps are of SQL type TIMESTAMP with an accuracy up to microseconds. If the database compatibility is below release 9.0.1, the modified timestamps are of SQL type DATE with an accuracy up to seconds.

Built-in Validated Category Management

Oracle9iAS Release 2 UDDI Registry can perform a spell-check form of category value validation, increasing the data accuracy in the registry. An administrator can add or remove the set of categories that will be validated by the registry.

Adding a New Category for Registry-based Validation

To add a new category, you must load the category values into the database and register the category with the registry. Perform the following steps:

1. Load the category values into the database. To do this, the category values of the entire category should be in a file using the following format:
   • Each line of the file describes one category value in the category. It should be in the following format:

     <category value> | <description of category value>
      | <category value of the parent>
     
     

   • If a category value is a root value, for example, it has no parent, the category value of the parent should be set to itself.

   • The line of a category value should occur before all of its descendants.

     Examples can be found in the ds/uddi/taxonomy directory for UNIX and in the ds\uddi\taxonomy directory for Windows. Excerpts from the NAICS file are as follows:

     22|Utilities|22
     221|Utilities|22
     2211|Electric Power Generation, Transmission|221
     
     

     It is recommended that you save the file with UTF-8 encoding.

2. Create a SQL*Loader control file to load the category file. An example is ds/uddi/admin/naics-97.ctl for UNIX and ds\uddi\admin\naics-97.ctl for Windows. Copy the file and replace the name of the category file in the control file with the one you create.

3. Load the category file to the database using SQL*Loader. Refer to the SQL*Loader sections of Oracle9i Database Utilities for more information about using SQL*Loader.

4. Register the category with the registry as follows:
   1. Register the category by saving a new tModel for it in the registry. For example, look at the tModel named ntis-gov:naics:1997. You can use the included sample Web applications link http://<ias-web-server-host>:<ias-web-server-port>/uddi/ or a third-party UDDI v1.0-compliant tool. If the tModel data structure has been defined in some other registry, you can also import it (instead of creating a new one, which results in different tModelKeys entities) using the uddiadmin.jar utility. See Import Operation for more information.

   2. Configure the registry so that it recognizes the category that must be validated using the command-line administrative tool, uddiadmin.jar. For example, to add a new tModel entity with key UUID:FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFF0, issue the setProperty command for the property oracle.uddi.server.categoryValidationTModelKeys as follows:

      java -jar uddiadmin.jar <registry publishing URL> <username>
       <password> -setProperty
      "oracle.uddi.server.categoryValidationTModelKeys=
      'UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4',
      'UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88',
      'UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2',
      'UUID:CD153257-086A-4237-B336-6BDCBDCC6634',
      'UUID:FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFF0' "
      
      

      Notice that because the setProperty command defines all categories that need to be validated, to add a new category, you should set the property with all the existing tModelKeys values plus the new tModelKey value that needs to be added.

Removing a Category from Registry-based Validation

To remove a category from registry-based validation, you should deregister the category with the registry and remove the category values in the database. Perform the following steps:

1. To deregister the category with the registry, you should remove it from the list of validated categories using the uddiadmin.jar setProperty command for the property oracle.uddi.server.categoryValidationTModelKeys.

   You do not have to (and in general should not) delete the tModel entity from the registry.

2. To remove the category values from the database, use the SQL*Plus script udivcrm.sql in the ds/uddi/admin directory for UNIX and in the ds\uddi\admin directory for Windows. For example:

   sqlplus uddisys/uddisys @udivcrm.sql
   
   

   When running this script, you will be prompted for the tModelKey value of the category to be removed. You should see that a set of rows is deleted. If the result shows that 0 rows are deleted, you have entered an invalid tModelKey value.

Transport Security

The Inquiry API in general does not require authentication. However, if the inquiry end point needs to be protected, transport level authentication, such as HTTP BASIC authentication and HTTPS SSL client authentication, can be enabled by configuring the web.xml file. A security role, uddiguest, is reserved for accessing the protected inquiry end point. Refer to Oracle9iAS Containers for J2EE Services Guide and Oracle9iAS Containers for J2EE User's Guide for more information about security roles and related security configuration.

For the Publishing API, you may want to allow HTTPS access only. To disable HTTP access, edit the web.xml file of the orauddi application to enforce data confidentiality and make adjustments to HTTP servers accordingly. Refer to Chapter 8 Security in Oracle9iAS Containers for J2EE User's Guide and Oracle9iAS Containers for J2EE Services Guide for more information. For example, to disable HTTP access in the web.xml file, use the following code:

<user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>

Additional Information

The UUID generation algorithm used generates version 4 UUID, which creates UUIDs from random numbers.

All built-in tModel data structures as specified in the UDDI v1 specification are included. An additional tModel data structure uddi-org:operators, defined in the UDDI v2 specification, is also included to classify the bootstrap node businessEntity that represents the UDDI registry itself.

Server Configuration Parameters Reference Information

This section describes reference information for some UDDI server configuration parameters. It is divided into two sections:

• Advanced configuration parameters

• Installation or first-use configuration parameters

These server configuration parameters are referenced in Server Configuration. As each example shows, these configuration parameters can be changed only by using the command-line administration tool, uddiadmin.jar, which is described in Using the Command-Line Tool uddiadmin.jar.

Advanced Configuration Parameters

The following UDDI server parameters can be configured for advanced use.

Parameter name: identifierValidation (Advanced use parameter)

Description: Determine if the registry internally validates identifierBag upon save_xxx calls. In a typical case, there is no reason to change it.

Parameter Type/allowable values: Boolean (true, false)

Initial value: true

Typical value: true

Guideline: N/A

Example:

java -jar uddiadmin.jar <registry publishing URL> <username> <password>
 [-verbose] -setProperty oracle.uddi.server.identifierValidation=true

Parameter name: operatorCategory (Advanced use parameter)

Description: If categoryValidation is true, this property determines whether or not the uddi-org:operators category scheme is validated. If uddi-org:operators is validated, in a single-node scenario, it implies no additional businessEntity data structures can be classified in uddi-org:operators

Parameter type/allowable values: Boolean (true, false)

Initial value: true

Typical value: true

Guideline: N/A

Example:

java -jar uddiadmin.jar <registry publishing URL> <username> <password> 
[-verbose] -setProperty
  oracle.uddi.server.categoryValidation.operatorCategory=true

Parameter name: categoryValidation (Advanced use parameter)

Description: Determine if the registry internally validates categoryBag upon save_xxx calls. In a typical case, there is no reason to change it.

Parameter type/allowable values: boolean (true, false)

Initial value: true

Typical value: true

Guideline: N/A

Example:

java -jar uddiadmin.jar <registry publishing URL> <username> <password>
 [-verbose] -setProperty oracle.uddi.server.categoryValidation=true

Parameter name: categoryValidationTModelKeys (Advanced use parameter)

Description: If categoryValidation is true, this property defines the list of categories to be validated internally by the registry. The validation is essentially a spell-check: compare the value with the set of valid values to make sure it is one.

Parameter type/allowable values: A list in the form of '<tModelKey1>', '<tModelKey2>', '<tModelKey3>'.

Initial value: 'UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4', which represents (uddi-org:types classification). The pre-installed value, however, is UDDI types classification plus the three classifications defined in UDDI v1 specification: (uddi-org:types, uddi-org:iso-ch:3166-1999, ntis-gov:naics:1997, unspsc-org:unspsc).

Note: The uddi-org:types classification should not be removed from the list.

Typical value: The pre-installed value.

Example:

java -jar uddiadmin.jar <registry publishing URL> <username> <password>
 [-verbose] -setProperty 
"oracle.uddi.server.categoryValidationTModelKeys=
'UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4',
'UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88',
'UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2',
'UUID:CD153257-086A-4237-B336-6BDCBDCC6634' "

Installation or First-Use Parameters

The following two parameters operatorName and businessEntityURLPrefix should be changed immediately after an installation, but should not be changed afterward.

Parameter Name: operatorName

Description: The name of the operator, appearing in the operator attribute of UDDI responses.

Parameter type/allowable values: A non-null string.

Initial value: OracleUddiServer

Typical value: <domain of the UDDI registry>/uddi

Guideline: N/A

Example:

java -jar uddiadmin.jar <registry publishing URL> <username> <password>
 [-verbose] -setProperty oracle.uddi.server.operatorName=OracleUddiServer

Parameter Name: businessEntityURLPrefix

Description: This parameter customizes the URL prefix for the generated businessEntity URL for discoveryURL[@useType='businessEntity']. The actual URL is in the form of <businessEntityURLPrefix>?businessKey=<businessKey>.

Parameter type/allowable values: A valid URL.

Initial value: The UDDI registry will prompt an administrator for an initial value upon server initalization.

Typical value: The host name and port should be the host name and port of the Web server (which may or may not be the same as the servlet container).

Guideline: N/A

Example:

java -jar uddiadmin.jar <registry publishing URL> <username> <password>
 [-verbose] -setProperty oracle.uddi.server.businessEntityURLPrefix=

Parameter name: defaultLang

Description: The default language of the registry, used when a description element given in a save_xxx call is not qualified by the xml:lang attribute.

Parameter type/allowable values: Values of xml:lang

Initial value: en

Typical value: The locale of the primary region the registry serves.

Guideline: N/A

Example:

java -jar uddiadmin.jar <registry publishing URL> <username> <password>
 [-verbose] -setProperty oracle.uddi.server.defaultLang=en

Database Character Set and Built-in ISO-3166 Classification

The UDDI specification mandates that the registry support the full UTF-8 character set. Oracle recommends, though does not require, using UTF-8 as the character set for the Oracle9iAS infrastructure database if the UDDI registry is used.

If the database is not configured with the UTF-8 character set or its equivalent or superset, there could be data corruption and error due to loss in character set conversion to or from UTF-8. Refer to Oracle9i Globalization Support Guide for details.

In particular, the descriptions in UDDI built-in ISO-3166 classification contains descriptions with non-ASCII characters, such as some Western European characters and some Eastern European characters for the names of cities or regions. In order to support the non-UTF-8 database, all non-ASCII characters in the descriptions are replaced with ASCII characters as an approximation.

If you do have a UTF-8 database, you can upgrade the built-in ISO-3166 classification to the one with accurate descriptions using the following instructions:

• Delete the existing ISO-3166 classification by running the SQL script, clrISO.sql, for example:

  cd <ORACLE_HOME>/ds/uddi/admin
  sqlplus system/manager @clrISO.sql
  
  

• Load the ISO-3166 classification with accurate descriptions by using SQL* Loader control file iso3166-99.ctl, for example:

  cd <ORACLE_HOME>/ds/uddi/admin
  sqlldr userid=system/manager control=iso3166-99.ctl
  
  

Recommended Configuration for a Production Environment

The following information describes some post-installation configuration steps that you should do immediately after the installation. These steps are not mandatory, but are highly recommended in a production environment.

• User repository setup: By default, a file-based JAAS repository (jazn-data.xml) is deployed with two users: ias_admin and publisher. You should customize the repository. For example, LDAP directory or a centralized jazn-data.xmlshould be your user repository. Refer to Chapter 7 Managing the JAAS Provider in Oracle9iAS Containers for J2EE Services Guide for more information. Examples of using command-line utilities are as follow:

  java -jar jazn.jar -listusers jazn.com
  java -jar jazn.jar -listroles jazn.com
  java -jar jazn.jar -adduser jazn.com myname mypassword
  java -jar jazn.jar -grantrole webserviceuserrole jazn.com myname
  java -jar jazn.jar -revokerole webserviceuserrole jazn.com myname
  java -jar jazn.jar -remuser jazn.com myname
  
  

• Security for publishing the end point: By default, HTTP access is enabled. However, HTTPS access is recommended for security concerns. See Transport Security for more information about disabling HTTP access.