WebSphere Application Server Network Deployment, Version 6.0.x   Operating Systems: AIX, HP-UX, Linux, Solaris, Windows
             [TIP: Focusing the table of contents and search results]

JAXR for UDDI - getting started and further information

A sample program demonstrates how to get started with the Java API for XML Registries (JAXR). This topic also discusses class libraries, authentication and security, internal taxonomies, and logging and messages.

A simple sample

The following sample program shows how to obtain the ConnectionFactory instance, create a Connection to the registry and save an Organization in the registry.

import java.net.PasswordAuthentication;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashSet;
import java.util.Properties;
import java.util.Set;

import javax.xml.registry.BulkResponse;
import javax.xml.registry.BusinessLifeCycleManager;
import javax.xml.registry.Connection;
import javax.xml.registry.ConnectionFactory;
import javax.xml.registry.JAXRException;
import javax.xml.registry.RegistryService;
import javax.xml.registry.infomodel.Key;
import javax.xml.registry.infomodel.Organization;

public class JAXRSample
{
    public static void main(String[] args) throws JAXRException
    {
        //Tell the ConnectionFactory to use the JAXR Provider for UDDI
        System.setProperty("javax.xml.registry.ConnectionFactoryClass", 
                                                        "com.ibm.xml.registry.uddi.ConnectionFactoryImpl");
        ConnectionFactory connectionFactory = ConnectionFactory.newInstance();

        //Set the URLs for the UDDI inquiry and publish APIs.
        //These must be the URLs of the UDDI version 2 APIs. 
        Properties props = new Properties();
        props.setProperty("javax.xml.registry.queryManagerURL", "http://localhost:9080/uddisoap/inquiryapi");
        props.setProperty("javax.xml.registry.lifeCycleManagerURL", "http://localhost:9080/uddisoap/publishapi");
        connectionFactory.setProperties(props);

        //Create a Connection to the UDDI registry accessible at the above URLs.
        Connection connection = connectionFactory.createConnection();

        //Set the user ID and password used to access the UDDI registry.
        PasswordAuthentication pa = new PasswordAuthentication("Publisher1", new char[] { 'p', 'a', 's', 
                                                                                  's', 'w', 'o', 'r', 'd' });
        Set credentials = new HashSet();
        credentials.add(pa);
        connection.setCredentials(credentials);

        //Get the javax.xml.registry.BusinessLifeCycleManager interface, which contains
        //methods corresponding to UDDI publish API calls.
        RegistryService registryService = connection.getRegistryService();
        BusinessLifeCycleManager lifeCycleManager = registryService.getBusinessLifeCycleManager();

        //Create an Organization (UDDI businessEntity) with name "Organization 1".
        Organization org = lifeCycleManager.createOrganization("Organization 1");

        //Add the Organization to a Collection, ready to be saved in the UDDI registry. 
        Collection orgs = new ArrayList();
        orgs.add(org);

        //Save the Organization in the UDDI registry.
        BulkResponse bulkResponse = lifeCycleManager.saveOrganizations(orgs);

        //Obtain the Organization's Key (the UDDI businessEntity's businessKey) from the response.
        if (bulkResponse.getExceptions() == null)
        {
            //1 Organization was saved, so 1 key will be returned in the response collection
            Collection responses = bulkResponse.getCollection();
            Key organizationKey = (Key)responses.iterator().next();
            System.out.println("\nOrganization Key = " + organizationKey.getId());
        }
    }
}

Classpath

The class libraries of the JAXR Provider for UDDI are contained within the archive jaxruddi.jar, located in the app_server_root/lib directory. When using the JAXR API from within a J2EE application running under WebSphere Application Server, all required classes will automatically be on the classpath. When using the JAXR API from outside this environment, the following jars must be on the Java classpath: bootstrap.jar, jaxruddi.jar, j2ee.jar, soap.jar and uddi4jv2.jar, which are all located in the app_server_root/lib directory.

javax.xml.registry.ConnectionFactory

