10 Discovering and Publishing Web Services

10.1.1 UDDI Registry Data Structure

The UDDI registry consists of the following five data structure types, which group information to facilitate rapid location and comprehension of registry information:

• businessEntity—the top-level, logical parent data structure. It contains descriptive information about the business that publishes information about Web Services, such as company name, contacts, 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, 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 Services entry point, and references to interface specifications.

• tModel—a description of specifications for Web Services, or a classification that forms the basis for technical identification. It represents the technical specification of Web Services. It facilitates the Web Services consumers (programmers) 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 data structure, Web Services consumers can easily identify other compatible Web Services.

• publisherAssertion—information about a relationship between two parties, asserted by one or both.

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

Figure 10-1 UDDI Registry Information Model

Description of the illustration uddidstp.gif

Because the UDDI registry makes use of XML and SOAP, each of these data structures contains a number of elements and attributes that further serve to describe a business or have a technical purpose.

For a complete description of the UDDI service description framework, see UDDI Version 2.03, Data Structure Reference Published Specification, Dated 19 July 2002 and UDDI Version 2.04 API, Published Specification Dated 19 July 2002, available at:

http://www.uddi.org/specification.html

10.2.1 Support for Standard Classification and Identifier Systems

OracleAS UDDI Registry supports standard taxonomies for classifying (categorizing) tModels, businessEntities, and businessServices and for identifying tModels and BusinessEntities.

OracleAS UDDI Registry provides the following built-in and checked standard taxonomies for categorizing tModels, businessEntities, and businessServices:

• North American Industry Classification System (NAICS) 1997 Release

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

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

• United Nations Standard Products and Services Codes (UNSPSC) Version 7.3

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

  http://www.unspsc.org/
  
  

• ISO-3166 Geographic Code System (ISO-3166)

  This a list of all countries and their subdivisions. For more information about ISO-3166, see the following Web site:

  http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html
  
  

When administrators publish Web Services, they can select the taxonomy 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 taxonomies, and to as many categories and subcategories as they wish within each.

OracleAS UDDI Registry also provides the following built-in identifier systems for identifying tModels and businessEntities:

• Dun & Bradstreet D-U-N-S Number Identifier System (D-U-N-S)

  This system uses unique nine-digit sequences for identifying businesses worldwide. For more information, see the following Web site:

  http://www.dnb.com
  
  

• Thomas Register Supplier Identifier Code System

  This system provides identification codes for manufacturers and suppliers. For more information see the following Web site:

  http://www.thomasregister.com/
  
  

Table 10-1 lists the taxonomy, its name, and its tModel key, a unique universal identifier (UUID).

For more information about the taxonomies, see the following Web site:

http://www.uddi.org/taxonomies/UDDI_Taxonomy_tModels.htm

10.2.2 UUID Generation

OracleAS UDDI Registry uses an algorithm to generate a version 4 Unique Universal Identifier (UUID) from random numbers.

All built-in tModel data structures as specified in the UDDI v2 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 OracleAS UDDI Registry itself.

10.3.1 Configuring OracleAS UDDI Registry

If you install the OracleAS Infrastructure 10g and the OracleAS Portal and Wireless middle tier, OracleAS UDDI Registry is installed. OracleAS UDDI Registry is automatically deployed into an OC4J_Portal instance and the UDDI database schema is embedded in the OracleAS Infrastructure database.

If you want to install OracleAS UDDI Registry with OC4J standalone or with Oracle Application Server Core install, please refer to the standalone OracleAS UDDI Registry kit on OTN:

http://www.oracle.com/technology/tech/webservices/htdocs/uddi

To initialize and configure OracleAS UDDI Registry, you must access (either through the browser or programmatically through a SOAP invocation) the UDDI servlet inquiry end point or publishing SOAP end points. Otherwise, you will not be able to use OracleAS UDDI Registry from Oracle Enterprise Manager 10g, including the integrated Web Services publishing.

To initialize and configure OracleAS UDDI Registry by pinging the UDDI inquiry servlet end point from a browser, enter the following URL:

http://OracleAS-host:OracleAS-port/uddi/inquiry

The OracleAS UDDI Registry page is displayed. You should see the message: "Welcome! Your registry is now up and running."

This initialization and configuration step sets up the following:

• UDDI core tModel data structures

• A businessEntity node representing the registry node

• The businessEntity discoveryURL prefix and the operatorName property

By default, the installation creates UDDI users and user groups. Table 10-2 lists the type of user, the user names, and passwords.

You can connect to the UDDI end points using these user names and passwords. "Managing Users" provides more information about the UDDI users and groups that are set up during installation.

The OracleAS UDDI Registry is available through the following URLs:

• Getting started information

  http://OracleAS-host:OracleAS-port/uddi/
  
  

• UDDI inquiry SOAP end point

  http://OracleAS-host:OracleAS-port/uddi/inquiry
  
  

• UDDI publishing SOAP end point

  http://OracleAS-host:OracleAS-port/uddi/publishing
  
  

• UDDI administration end point

  http://OracleAS-host:OracleAS-port/uddi/admin
  
  

• UDDI replication SOAP end point

  http://OracleAS-host:OracleAS-port/uddirepl/replication
  
  

• UDDI replication HTTPS Wallet Password Administration end point

  http://OracleAS-host:OracleAS-port/uddirepl/admin/wallet
  

10.3.2 Modifying Properties at Installation or First-Use

You perform many administrative operations using the command-line tool uddiadmin.jar. The tool is located in the uddi/lib/uddiadmin.jar file for UNIX and in the uddi\lib\uddiadmin.jar file for Windows. In general, the command-line tool uses the following format:

java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password
[-verbose] options_and_their_parameters

With the setProperty option of the command-line tool uddiadmin.jar, you can set the value of configuration properties, such as maximum database connections and default language.

You should change the following two properties immediately after installation. However, once you change them, you should not change them again unless there are changes to the host setup or you move the system from a staging environment to a production environment.

