Getting started
A simple sample
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 IBM 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 IBM JAXR Provider for UDDI are contained within the archive jaxruddi.jar, located in the install_root/lib directory. When using the JAXR API from within a J2EE application running under WebSphere Application Server Version 6.0, 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 install_root/lib directory.
javax.xml.registry.ConnectionFactory
To use the IBM 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 IBM JAXR Provider for UDDI does not support lookup of the ConnectionFactory via JNDI.
javax.xml.registry.Connection Properties
Property | Description |
javax.xml.registry.queryManagerURL | The URL of the IBM WebSphere 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 IBM WebSphere 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 IBM 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 IBM 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 when WebSphere 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)
java.security.Security.addProvider(new com.ibm.jsse.JSSEProvider());
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 IBM UDDI Version 3 Registry. If using the IBM JAXR Provider to access an IBM UDDI Version 2 Registry, only the tModels corresponding to NAICS 1997, UNSPSC 3.1 and ISO3166 are available.
Custom internal taxonomies
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
<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. |
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,#
<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. |
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 IBM 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.