To use the JAXR Provider for UDDI, the name of the ConnectionFactory implementation class must first be specified by setting the System Property “javax.xml.registry.ConnectionFactoryClass” to “com.ibm.xml.registry.uddi.ConnectionFactoryImpl”. Failure to specify this will result in the value defaulting to “com.sun.xml.registry,common.ConnectionFactoryImpl”, which will not be found. This will result in a JAXRException when the ConnectionFactory.newInstance() method is called. The JAXR Provider for UDDI does not support lookup of the ConnectionFactory via JNDI.

javax.xml.registry.Connection Properties

Connection specific properties must be specified by setting a java.util.Properties object on the JAXR ConnectionFactory before obtaining a Connection. The JAXR specification defines the full list of these properties. The table below lists the three most important properties, and what values they should take in order to use the JAXR Provider for UDDI to access the UDDI registry. The only required Connection property is “javax.xml.registry.queryManagerURL”, however it is recommended that “javax.xml.registry.lifeCycleManagerURL” is also set, and that the default value of “javax.xml.registry.security.authenticationMethod” is understood. The rest of the Connection properties defined in the JAXR specification are optional, and their values are not specific to the UDDI registry. The JAXR Provider for UDDI does not define any additional provider-specific properties.
Property Description
javax.xml.registry.queryManagerURL The URL of the UDDI registry’s inquiry API for UDDI Version 2. Typically this will be of the form: “http://<hostname>:<port>/uddisoap/inquiryapi”. This property is required.
javax.xml.registry.lifeCycleManagerURL The URL of the UDDI registry’s publish API for UDDI v2. Typically this will be of the form: “http://<hostname>:<port>/uddisoap/publishapi”. If this property is not specified, it defaults to the value of the javax.xml.registry.queryManagerURL property, however the UDDI registry will typically have different URLs for the inquiry and publish APIs, and it is recommended to specifiy both properties.
javax.xml.registry.authenticationMethod The method of authentication to use when authenticating with the registry. This may take one of two values, “UDDI_GET_AUTHTOKEN” and “HTTP_BASIC”. The default value is “UDDI_GET_AUTHTOKEN” if none is specified. See section Authentication and Security below for more information.

Authentication and security

Authentication

The javax.xml.registry.authenticationMethod Connection property tells the JAXR Provider which method to use when authenticating with the UDDI registry. The two supported values of this property are “UDDI_GET_AUTHTOKEN” and “HTTP_BASIC”. The JAXR Provider for UDDI does not support the “CLIENT_CERTIFICATE” or “MS_PASSPORT” methods of authentication. If this property is not set, the default authentication method is “UDDI_GET_AUTHTOKEN”.

UDDI_GET_AUTHTOKEN

The JAXR Provider uses the UDDI V2 get_authToken API to authenticate with the registry. The get_authToken call is made automatically by the JAXR Provider when the Connection credentials are set, and the UDDI V2 authToken returned by the call is saved by the JAXR Provider for use on subsequent UDDI publish API calls.

HTTP_BASIC

The JAXR Provider uses HTTP basic authentication to authenticate with the registry. This is supported by WebSphere Application Server when global security is on. No UDDI V2 get_authToken API call is made, instead the username and password are sent in the HTTP headers using HTTP basic authentication every time a UDDI API call is made (both inquiry and publish). If the UDDI registry does not require HTTP basic authentication, the credentials are ignored.

The JAXR Provider uses UDDI Version 2 SOAP inquiry and publish APIs. These APIs are protected as described in Access control for UDDI registry interfaces.

USING SSL (Secure Sockets Layer)

