8
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 Service provider administrators in an enterprise environment can publish their Web Services for use by Web Service consumers (programmers). Web Service 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 Service provider administrator working with programmers who have completed a Web Service implementation using the J2EE stack (either EJBs, javabeans, JSPs, or servlets) and exposing the implementation as a Simple Open Access Protocol (SOAP)-based Web Service, can publish the Web Service by providing all the metadata and pointers to the interface specification in the UDDI registry. In this way, the Web Service provider administrator publishes the availability of these Web Services for the Web Service consumer or programmer 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 taxonomies, such as the NAICS, ISO3166, and UNSPSC classification systems.

• 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 Service description format and Web Service discovery protocol; a UDDI registry can contain metadata for any type of service, with best practices already defined for those described by Web Service 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 that contains descriptive business information about the business that publishes information about a Web Service, such as information about its 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, it contains descriptive business service information about a particular family of technical services including its name, brief description, technical service description information, and category information that is useful for performing searches

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

• tModel -- descriptions of specifications for Web Services or taxonomies that form the basis for technical fingerprints; its role is to represent the technical specification of the Web Service, in order to facilitate Web Service consumers 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 Service consumers can easily identify other compatible Web Services.

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

Text description of the illustration uddidstp.gif

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

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 the UDDI Data Structure Reference V1.0 Open Draft Specification 30 September 2000 and the 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 Service Registry

This section describes a subset of features that provide UDDI support for Web Services deployed in OC4J as the Oracle 9iAS 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 comprised of two parts:

• Web Service discovery -- programmers can use the Inquiry API available for Java programmers to implement their own Web Service 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 Service 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 Service publishing -- Web Service provider administrators can publish OC4J Web Services into the enterprise-wide Oracle UDDI Web Service registry using the Application Server: iAS: OC4J home: Deployed Applications: Deploy Application Wizard provided through Oracle Enterprise Manager (OEM). 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 Service servlets contained in the EAR file) to the Oracle UDDI registry.

  Web Service 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 OEM.

Web Service Discovery

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

Using Tools

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

Using the Inquiry API

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

The inquiry API allows programmers to discover and use Web Services using the Java language. Programs can be written in any language and 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 the <ias-http-server-host-name> is where the Oracle HTTP Server powered by Apache is installed and the <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 <ORACLE_HOME>/ds/uddi/demo/demo.zip for UNIX and 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, which 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 alphabetic 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 taxonomy 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 free up resources.

  uddiClient.close();
  
  

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

Web Service Publishing

Using OEM, Web Service 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 steps 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 or the Publish Web Services step of the Deploy Applications Wizard lets Web Service provider administrators publish Web Services (servlets) that are found in your EAR file. Any Web Service 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 classification taxonomies provided. Any unpublished Web Service in an application appears with the status of Not Published and when the Web Service 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 you publish J2EE applications to the UDDI registry after entering all required Service Details and tModel Details information.

Web Service provider administrators can update the published Web Services they discover through the OEM 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 classification taxonomies:

• 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 Taxonomy (ISO 3166)

  This a list of all country names and each corresponding two character code element. For more information about ISO3166, see the Web site at: http://www.din.de/gremien/nas/nabd/iso3166ma/.

When you publish a Web Service, you can select the classification taxonomy and the category to which you want to register the Web Service. You have the option of publishing your Web Service to any or all three of these classification taxonomies and to as many categories and subcategories as you wish within each classification taxonomy.

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

Publishing a Web Service Using the OEM Deploy Applications Wizard

To publish a Web Service using the OEM Deploy Applications Wizard, 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 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 Service you want to register from the list of Web Services known to your 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 Service or the tModel sections, click Browse UDDI Registry and browse to the desired classification taxonomy 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 taxonomy, 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 taxonomy, 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 you want to add all the categories to which you want to register this Web Service.

   7. After you have entered all the necessary information on the Web Services Details window and are ready to publish the Web Service 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 Service to publish and repeat this entire process again as described in Steps 3 and 4.

6. After you have published all the Web Services you want for this application, click Next to continue to the Summary window where you can review all the application deployment information.

7. If there are no further changes, click Deploy to deploy your J2EE application on the OC4J container and you will return to the OEM OC4J Home page where you can repeat the process of deploying another J2EE application on the OC4J container by clicking Deploy Application.

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

Publishing a Web Service Using the OEM Web Services Details Window

To publish a Web Service using the OEM Web Services Details window, 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 you select one of the three standard classification taxonomies: 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, you must 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 Service or the tModel sections, click Browse UDDI Registry and browse to the desired classification taxonomy 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 taxonomy, 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 taxonomy, 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 you want to add all the categories to which you want to register this Web Service.

   9. After you have entered all the required information on the Web Services Details window and are ready to publish the Web Service to the Oracle UDDI registry, click Apply. You return 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 a Published Web Service in the UDDI Registry

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

To update a published Web Service using OEM to discover the Web Service, 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 you select one of the three standard classification taxonomies: NAICS, UNSPSC, or ISO 3166 by clicking its link. The UDDI Registry window lets you browse any of the three classification taxonomies and discover published Web Services associated with any category or sub-category.

   Click the desired classification taxonomy link.

3. The UDDI: <Classification Taxonomy Name> window lets you drill down from category to sub-category to discover published Web Services associated with any category or sub-category. Each taxonomy is organized in a hierarchical tree of which you can navigate down a particular branch by clicking the category name to determine all its sub-category 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 sub-category by successively clicking the desired category links.

4. The Web Services: <Category Name> window lets you 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 Service listed for the selected category, its corresponding service name, service key, and business key are also listed. If no Web Services are published for a selected category or sub-category, none are listed.

   To view the complete details of a particular published Web Service 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 Service published in the Oracle UDDI Registry. This information includes:
   • Service Details

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

     Category

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

   • tModel Details

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

     Category

     Category information includes the classification taxonomy 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 Service. You can add categories (click Add Category) to which both this Web Service and tModel are to be registered. You can remove categories (click Delete) from which this Web Service 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 you have made all your selections or completed all changes for this Web Service, 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 just began your current session again.

     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 Taxonomy Name> link to return to the desired Web Services:<Classification Taxonomy Name> window. At this window, you can select another Web service 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 taxonomy to discover Web Services for other categories. At each desired category, select the desired Web Service to view its details, make any necessary changes, and finally click Apply to save your changes.

Database Character Set and Built-in ISO-3166 Taxonomy

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 intended to be 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 taxonomy ISO-3166 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 an UTF-8 database, you can upgrade the built-in ISO-3166 taxonomy to the one with accurate descriptions using the following instructions:

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

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

• Load the ISO-3166 taxonomy 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