• operatorName: Provides the name of the operator of OracleAS UDDI Registry. This name appears in the operator attribute of responses. Setting this property applies in a retroactive fashion to existing entities in the database. For example, changing the operator name results in the new operator name replacing the old operator name in all business and tModel data structures.

  The following example sets the operatorName property to OracleUddiServerIT_Dept:

  java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password
   -setProperty oracle.uddi.server.operatorName=OracleUddiServerIT_Dept
  
  

• businessEntityURLPrefix: Provides the prefix of the generated discoveryURL, which is automatically generated for each businessEntity data structure saved in the registry. The prefix should be customized for your deployment environment. Setting this parameter applies in a retroactive fashion to existing entities in the database. For example, changing the discoveryURL prefix results in the new discoveryURL replacing the old discoveryURLs in all businessEntity usetypes.

  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).

  The following example sets the prefix of the discoveryURL to http://uddihost:port/uddi/inquiryget:

  java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password
  -setProperty oracle.uddi.server.businessEntityURLPrefix=http://uddihost:port/uddi/inquiryget
  

In addition, you can set the default language of the registry by using the defaultLang property. See "defaultLang" for more information.

See "Using the Command-Line Tool uddiadmin.jar" for information about the command-line tool. See "setProperty" for more information about the setProperty option.

10.3.3 Considerations in a Production Environment

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

• 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.

• Database connection pool sizing and statement caching: Database connection pool parameters, such as maximum number of database connections and usage of statement caching, should be configured to accommodate the actual database server load.

  If you are using an Oracle database other than the OracleAS Infrastructure database as the back-end storage, you can configure the parameters by editing the data source jdbc/OracleUddi. Refer to the chapter on data sources in the Oracle Application Server Containers for J2EE Services Guide for more information.

  If you are using the OracleAS Infrastructure database as the back-end storage, you can configure the parameters by modifying the following UDDI server configuration properties:

  • minConnections

  • maxConnections

  • jdbcDriverType

  • stmtCacheType

  • stmtCacheSize

• Change of the operatorName and businessEntity discoveryURL prefix: In some cases, you may want to change either the businessEntity discoveryURL prefix or the operatorName, or both parameter values, when moving a system from a staging environment to a production environment. See "businessEntityURLPrefix" and "operatorName" for more information.

10.4.1 Using the OracleAS UDDI Registry Searching and Browsing Tool

OracleAS UDDI Registry provides a Searching and Browsing Tool that lets you search a registry by businessEntity, businessService, tModel, or bindingTemplate. To access the Searching and Browsing tool, enter the following URL:

http://OracleAS-host:OracleAS-port/uddi

Then, click the UDDI Inquiry/Publishing tool link. The Searching and Browsing Tool page is displayed, as shown in the following illustration:

10.4.2 Using Other Tools to Discover Web Services

As a consumer, you can use Oracle JDeveloper to browse OracleAS UDDI Registry, or you can use third-party tools to browse and drill down for information about Web Services from OracleAS UDDI Registry, as well as from any other accessible UDDI v1.0 Web Services registry.

10.4.3 Using the OracleAS UDDI Registry Inquiry API

As a consumer, you can use the Inquiry API available for Java programmers to implement your own Web Services discovery interface. The Inquiry API, part of the UDDI Client API, provides find (browse and drill-down) calls and get calls for locating and getting information in each of the five data structures shown in Figure 10-1.

The Inquiry API is a Java-based API and is provided as a convenience for Java programmers. However, programs can be written in any language and can use SOAP to discover Web Services.

The URL for the OracleAS UDDI Registry inquiry API is:

http://OracleAS-http-server-hostname:OracleAS-port/uddi/inquiry

In the URL, OracleAS-http-server-hostname is the host where Oracle HTTP Server is installed, and OracleAS-port is the port number for Oracle HTTP Server.

The Inquiry API is located in the Oracle Application Server installation directory, ${ORACLE_Home}/uddi/ for UNIX and %ORACLE_Home_ORACLE%\uddi\ for Windows. For reference documentation for the Inquiry API, see the Oracle Application Server Web Services UDDI Client API Reference.

A set of sample demonstration files (uddidemo.zip) are located on the Oracle Technology Network (OTN) Web site at:

http://www.oracle.com/technology/tech/webservices/htdocs/uddi

The uddidemo.zip file contains a Java program file, UddiInquiryExample.java, which provides Java programmers with a starting point that demonstrates the key constructs and the sequence in using the OracleAS UDDI Registry client library.

The program example does the following:

• Gets an implementation of the SoapTransportLiaison interface. This is an implementation that handles the details of communication between the UDDI client and server, using SOAP 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 OracleAS UDDI Registry on the command line, using parameters, such as -Dhttp.proxyHost=hostname -Dhttp.proxyPort=portnum.

  setHttpProxy((SoapHttpTransportLiaison)transport);
  
  

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

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

  
  

  Note: The UddiClient instance, by default, operates as a UDDI v2 client (the latest version supported). If a specific version is needed, the version can be specified either through another constructor, or the JVM property oracle.uddi.client.defaultVersion. For example: -Doracle.uddi.client.defaultVersion=1

  
  

• Uses the UddiClient instance to perform a find business request. Specifically, it finds all businessEntities 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.getBusinessKey());
          Name name = businessInfo.getFirstNameAsName();
          if (name != null) {
            System.out.println("name=" + name.getContent() + 
                               " ; xml:lang=" + name.getLang());
          }
  
   Description description = 
      businessInfo.getFirstDescriptionAsDescription();
   if (description != null) {
      System.out.println("description=" + description.getContent()
                     +  " ; xml:lang=" + description.getLang());
   }
  
  