SSL can be used to encrypt HTTP traffic between the JAXR Provider for UDDI and the UDDI registry. To use SSL, the JAXR client program should do the following:
  1. When setting the “javax.xml.registry.queryManagerURL” and “javax.xml.registry.lifeCycleManagerURL” Connection properties, specify a URL with the protocol “https” and the correct port for using SSL to access the UDDI registry. The UDDI registry’s default port for HTTPS is 9443. Often only the lifeCycleManager URL (the UDDI Publish API URL) will require SSL.
  2. Add a new Security Provider to the java.security.Security object, according to the JSSE (Java Secure Sockets Extension) implementation being used. If running under the JVM provided in WebSphere Application Server, the JSSE provided by IBM will automatically be on the classpath. Add the IBM Security Provider as follows:
    java.security.Security.addProvider(new com.ibm.jsse.JSSEProvider());
  3. Set the System property “javax.net.ssl.trustStore” to be the file name of the client trust store file. The client trust store file is a Java key store (.jks) file and must contain the server certificate of the UDDI registry. Key store files can be managed using the ikeyman tool
  4. Set the System property “javax.net.ssl.trustStorePassword”. This is the password used to open the client trust store file.
  5. If using an IBM version of JVM that is older than the level provided in this version of WebSphere Application Server, it may be necessary to set the System property “java.protocol.handler.pkgs” to “com.ibm.net.ssl.internal.www.protocol”. For more information on SSL and the ikeyman tool refer to SSL and IKEYMAN within this Information Center.

Internal taxonomies

The JAXR Provider for UDDI supplies the following internal taxonomies:
Taxonomy ClassificationScheme name (UDDI tModel name) ClassificationScheme id (UDDI Version 2 tModelKey)
NAICS 1997 ntis-gov:naics:1997 UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2
NAICS 2002 ntis-gov:naics:2002 UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2
UNSPSC 3.1 unspsc-org:unspsc:3-1 UUID:DB77450D-9FA8-45D4-A7BC-04411D14E384
UNSPSC 7 unspsc-org:unspsc UUID:CD153257-086A-4237-B336-6BDCBDCC6634
ISO3166 2003 ubr-uddi-org:iso-ch:3166-2003 UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88

The tModels corresponding to all of these taxonomies are available in the UDDI Version 3 registry. If using the JAXR Provider to access a UDDI Version 2 registry, only the tModels corresponding to NAICS 1997, UNSPSC 3.1 and ISO3166 are available.

Custom internal taxonomies

A user may supply their own custom internal taxonomies. To create a new custom internal taxonomy and make it available to the JAXR provider, follow these steps:
  1. Create a text file containing the taxonomy element data. As an example, look at the file geo-data.txt on the root of jaxruddi.jar. This is the taxonomy data file for the supplied ISO 3166 taxonomy. The first few lines are:
    geo#--#World#--
    geo#AE#United Arab Emirates#--
    geo#AF#Afghanistan#--
    geo#AG#Antigua And Barbuda#--
    geo#AI#Anguilla#--
    geo#AL#Albania#--
    geo#AM#Armenia#--
    geo#AN#Netherlands Antilles#--
    geo#AO#Angola#--
    geo#AQ#Antarctica#--
    geo#AR#Argentina#--
    geo#AR-A#Salta#AR
    geo#AR-B#Buenos Aires#AR
    
    Each line represents one element of the taxonomy, or one Concept in the taxonomy Concept tree. Each line has the form:
    <taxonomy ID>#<element value>#<element name>#<parent element value>
    Token Description
    <taxonomy ID> The taxonomy ID is the same for every element of a taxonomy.
    <element value> The Concept value (UDDI keyValue).
    <element name> The Concept name (UDDI keyName).
    <parent element value> This defines the element’s parent element in the taxonomy tree. For every element (except the root element) in the data file, there should be another line which defines the element’s parent element. The root element is denoted by defining itself as its own parent. There should be only one root element, and no parentless elements.
    # The delimiter character. This does not have to be “#” and can be defined for each taxonomy in the taxonomyConfig.properties file.
  2. Save a ClassificationScheme (UDDI tModel) in the UDDI registry to represent the new internal taxonomy. This can be done using the javax.xml.registry.BusinessLifeCycleManager.saveClassificationSchemes() method.
  3. Add the new taxonomy to the taxonomyConfig.properties file:
    1. Copy the supplied taxonomyConfig.properties file from the root of jaxruddi.jar.

      The content of the supplied taxonomyConfig.properties file is:
      naics-1997	= UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2, naics-1997-data.txt,	#
      naics-2002	= UUID:1FF729F2-1948-46CF-B660-31EC107F1663, naics-2002-data.txt,	#
      unspsc		= UUID:DB77450D-9FA8-45D4-A7BC-04411D14E384, unspsc-data.txt,    	#
      unspsc7_data	= UUID:CD153257-086A-4237-B336-6BDCBDCC6634, unspsc7-data.txt,   	#
      iso3166-2003	= UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88, iso3166-2003-data.txt,#
      
      This file has one line per supplied internal taxonomy, which is of the form:
      <taxonomy ID> = <tModelKey>,<data filename>,<data file delimiter>
      Token Description
      <taxonomy ID> This is used internally by the JAXR provider to identify each taxonomy. It does not have to be the same as the taxonomy ID in the corresponding taxonomy data file.
      <tModelKey> The tModelKey of the corresponding UDDI tModel. (The id of the corresponding JAXR ClassificationScheme).
      <data filename> The name of the corresponding taxonomy data file.
      <data file delimiter> The delimiter character used in the taxonomy data file. All supplied internal taxonomies use “#”, but user-supplied internal taxonomies may use different delimiters.
    2. Add a new line for the new taxonomy to the copy of the taxonomyConfig.properties file. Do not remove any existing taxonomies from the file as this will make them unavailable to the JAXR provider.
  4. Add the copied taxonomyConfig.properties file to the Java classpath ahead of jaxruddi.jar.
  5. If any JAXR client programs are still running that were started before the new taxonomy was added to the taxonomyConfig.properties file, a new Connection must be created in order to pick up the new taxonomy.