• Uses the UddiClient instance 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 instance 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 instance 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 businessEntity (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();
  
  

• Finds tModel operations with multiple arguments. This is a UDDI v2 feature. A find_xx request now allows multiple arguments. For example, find tModel operations that have a name pattern, such as "uddi%inquiry%" and are classified as wsdlSpec or xmlSpec in uddi-org:types taxonomy:

  System.out.println("\nListing tModels with the name pattern \"uddi%inquiry%\" ");
  System.out.println("and classified as \"wsdlSpec\" or \"xmlSpec\" ");
  System.out.println("under uddi-org:types taxonomy.");
  // Use UddiElement factory to create UDDI-specific objects 
  // that are needed in inquiries.
  CategoryBag cbTM = (CategoryBag)uddiEltFactory.createCategoryBag();
  KeyedReference krTM1 =
   (KeyedReference)uddiEltFactory.createKeyedReference();
  krTM1.setTModelKey(CoreTModelConstants.TAXONOMY_KEY_UDDI_TYPE);
  krTM1.setKeyValue(CoreTModelConstants.UDDI_TYPE_VALUE_WSDL_SPEC);
  cbTM.addUddiElement(krTM1);
  
  KeyedReference krTM2 =
   (KeyedReference)uddiEltFactory.createKeyedReference();
  krTM2.setTModelKey(CoreTModelConstants.TAXONOMY_KEY_UDDI_TYPE);
  krTM2.setKeyValue(CoreTModelConstants.UDDI_TYPE_VALUE_XML_SPEC);
  cbTM.addUddiElement(krTM2);
  
  FindQualifiers fqTM = (FindQualifiers)uddiEltFactory.createFindQualifiers(); 
  List listFQTM = uddiEltFactory.createList();
  listFQTM.add(FindQualifiers.OR_ALL_KEYS);
  fqTM.setFindQualifierStringList(listFQTM);
  
  // Actual find tModel operation:
  // Integer(10) means a maximum of 10 tModel operations are to be returned.
  TModelList tModelList =  uddiClient.findTModel("uddi%inquiry%", 
                                                  null, 
                                                  cbTM, 
                                                  fqTM, 
                                                  new Integer(10));
  
  // Print some response information.
  System.out.println("The response is: ");
  List listTModelInfo = tModelList.getTModelInfos().getUddiElementList();
  for (int i = 0; i < listTModelInfo.size(); i++) {
    TModelInfo tModelInfo = (TModelInfo)listTModelInfo.get(i);
    System.out.println(tModelInfo.getTModelKey());
    System.out.println("name=" + tModelInfo.getName());
   }
  
  

• Closes the UddiClient instance when finished, to release resources.

  uddiClient.close();
  
  

• Provides URLs (in comments) to OracleAS UDDI Registry and four public UDDI registries.

10.5.1 Using Oracle Enterprise Manager for Web Services Publishing

Using Oracle Enterprise Manager 10g, administrators can publish Web Services in OracleAS UDDI Registry and can update discovered Web Services:

• Using the Deploy Application Wizard. The Deploy Application wizard takes you through the process of deploying a J2EE application on the OC4J container.

  See "Publishing Web Services Using the Deploy Application Wizard".

• Using the UDDI Registry page. The UDDI Registry page lets you discover published Web Services and update those published Web Services.

  See "Updating Published Web Services in OracleAS UDDI Registry".

10.5.1.2 Updating Published Web Services in OracleAS UDDI Registry

You can use Oracle Enterprise Manager to browse, drill down, and get information about Web Services published for categories in OracleAS UDDI Registry. You can update the discovered published Web Services.

To update published Web Services using Oracle Enterprise Manager 10g, do the following:

1. Invoke Oracle Enterprise Manager and navigate to the Application Server Instance-name page. From the System Components table, select an OC4J instance.

2. In the OC4J:oc4j-name page, click the Administration link. On the Administration page, click the UDDI Registry link in the Related Links section.

   If UDDI Registry is not listed in the Related Links column, initialize the OracleAS UDDI Registry by pinging the UDDI inquiry servlet end point (see "Configuring OracleAS UDDI Registry".) Then, restart Oracle Enterprise Manager.

3. In the UDDI Registry page, select one of the three standard classifications, NAICS, UNSPSC, or ISO-3166, by clicking its link. The following illustration shows the UDDI Registry page:

   
   Description of the illustration uddi_reg.gif
   
   

4. In the UDDI Registry: Classification_Name page, you can 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.

   The following illustration shows the page:

   
   Description of the illustration uddi_class.gif
   
   

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

5. To view all Web Services published in a particular category, select the corresponding radio button in the Select column for that category, and click View Details.

   The Web Services page lists all Web Services published for that category name. For Web Services listed for the selected category, the corresponding service name, service key, and business key are also listed. If the selected category or subcategory has no published Web services, none is listed.

   The following illustration shows the Web Services page:

   
   Description of the illustration uddi_serv.gif
   
   

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

   Click the desired service name.

7. The Web Service Details page displays detailed information for the selected Web Service published in OracleAS UDDI Registry. This information includes:

   • Service Details: Information such as the Web Services name, Web Services description, and the URL of the Web Services access point.

     Service Category: The classification and the corresponding code value and its category name.

   • tModel Details: 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.

     tModel Category: The classification and the corresponding code value and its category name.

   On this page, you can:

   • Browse OracleAS UDDI Registry to look for categories in which to register Web Services: Click Browse UDDI Registry.

   • Add categories to which either the Web Services or tModel are to be registered: Click Add Another Row.

   • Remove categories to which the Web Services and tModel are registered: Click Delete.

8. 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 page refreshes with the original set of values for all selections as if you had just begun your current session.

To update other published Web Services for the same category, at the top of the Web Service Details page, select the Web Services: Classification_Name link to return to the desired Web Services:Classification_Name page. The following illustration shows the Web Service Details page:

Description of the illustration uddi_ws_class.gif

When you return to the desired Web Services:Classification_Name page, select another Web Service to view in more detail, make any necessary changes, and finally click Apply to save your changes.

Alternatively, you can click Browse UDDI Registry to return to the UDDI Registry page, 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 the details, make any necessary changes, and finally click Apply to save your changes.

10.5.2 Using the OracleAS UDDI Registry Publishing Tool

OracleAS UDDI Registry provides a Publishing tool that enables you to create a new businessEntity, containing new businessServices and bindingTemplates, or tModel. To access the Publishing tool, enter the following URL in a browser:

http://OracleAS-host:OracleAS-port/uddi

The OracleAS UDDI Registry page is displayed.

This section uses an example that publishes a service for a Google-based search. It shows how to publish to the UDDI registry including how to create a tModel that is mapped to a WSDL interface specification and how to create a businessEntity and a businessService.

Take the following steps:

1. Click the UDDI Inquiry/Publishing tool link. Then, on the OracleAS UDDI Registry: Searching and Browsing Tool page, click Publishing Tool.

2. On the Log Into Publishing Service page, enter the user name and password for the uddi_publisher user and click Login. (See Table 10-2 for default passwords.)

   The Publishing Tool page is displayed, as shown in the following figure:

   
   Description of the illustration uddi_pub.gif
   
   

3. In the Publishing Tool page, you can create:

   • A new businessEntity

   • A new tModel

   The first step in registering a Web service in OracleAS UDDI Registry is to create a tModel. This example creates a tModel that represents a Google-compatible service.

   To create a new tModel, click tModel. The Publish tModel page is displayed.

4. In the Basic information section, specify the following information:

   1. For Name, specify a name so that this tModel can be located. For example, enter urn:google.com:search-interface.

   2. For Description, specify a description of the tModel, such as Google search interface.

   3. For Overview Document URL, specify the URL to the interface specification, typically a WSDL document. In this case, Google provides a WSDL document, http://api.google.com/GoogleSearch.wsdl.

   4. For Overview Document Description, enter a description of the overview document.

5. In the Category section, you categorize the tModel, in this case as a WSDL-based interface. To find information about the tModel key and key name and value, click the browse category icon at the end of the first row. The Category Browsing page is displayed.

   Take the following steps:

   1. Select uddi-org:types and click Browse.

      The Classification Tree for this selection is displayed.

   2. Click Specification for a Web Service. The Classification Tree for this selection is displayed, as shown in the following figure:

      
      Description of the illustration uddi_cat.gif
      
      

   3. In the row Specification for a Web Service described in WSDL, click the Select icon.

   In the Publish tModel page, the information you selected is automatically entered into the Category section. Now, it contains the following information:

   • For tModel Key: uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4

   • For Key Name: Specification for a Web Service described in WSDL

   • For Key Value: wsdlSpec

6. The Identifier section specifies identifying information, such as from the D-U-N-S or Thomas Register systems (see "Support for Standard Classification and Identifier Systems" for more information). For this example, leave this section blank.

   The following figure shows the Publish tModel page:

   
   Description of the illustration uddi_pub_tmodel.gif
   
   

7. Click the Publish button to publish the tModel. The TModel Details page is displayed, as shown in the following figure:

   
   Description of the illustration uddi_tm_detail.gif
   
   

   Note that the key (UUID:B960F57E-54BF-4DB8-BC36-F2802FE6BEF0) for this tModel is randomly assigned by the registry.

8. Click the Publish link at the bottom of the page to return to the Publishing Tool page.

9. Create a businessEntity, which contains details about the business, such as the name, contacts, and categories with which the businessEntity is associated. Click business entity (or service provider). The Publish Business Entity (Service Provider) page is displayed.

   If a businessEntity already exists, you do not need to create a new entity. In the Publishing Tool page, click the link to the existing businessEntity. Then, proceed to Step 15.

10. In the Business Details section of the Publish Business Entity (Service Provider) page, specify the following information:

    1. For Name, specify a name so that this business can be located. For example, enter Google Service Provider.

    2. For Description, specify a description of the business.

11. In the Contacts section, enter information that you want to appear in the UDDI registry. Specify information for the following fields:

    1. For name, specify the name of a contact.

    2. For voice, specify a voice mail number.

    3. For email, specify an email address.

    4. For address, specify a mailing address.

12. In the Category section, add any categories with which the business should be associated. For this example, use the ISO-3166 geographic taxonomy to provide geographic categorization of the business.

    To find information about the tModel key and key name and value of the category, click the browse category icon at the end of the first row. The Category Browsing page is displayed. Then, take the following steps:

    1. Select iso3166 and click Browse. The Classification Tree for this selection is displayed.

    2. Drill down to select the geographic category. For this example, click World, click United States, and then click the select icon for New Hampshire.

    In the Publish Business Entity page, the information you selected is automatically entered into the Category section. Now, it contains the following information:

    • For tModel Key: uuid:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88

    • For Key Name: New Hampshire.

    • For Key Value: US-NH.

13. The information for the Identifier section is optional. For this example, leave it blank.

    The following figure shows the Publish Business Entity (Service Provider) page:

    
    Description of the illustration uddi_pub_biz.gif
    
    

14. Click Publish to publish the business. The Business Details page is displayed:

    
    Description of the illustration uddi_biz_detail.gif
    
    

    Note that the Business Key and the Discovery URL are generated by OracleAS UDDI Registry. With the Discovery URL, you can retrieve the businessEntity using the HTTP Get method.

15. In the Services section of the Business Details page, click the icon to the right of Services to enter information about the businessServices offered by the businessEntity and the categorization of the service. The Publish Business Service page is displayed.

16. In the Basic information section, specify the following information:

    1. The key for the business is automatically entered in Owning business.

    2. For Name, enter a name for the businessService.

    3. For Description, specify a description of the businessService.

17. In the Category section, add any categories to detail the intended use of this service. For this example, add a category from the NAICS taxonomy to specify that that category is an online search tool.

    To find information about the tModel key and key name and value of the category, click the browse category icon at the end of the first row. The Category Browsing page is displayed. Then, take the following steps:

    1. Select naics and click Browse. The Classification Tree for this selection is displayed.

    2. Drill down to select the category. Click Information, then Information Services and Data Processing Services, then Information Services, and Other Information Services. Then, click the Select icon for On-Line Information Services.

    In the Publish Business Service page, the information you selected is automatically entered into the Category section. Now, it contains the following information:

    • For tModel Key: uuid:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2

    • For Key Name: On-Line Information Services

    • For Key Value: 514191

    The following figure shows the Publish Business Service page:

    
    Description of the illustration uddi_pub_serv.gif
    
    

18. Click the Publish button to publish the service. The Service Details page is displayed, as shown in the following figure:

    
    Description of the illustration uddi_serv_detail.gif
    
    

19. Create a bindingTemplate, which contains details of how and where the service provided by this businessService is accessed. On the Service Details page, click the icon to the right of Binding Details.

20. In the Publish Binding Template page, OracleAS UDDI Registry automatically fills in the field Owning Service Key with the key for the service you just created. In the Basic information section, enter the following information:

    • For Description, specify a description for the bindingTemplate.

    • For Access Point, specify the access point for accessing the service. In this case, review the source code for http://api.google.com/GoogleSearch.wsdl to find the access point. The WSDL file contains the following:

      <soap:address location="http://api.google.com/search/beta2"/>
      
      

      Enter http://api.google.com/search/beta2 as the Access Point.

    • For Access Point URL Type, select HTTP.

    The following figure shows the Publish Binding Template page:

    
    Description of the illustration uddi_pub_bind.gif
    
    

21. Click Publish to publish the bindingTemplate. The Binding Details page is displayed, as shown in the following figure:

    
    Description of the illustration uddi_bind_detail1.gif
    
    

22. Click the icon to the right of Interfaces implemented to add a new interface reference.

    The Publish Interface Reference page is displayed.

23. On this page, OracleAS UDDI Registry automatically fills in the Binding Key field. Click the Search a suitable tModel icon, which is at the end of the Interface (tModel) Key line.

    The Find tModel page is displayed.

24. For tModel Name, enter the beginning of the name of the tModel you created, for example, %urn%google%. The following figure shows the Find tModel page:

    
    Description of the illustration uddi_step1.gif
    
    

25. Click Search.

26. The tModel you created earlier is returned. Click Select.

    The Publisher Interface Reference page is displayed. The tModel Key is automatically entered in the Interface (tModel) key field of the page.

27. For Overview Document URL, enter the URL for the interface specification. In this case, enter http://api.google.com/GoogleSearch.wsdl, as shown in the following figure:

    
    Description of the illustration uddi_step2.gif
    
    

28. Click the Publish button. The Binding Details page is displayed. As the following figure shows, it now contains information about the implemented interfaces:

    
    Description of the illustration uddi_bind_detail.gif
    
    

10.5.3 Using the OracleAS UDDI Registry Publishing API

The OracleAS UDDI Registry Publishing API lets consumers (programmers), following authentication, publish Web Services by providing save and delete calls for each of the five key UDDI data structures (businessEntity, businessService, bindingTemplate, tModel, and publisherAssertion).

The Publishing API, part of the UDDI Client API, allows programmers to publish Web Services using the Java language. Programs can be written in any language, using SOAP to publish Web Services. The Java API is provided as a convenience for Java programmers.

The Publishing API is located in the Oracle Application Server installation directory, ${ORACLE_Home}/uddi/ for UNIX and %ORACLE_Home_ORACLE%\uddi\ for Windows. The API documentation can be found in the Oracle Application Server Web Services UDDI Client API Reference Javadoc.

A set of sample demonstration files (uddidemo.zip) are located on the Oracle Technology Network (OTN) Web site at:

http://www.oracle.com/technology/tech/webservices/htdocs/uddi

UddiPublishingExample.java Example

The uddidemo.zip file contains 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 OracleAS UDDI Registry client library.

The program example does the following:

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

  SoapHttpTransportLiaison transport = new OracleSoapHttpTransportLiaison();
  
  

• Sets the proxy information for the transport if the system properties http.proxyHost and http.proxyPort are set. These properties can be set on the command line. If these properties are not set, this command has no effect.

  setHttpProxy((SoapHttpTransportLiaison)transport);
  
  

• Uses a SoapTransportLiaison instance and the URL of a UDDI publishing registry to initialize an instance of UddiClient, which connects to the specified OracleAS UDDI Registry. The UddiClient instance is the primary interface by which clients send requests to OracleAS UDDI Registry. Authentication is done using the UDDI get_authToken message in this example.

  SimpleAuthenticationLiaison auth = 
              new SimpleAuthenticationLiaison(szUserName, szPassword);
  UddiClient uddiClient = new UddiClient(null, szPublishingUrl, 
                                         transport, auth);
  

  
  

  Note: The UddiClient instance, by default, operates as a UDDI v2 client (the latest release supported). If a specific release is needed, the release can be specified, either through another constructor, or by the JVM property oracle.uddi.client.defaultVersion.

  
  

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

  UddiClient.authenticate();
  
  

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

  UddiElementFactory uddiEltFactory = uddiClient.getUddiElementFactory();
  
  

• 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");
  
  

• 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");
  
  

• In the tModel 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 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("soapSpec");
  krTm1.setKeyValue("soapSpec");
  
  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.", "en");
  
  

  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", "en");
  
  

  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 bindingTemplate data structure that represents 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 bindingTemplate 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 bindingTemplate 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 contained 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:");
  
  bESaved.setName("The ACME search Inc.", "en");
  BusinessEntity bEUpdated = uddiClient.saveBusiness(bESaved);
  
  

• 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();
  

UddiPublisherAssertionExample.java Example

The uddidemo.zip file contains a Java program file, UddiPublisherAssertionExample.java, which provides Java programmers with a starting point that demonstrates the key constructs and the sequence in using the OracleAS UDDI Registry client library for publisher assertion-related operations. A publisherAssertion, which is a UDDI v2 feature, is an assertion made by a publisher who is expressing a particular fact about a business registration and its relationships to other business data within OracleAS UDDI Registry. A publisherAssertion is used to establish visible relationships between registered data. Once completed, a set of assertions can be seen by the general inquiry message named findRelatedBusinesses. The program example does the following:

• Initializes instances of two UddiClients.

  UddiClient uddiClient1 = createUddiClient(szInquiryUrl, 
                                 szPublishingUrl, szUserName1, szPassword1);
  UddiClient uddiClient2 = createUddiClient(szInquiryUrl, szPublishingUrl,
                                 szUserName2, szPassword2);
  DispositionReport dispositionReport = null;
  
  

• Creates the businessEntity data structures to be used.

  String bEKey1 = createBusinessEntity(uddiClient1, 
                         "bE1 - UddiPublisherAssertionExample");
  String bEKey2 =  createBusinessEntity(uddiClient2, 
                         "bE2 - UddiPublisherAssertionExample");
  
  

• Creates, for uddiClient1, a publisherAssertion that represents a peer-to-peer relationship from bE1 to bE2.

  System.out.println("");
  System.out.println("uddiClient1 attempts to create a peer-to-peer relationship ");
  System.out.println("from bE1 to bE2...");
  dispositionReport = uddiClient1.addPublisherAssertion
             (createPeerToPeerPublisherAssertion(uddiClient1, bEKey1, bEKey2));
  System.out.println("Done.");
  
  

• Makes a query for uddiClient1 for relationships yet to be established; that is, looking for those relationships that the toKey side has not yet acknowledged.

  AssertionStatusReport assertionStatusReport1 = 
          uddiClient1.getAssertionStatusReport
                    (AssertionStatusItem.COMPLETION_STATUS_TOKEY_INCOMPLETE);
  printOutXml("pending relationships for uddiClient1: case toKey incomplete", 
                assertionStatusReport1);
  
  

• Makes a query for uddiClient2 for relationships yet to be established; that is, looking for those relationships that the toKey side has not yet acknowledged.

  AssertionStatusReport assertionStatusReport2 =
    uddiClient2.getAssertionStatusReport(AssertionStatusItem.COMPLETION_STATUS_TOKEY_INCOMPLETE);
  printOutXml("pending relationships for uddiClient2: case toKey incomplete", 
               assertionStatusReport2);
  
  

• Shows uddiClient2 agreeing to the peer-to-peer relationship requested by creating a publisherAssertion.

  System.out.println("");
  System.out.println("uddiClient2 agrees to the peer-to-peer relationship ");
  System.out.println("from bE1 to bE2");
  dispositionReport = uddiClient2.addPublisherAssertion
          (createPeerToPeerPublisherAssertion(uddiClient2, bEKey1, bEKey2));
  System.out.println("Done.");
  
  

• Makes another query for uddiClient2 for relationships yet to be established to see if there are other peer-to-peer relationships to be established. There are no more pending relationships to be established.

  AssertionStatusReport assertionStatusReport2After = 
            uddiClient2.getAssertionStatusReport
            (AssertionStatusItem.COMPLETION_STATUS_TOKEY_INCOMPLETE);
  printOutXml("pending relationships for client2: toKey incomplete (should be
    none)", assertionStatusReport2After);
  
  

• Finds related businesses that have established peer-to-peer relationships (that have published assertions) by calling the general inquiry message findRelatedBusinesses.

  RelatedBusinessesList rbList = uddiClient1.findRelatedBusinesses(bEKey1,
                                   createPeerToPeerKeyedReference(uddiClient1),
                                   null);
  printOutXml("find all businesses that are peers to " + bEKey1, rbList);
  
  

• Deletes a publisher assertion relationship between bE1 and bE2, owned by uddiClient1.

  System.out.println("");
  System.out.println("Delete a publisherAssertion...");
  dispositionReport = uddiClient1.deletePublisherAssertion
                (createIdentityPublisherAssertion(uddiClient1,bEKey1, bEKey2));
  System.out.println("Done");
  
  

• Shows another way of deleting all publisher assertion relationships owned by uddiClient1 by using the setPublisherAssertions call.

  System.out.println("");
  System.out.println("Delete all publisherAssertions of uddiClient1 ");
  System.out.println("by using setPublisherAssertions...");
  publisherAssertions = uddiClient1.setPublisherAssertions(null);
  printOutXml("Done. The current list:", publisherAssertions);
  

10.6.1 Using the Command-Line Tool uddiadmin.jar

As administrator, you perform many administrative operations using the command-line tool uddiadmin.jar.

The command-line tool uddiadmin.jar is located in the ${ORACLE_Home}/uddi/lib/uddiadmin.jar file for UNIX and in the %ORACLE_Home_ORACLE%\uddi\lib\uddiadmin.jar file for Windows. In general, the command-line tool uses the following command format:

java -jar uddiadmin.jar  registry_admin_URL username password
 [-verbose] options_and_their_parameters

In the format, the parameters have the following meanings:

• registry_admin_URL: A URL pointing to the administration end point:

  http://OracleAS-host:OracleAS-port/uddi/admin
  
  

• username: The default user name is ias_admin. The username must belong to the uddiadmin group.

• password: The default password is ias_admin123.

• -verbose: This causes stack trace information to be printed out when an exception is encountered.

• options_and_their_parameters: Any of the options listed in Table 10-3 and their parameters.

Table 10-3 shows the command-line options for the command-line tool uddiadmin.jar.

For reference information about these options, see "Command-Line Options for the uddiadmin.jar Tool".

10.6.2 Configuring the Server

You use the following options of the command-line tool uddiadmin.jar to configure the server:

• getProperties: Lists the current registry configuration parameters. The following shows an example:

  java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password  [-verbose] -getProperties
  
  

  See "getProperties" for more information on this option.

• setProperty: Changes the value of the named configuration parameter. The OracleAS UDDI Registry J2EE application needs to be restarted for the parameters to take effect.

  
  

  Caution: Be very careful when using the setProperty option to change server configuration property values. Making an incorrect property setting could cause severe damage to the integrity of the registry.

  
  

  With the setProperty option, you can specify server configuration as described in "Modifying Properties at Installation or First-Use".

10.6.3 Managing Users

OracleAS UDDI Registry uses Oracle Internet Directory (OID) of the OracleAS Infrastructure as the default user repository. This is achieved through the use of LDAP-based provider of OC4J Java Authentication and Authorization Service (JAAS).

UDDI-specific OID groups are located under the cn=uddi_groups subtree of the group subtree of the OID default subscriber, and users are located under the user subtree of the OID default subscriber.

Table 10-4 summarizes the groups of UDDI users.

In addition to the default UDDI groups, there are also a set of default groups for user quota purposes. As administrator, you can add, update, or remove the groups, based on the specific user quota policy that you may need to enforce.

By default, the users listed in Table 10-5 are created during installation. You can add users to, or remove users from, these groups.

Generic user management, such as creation, deletion, suspension, is handled by OID and its Oracle Delegated Administration Services. Refer to Oracle Identity Management Guide to Delegated Administration for more information.

User management, including operations such as creation, deletion, suspension, role management, is handled by the JAAS service of OC4J. Refer to Oracle Application Server Containers for J2EE Services Guide for more information.

However, to find out the authorized name of a user, use the getUsers or getUserDetail option of the uddiadmin.jar command-line tool:

• getUsers: Lists all existing users who have entities in the registry. For example:

  java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password  
  [-verbose] -getUsers
  
  

  See "getUsers" for more information on this option.

• getUserDetail: Retrieves the details of the named user, currently the authorized name of each user. For example:

  java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password  
  [-verbose] -getUserDetail username
  
  

  See "getUserDetail" for more information on this option.

10.6.4 Enforcing Quotas

OracleAS UDDI Registry provides a mechanism to enforce the number of entities a publisher can own. A publisher can own at most a specific number of tModel, publisherAssertion, businessEntity, and businessService data structures for each businessEnitity, and bindingTemplate data structures for each businessService, depending upon the quota group associated with the publisher. The quota group is guided by the user group to which the publisher is assigned.

OracleAS UDDI Registry uses a group-based mechanism for assigning quota limits to a publisher. When a new publisher is added, the OracleAS UDDI Registry administrator must associate the publisher with a quota group. Table 10-6 shows the predefined quota groups and quota limits for each entity that a publisher can own.

uddi_unlimited_quota_group

uddi_lowlimits_quota_group

<Implicit>
UDDI_Administrators

The explicit Default quota group cannot be deleted. Users who are OracleAS UDDI Registry administrators are always assigned unlimited quota.

As OracleAS UDDI Registry administrator, you can also update a quota group, add a new quota group, delete a quota group, view the lists of quota groups and their quota limits, and associate a publisher with a quota group. The following sections describe each of these administrator tasks.

java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password
 -setRoleQuotaLimits roleName maxBE maxBSperBE maxBTperBS maxTM maxPA

java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password
 -getRoleQuotaLimits

10.6.5 Managing Administrative Entities

Use the following options of the command-line tool uddiaddmin.jar for administrative entity management:

• deleteEntity: 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.

  See "deleteEntity" for reference information about this option.

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

  See "destroyTModel" for reference information about this option.

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

  See "changeOwner" for reference information about this option.

10.6.6 Importing Entities

To import entities from a file, you use the import option of the command-line tool uddiaddmin.jar. You can import all businessEntity, tModel, and publisherAssertion data structures in the named file.

To import the businessEntity data structure, the named file for importing should contain a UDDI businessDetail XML document.

To import tModel data structures, the named file should contain a UDDI tModelDetail XML document. By importing them, entity keys (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 option 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, you should be careful in evaluating the source of the entities to ensure there will not be a collision in entity keys.

For importing a publisherAssertion, two Boolean values are required. These Boolean values are used to indicate from which side (or both sides, when two Boolean values are true) the publisherAssertion is going to be inserted.

You can import in single mode, using the option -s, which does not allow partial success (some entities are imported and some are not, due to some error condition), or in multiple mode (-m), which does allow partial success.

The following shows the format of the import option:

-import [-s|-m] {-businesses filename | -tmodels filename |
 -assertions filename  -fromBusinessCheck {true|false}
 -toBusinessCheck {true|false} }

For example, the contents of the publisherAssertion file, assert.xml, could contain the following:

 <publisherAssertion generic="2.0" xmlns="urn:uddi-org:api_v2">
   <fromKey>22A5A0304C64-11D8-AB19-B8A03C50A862</fromKey>
   <toKey>27CC6702-7F6E-4395-A0B8-97D2FFB5F7634  </toKey>
   <keyedReference tModelKey="UUID:807A2C6A-EE22-470D-ADC7-E0424A337C03"
                   keyName="subsidiary"
                   keyValue="parent-child" />
 </publisherAssertion>

Then, to import the publisherAssertion data structure, use the following command:

java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password
 -import -s -assertions assert.xml -fromBusinessCheck true
 -toBusinessCheck true

10.6.7 Setting Operational Information

You can use the setOperationalInfo option to set some operational information of entities, such as the operator name, authorized name, or timestamp of a businessEntity or tModel specified by a key, for example, following an import operation.

The setOperationalInfo option uses two syntax formats:

• To change the operator name, the authorized name, or the timestamp, or all three, of a businessEntity or tModel specified by a key, use the following format:

  -setOperationalInfo {-businessKey key | -tModelKey key}
  [-newOperator OperatorName] [-newAuthorizedname authName] [-newTime timestamp]] 
  
  

  Any combination of operator name, authorized name, or timestamp of a businessEntity or tModel data structure is allowed.

• To change only the timestamp of a businessService or bindingTemplate data structure, use the following format:

  -setOperationalInfo {-serviceKey key | -bindingKey key} [-newTime timestamp] 
  
  

See "setOperationalInfo" for more information on this option.

10.6.8 UDDI Replication

OracleAS UDDI Registry allows administrators to create a logical registry that comprises one or more OracleAS UDDI Registry implementations, as well as UDDI implementations from other vendors that also implement the UDDI v2 Replication Specification.

This section briefly describes the data replication process and the program interface required to achieve complete data replication among UDDI operator nodes that form a UDDI service. UDDI replication ensures that all operator nodes see all the changes that have originated at individual operator nodes. In addition, any inquiries made at any operator node within the UDDI service yield results consistent to those made at any other operator node within the UDDI service, hence the logical OracleAS UDDI Registry.

For detailed technical descriptions of concepts and definitions involved with UDDI replication, including replication processing, how to bring new UDDI operators online, checking and validation of replicated data, see the UDDI v2.0.3 Replication Specification. The sections that follow describe the Oracle implementation of UDDI replication.

10.6.9 Registry-Based Category Validation

OracleAS UDDI Registry can perform a spell-check form of category value validation. As administrator, you can add or remove the set of categories that will be validated by the registry. Refer to the UDDI v2 specification for more information.

10.6.10 External Validation

Third parties can register new category and identifier schemes, and then control the validation process used by OracleAS UDDI Registry to perform external validation or checking. This enables a third-party category provider to validate the UDDI entities to be saved when the entity is categorized, or identified with the category, by providing a validate_values SOAP Web service.

The operator that calls the validate_values service passes a businessEntity, a businessService, or a tModel element as the sole argument to this call. This is the same data that is being passed within a save_business, save_service, or save_tModel API call. External validation is performed for any third-party category provider and identifier scheme that is classified as checked. A tModel element marked as checked asserts that it represents a categorization, identifier, or namespace tModel element that has a properly registered validation service.

If no error is found, the response is a dispositionReport message returning an errorCode value of E_success and an errno value of 0. If any error is found, or the called service needs to signal that the information being saved is not valid based on the validation algorithm chosen by the external service provider, then the service should raise a SOAP Fault and indicate either an errorCode value of E_invalidValue or E_valueNotAllowed. In either case, the error text indicates the keyedReference data that is being rejected, and the reason why.

Use the command-line tool uddiadmin.jar with the setProperty option to:

• Enable external validation

• Add an externally validated category to the registry

• Remove an externally validated category from the registry

java -jar uddiadmin.jar http://OracleAS-host:port/uddi/admin username password
 -setProperty oracle.uddi.server.externalValidation=true

10.6.11 Performance Monitoring and Tuning

On the back end of an Oracle database, UDDI servlets and the associated JDBC connection pools can be monitored using Oracle Enterprise Manager 10g 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

10.6.12 Data Backup and Restore Operations

You can back up and restore UDDI Registry data by using the standard Oracle database back up and restore operations. See the Oracle Backup and Recovery Concepts, part of the Oracle Database documentation set.

10.6.13 Database Configuration

The following sections describe some database-specific configuration information.

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

10.6.14 Transport Security

In general, the Inquiry API does not require authentication. However, if the inquiry end point needs to be protected, transport-level authentication, such as HTTP BASIC authentication and HTTPS Secure Sockets Layer (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 Oracle Application Server Containers for J2EE Services Guide and Oracle Application Server Containers for J2EE User's Guide for more information about security roles and related security configuration.

For the publishing end-point URL, consider allowing only HTTPS access. To disable HTTP access, edit the web.xml file of the orauddi application to enforce data confidentiality and make adjustments to HTTP servers. 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>

Refer to the chapter on security in Oracle Application Server Containers for J2EE User's Guide and to Oracle Application Server Containers for J2EE Services Guide for more information.

Similarly, you can set up HTTPS access for the administrative end point and the UDDI Replication end point in the same way.

10.7.1 Microsoft SQL Server

The following sections describe installation and configuration information with SQL Server.

osql -S server -U sa -P sa  -i wurcreatedb_mssql.sql

"Login failed for user 'sa'. Reason: Not associated with a trusted SQL Server Server Connection."

osql -S server -U user -P password -d database -i wurinst_mssql.sql

osql -S server-machine -U uddisys -P uddisys -d uddisys -i wurinst_mssql.sql

<data-source
    class="com.evermind.sql.DriverManagerDataSource"
    name="jdbc/OracleUddi"
    location="jdbc/OracleUddi"
    connection-driver="com.oracle.ias.jdbc.sqlserver.SQLServerDriver"
    username="uddisys"
    password="uddisys"
url="jdbc:oracle:sqlserver://server:1433;SelectMethod=cursor;User=uddisys;Password=uddisys"
/>

10.7.2 IBM DB2

The following sections describe installation and configuration information for OracleAS UDDI Registry relative to IBM DB2.

db2 -t +p < wurcreatedb_db2.sql

db2 -t +p < wurinst_db2.sql

<data-source
    class="com.evermind.sql.DriverManagerDataSource"
    name="jdbc/OracleUddi"
    location="jdbc/OracleUddi"
    connection-driver="com.oracle.ias.jdbc.db2.DB2Driver"
    username="uddisys"
    password="uddisys"
url="jdbc:oracle:db2://servername:50000;databaseName=UDDISYS;
PackageName=JDBCPKG;DynamicSections=512;
CreateDefaultPackage=TRUE;ReplacePackage=true"
/>

http://OracleAS-host:port/uddi/inquiry

url="jdbc:oracle:db2://servername:50000;databaseName=uddisys;
PackageName=JDBCPKG;DynamicSections=512;
CreateDefaultPackage=TRUE;ReplacePackage=true"

url="jdbc:oracle:db2://servername:50000;databaseName=uddisys;
PackageName=JDBCPKG;DynamicSections=512"

http://OracleAS-host:port/uddi/inquiry

10.7.3 Other Oracle Database (Non-Infrastructure)

The following sections describe installation and configuration information for an Oracle database that is not an OracleAS Infrastructure database.

sqlldr userid=uddisys/uddisys control=naics-97.ctl
sqlldr userid=uddisys/uddisys
   control=unspsc-73.ctl
sqlldr userid=uddisys/uddisys  control=iso3166-99.ctl

sqlldr userid=uddisys/uddisys control=iso3166-99-ascii.ctl

<data-source
    class="oracle.jdbc.pool.OracleConnectionCacheImpl"
    name="jdbc/OracleUddi"
    location="jdbc/OracleUddi"
    connection-driver="oracle.jdbc.driver.OracleDriver"
    username="uddisys"
    password="uddisys"
url="jdbc:oracle:thin:@servername:1521:oracle sid"
/>