Important notes on internal taxonomies

Each internal taxonomy is loaded into memory once per JAXR Connection. The taxonomy’s ClassificationScheme is created when the Connection is created. At this time the associated UDDI tModel is obtained from the registry and used to populate the ClassificationScheme attributes. The taxonomy’s Concept object tree is not created until the first time the ClassificationScheme is requested by the user. All subsequent requests for the same internal taxonomy using the same Connection will return the same object tree.

Modification of the Concept object tree

Because there is only one ClassificationScheme and Concept object tree per internal taxonomy per Connection, a user should not attempt to modify programmatically any part of the Concept tree, because all future requests for this taxonomy using the same Connection will return the modified (and now possibly invalid) objects. Programmatic modification of the Concept tree will not result in any changes to the associated taxonomy data file. If a user wishes to make a change to the values in a user-defined internal taxonomy, they must first make the changes in the taxonomy data file, and then create a new Connection to pick up the changes in a new Concept tree.

Modification of the ClassificationScheme

Similarly, a user should not attempt to modify programmatically an internal ClassificationScheme, except in the case where a user wishes to modify and then save a user-defined internal ClassificationScheme. A new Connection is not required to pick up programmatic changes.

Logging and messages

UDDI4J Logging

The JAXR Provider for UDDI uses UDDI4J Version 2 to communicate with the UDDI registry. UDDI4J has its own logging which can be switched on by setting the value of the System property “org.uddi4j.logEnabled” to “true”. This outputs to the standard error log the XML request and response bodies of every UDDI request.

Trace

Entry, exit, exception, warning and debug trace is provided using commons-logging. See http://jakarta.apache.org/commons/logging/ for more information on commons-logging. Trace will only be created if the JAXR client configures it. Entry, exit and debug trace uses the debug level of logging. Exception and warning trace uses the info level of logging. Additionally, info level logging is provided before each UDDI4J request is made.

Standard error log messages

The InternalTaxonomyManager, EnumerationManager and PostalSchemeManager send warning messages to System.err if error conditions occur that do not warrant an exception, but that the user should be informed of. Examples of these are if a taxonomy data file contains an invalid line, or if a tModel corresponding to an internal taxonomy could not be found in the registry.




Related concepts
Java API for XML Registries (JAXR) provider for UDDI
Related tasks
Using the UDDI registry
Reference topic    

Terms of Use | Feedback

Last updated: Mar 8, 2007 8:14:28 PM CST
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/rwsu_jaxr.html

© Copyright IBM Corporation 2002, 2006. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)