Home
TOC Index |
Implementing a JAXR Client
This section describes the basic steps to follow in order to implement a JAXR client that can perform queries and updates to a UDDI registry. A JAXR client is a client program that can access registries using the JAXR API.
This tutorial does not describe how to implement a JAXR provider. A JAXR provider provides an implementation of the JAXR specification that allows access to an existing registry provider, such as a UDDI or ebXML registry. The implementation of JAXR in the Java WSDP itself is an example of a JAXR provider.
This tutorial includes several client examples, which are described in Running the Client Examples.
The JAXR release also includes several sample JAXR clients, the most complete of which is a Registry Browser that includes a graphical user interface (GUI). For details on using this browser, see Registry Browser.
Establishing a Connection
The first task a JAXR client must complete is to establish a connection to a registry.
Preliminaries: Getting Access to a Registry
Any user of a JAXR client may perform queries on a registry. In order to add data to the registry or to update registry data, however, a user must obtain permission from the registry to access it. To register with one of the public UDDI version 2 registries, go to one of the following Web sites and follow the instructions:
http://uddi.microsoft.com/
(Microsoft)http://uddi.ibm.com/testregistry/registry.html
(IBM)http://udditest.sap.com/
(SAP)These UDDI version 2 registries are intended for testing purposes. When you register, you will obtain a user name and password. You will specify this user name and password for some of the JAXR client example programs.
Note: The JAXR API has been tested with the Microsoft and IBM registries, but not with the SAP registry.
Creating or Looking Up a Connection Factory
A client creates a connection from a connection factory. A JAXR provider may supply one or more preconfigured connection factories that clients can obtain by looking them up using the Java Naming and Directory Interface (JNDI) API.
At this release of the Java WSDP, JAXR does not supply preconfigured connection factories. Instead, a client creates an instance of the abstract class
ConnectionFactory
:import javax.xml.registry.*; ... ConnectionFactory connFactory = ConnectionFactory.newInstance();Creating a Connection
To create a connection, a client first creates a set of properties that specify the URL or URLs of the registry or registries being accessed. For example, the following code provides the URLs of the query service and publishing service for the IBM test registry. (There should be no line break in the strings.)
Properties props = new Properties(); props.setProperty("javax.xml.registry.queryManagerURL", "http://uddi.ibm.com/testregistry/inquiryapi"); props.setProperty("javax.xml.registry.lifeCycleManagerURL", "https://uddi.ibm.com/testregistry/protect/publishapi");With the Java WSDP implementation of JAXR, if the client is accessing a registry that is outside a firewall, it must also specify proxy host and port information for the network on which it is running. For queries it may need to specify only the HTTP proxy host and port; for updates it must specify the HTTPS proxy host and port.
props.setProperty("com.sun.xml.registry.http.proxyHost", "myhost.mydomain"); props.setProperty("com.sun.xml.registry.http.proxyPort", "8080"); props.setProperty("com.sun.xml.registry.https.proxyHost", "myhost.mydomain"); props.setProperty("com.sun.xml.registry.https.proxyPort", "8080");The client then sets the properties for the connection factory and creates the connection:
connFactory.setProperties(props); Connection connection = connFactory.createConnection();The
makeConnection
method in the sample programs shows the steps used to create a JAXR connection.Setting Connection Properties
The implementation of JAXR in the Java WSDP allows you to set a number of properties on a JAXR connection. Some of these are standard properties defined in the JAXR specification. Other properties are specific to the implementation of JAXR in the Java WSDP. Table 11-1 and Table 11-2 list and describe these properties.
Table 11-1 Standard JAXR Connection Properties Property Name and Description
Data Type
Default Value
javax.xml.registry.queryManagerURL
Specifies the URL of the query manager service within the target registry provider
String
None
javax.xml.registry.lifeCycleManagerURL
Specifies the URL of the life cycle manager service within the target registry provider (for registry updates)
String
Same as the specified queryManagerURL
value
javax.xml.registry.semanticEquivalences
Specifies semantic equivalences of concepts as one or more tuples of the ID values of two equivalent concepts separated by a comma; the tuples are separated by vertical bars:
id1,id2|id3,id4
String
None
javax.xml.registry.security.authenticationMethod
Provides a hint to the JAXR provider on the authentication method to be used for authenticating with the registry provider
String
None; UDDI_GET_AUTHTOKEN
is the only supported value
javax.xml.registry.uddi.maxRows
The maximum number of rows to be returned by find operations. Specific to UDDI providers
Integer
None
javax.xml.registry.postalAddressScheme
The ID of aClassificationScheme
to be used as the default postal address scheme. See Specifying Postal Addresses for an example
String
None
You can set these properties as follows:
- Most of these properties must be set in a JAXR client program. For example:
Properties props = new Properties(); props.setProperty("javax.xml.registry.queryManagerURL", "http://uddi.ibm.com/testregistry/inquiryapi"); props.setProperty("javax.xml.registry.lifeCycleManagerURL", "https://uddi.ibm.com/testregistry/protect/publishapi"); ConnectionFactory factory = ConnectionFactory.newInstance(); factory.setProperties(props); connection = factory.createConnection();- The
postalAddressScheme
,useCache
, anduseSOAP
properties may be set in a<sysproperty>
tag in abuild.xml
file for theAnt
tool. For example:<sysproperty key="useSOAP" value="true"/>
- These properties may also be set with the
-D
option on thejava
command line.An additional system property specific to the implementation of JAXR in the Java WSDP is
com.sun.xml.registry.userTaxonomyFilenames
. For details on using this property, see Defining a Taxonomy.Obtaining and Using a RegistryService Object
After creating the connection, the client uses the connection to obtain a
RegistryService
object and then the interface or interfaces it will use:RegistryService rs = connection.getRegistryService(); BusinessQueryManager bqm = rs.getBusinessQueryManager(); BusinessLifeCycleManager blcm = rs.getBusinessLifeCycleManager();Typically, a client obtains both a
BusinessQueryManager
object and aBusinessLifeCycleManager
object from theRegistryService
object. If it is using the registry for simple queries only, it may need to obtain only aBusinessQueryManager
object.Querying a Registry
The simplest way for a client to use a registry is to query it for information about the organizations that have submitted data to it. The
BusinessQueryManager
interface supports a number of find methods that allow clients to search for data using the JAXR information model. Many of these methods return aBulkResponse
(a collection of objects) that meets a set of criteria specified in the method arguments. The most useful of these methods are:
findOrganizations
, which returns a list of organizations that meet the specified criteria--often a name pattern or a classification within a classification schemefindServices
, which returns a set of services offered by a specified organizationfindServiceBindings
, which returns the service bindings (information about how to access the service) that are supported by a specified serviceThe
JAXRQuery
program illustrates how to query a registry by organization name and display the data returned. TheJAXRQueryByNAICSClassification
andJAXRQueryByWSDLClassification
programs illustrate how to query a registry using classifications. All JAXR providers support at least the following taxonomies for classifications:
- The North American Industry Classification System (NAICS). See
http://www.census.gov/epcd/www/naics.html
for details.- The Universal Standard Products and Services Classification (UNSPSC). See
http://www.eccma.org/unspsc/
for details.- The ISO 3166 country codes classification system maintained by the International Organization for Standardization (ISO). See
http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
for details.The following sections describe how to perform some common queries.
Finding Organizations by Name
To search for organizations by name, you normally use a combination of find qualifiers (which affect sorting and pattern matching) and name patterns (which specify the strings to be searched). The
findOrganizations
method takes a collection offindQualifier
objects as its first argument and a collection ofnamePattern
objects as its second argument. The following fragment shows how to find all the organizations in the registry whose names begin with a specified string,qString
, and to sort them in alphabetical order.// Define find qualifiers and name patterns Collection findQualifiers = new ArrayList(); findQualifiers.add(FindQualifier.SORT_BY_NAME_DESC); Collection namePatterns = new ArrayList(); namePatterns.add(qString); // Find using the name BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, null); Collection orgs = response.getCollection();A client can use percent signs (
%
) to specify that the query string can occur anywhere within the organization name. For example, the following code fragment performs a case-sensitive search for organizations whose names containqString
:Collection findQualifiers = new ArrayList(); findQualifiers.add(FindQualifier.CASE_SENSITIVE_MATCH); Collection namePatterns = new ArrayList(); namePatterns.add("%" + qString + "%"); // Find orgs with name containing qString BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, null); Collection orgs = response.getCollection();Finding Organizations by Classification
To find organizations by classification, you need to establish the classification within a particular classification scheme and then specify the classification as an argument to the
findOrganizations
method.The following code fragment finds all organizations that correspond to a particular classification within the NAICS taxonomy. (You can find the NAICS codes at
http://www.census.gov/epcd/naics/naicscod.txt
and also in the file<
JWSDP_HOME
>/docs/jaxr/taxonomies/naics.xml
.)ClassificationScheme cScheme = bqm.findClassificationSchemeByName(null, "ntis-gov:naics"); Classification classification = blcm.createClassification(cScheme, "Snack and Nonalcoholic Beverage Bars", "722213"); Collection classifications = new ArrayList(); classifications.add(classification); // make JAXR request BulkResponse response = bqm.findOrganizations(null, null, classifications, null, null, null); Collection orgs = response.getCollection();You can also use classifications to find organizations that offer services based on technical specifications that take the form of WSDL (Web Services Description Language) documents. In JAXR, a concept is used as a proxy to hold the information about a specification. The steps are a little more complicated than in the previous example, because the client must find the specification concepts first, then the organizations that use those concepts.
The following code fragment finds all the WSDL specification instances used within a given registry. You can see that the code is similar to the NAICS query code except that it ends with a call to
findConcepts
instead offindOrganizations
.String schemeName = "uddi-org:types"; ClassificationScheme uddiOrgTypes = bqm.findClassificationSchemeByName(null, schemeName); /* * Create a classification, specifying the scheme * and the taxonomy name and value defined for WSDL * documents by the UDDI specification. */ Classification wsdlSpecClassification = blcm.createClassification(uddiOrgTypes, "wsdlSpec", "wsdlSpec"); Collection classifications = new ArrayList(); classifications.add(wsdlSpecClassification); // Find concepts BulkResponse br = bqm.findConcepts(null, null, classifications, null, null);To narrow the search, you could use other arguments of the
findConcepts
method (search qualifiers, names, external identifiers, or external links).The next step is to go through the concepts, find the WSDL documents they correspond to, and display the organizations that use each document:
// Display information about the concepts found Collection specConcepts = br.getCollection(); Iterator iter = specConcepts.iterator(); if (!iter.hasNext()) { System.out.println("No WSDL specification concepts found"); } else { while (iter.hasNext()) { Concept concept = (Concept) iter.next(); String name = getName(concept); Collection links = concept.getExternalLinks(); System.out.println("\nSpecification Concept:\n\tName: " + name + "\n\tKey: " + concept.getKey().getId() + "\n\tDescription: " + getDescription(concept)); if (links.size() > 0) { ExternalLink link = (ExternalLink) links.iterator().next(); System.out.println("\tURL of WSDL document: '" + link.getExternalURI() + "'"); } // Find organizations that use this concept Collection specConcepts1 = new ArrayList(); specConcepts1.add(concept); br = bqm.findOrganizations(null, null, null, specConcepts1, null, null); // Display information about organizations ... }If you find an organization that offers a service you wish to use, you can invoke the service using the JAX-RPC API.
Finding Services and ServiceBindings
After a client has located an organization, it can find that organization's services and the service bindings associated with those services.
Iterator orgIter = orgs.iterator(); while (orgIter.hasNext()) { Organization org = (Organization) orgIter.next(); Collection services = org.getServices(); Iterator svcIter = services.iterator(); while (svcIter.hasNext()) { Service svc = (Service) svcIter.next(); Collection serviceBindings = svc.getServiceBindings(); Iterator sbIter = serviceBindings.iterator(); while (sbIter.hasNext()) { ServiceBinding sb = (ServiceBinding) sbIter.next(); } } }Managing Registry Data
If a client has authorization to do so, it can submit data to a registry, modify it, and remove it. It uses the
BusinessLifeCycleManager
interface to perform these tasks.Registries usually allow a client to modify or remove data only if the data is being modified or removed by the same user who first submitted the data.
Getting Authorization from the Registry
Before it can submit data, the client must send its user name and password to the registry in a set of credentials. The following code fragment shows how to do this.
String username = "myUserName"; String password = "myPassword"; // Get authorization from the registry PasswordAuthentication passwdAuth = new PasswordAuthentication(username, password.toCharArray()); Set creds = new HashSet(); creds.add(passwdAuth); connection.setCredentials(creds);Creating an Organization
The client creates the organization and populates it with data before saving it.
An
Organization
object is one of the more complex data items in the JAXR API. It normally includes the following:
- A
Name
object- A
Description
object- A
Key
object, representing the ID by which the organization is known to the registry. This key is created by the registry, not by the user, and is returned after the organization is submitted to the registry.- A
PrimaryContact
object, which is aUser
object that refers to an authorized user of the registry. AUser
object normally includes aPersonName
object and collections ofTelephoneNumber
,EmailAddress
, and/orPostalAddress
objects.- A collection of
Classification
objectsService
objects and their associatedServiceBinding
objectsFor example, the following code fragment creates an organization and specifies its name, description, and primary contact. When a client creates an organization, it does not include a key; the registry returns the new key when it accepts the newly created organization. The
blcm
object in this code fragment is theBusinessLifeCycleManager
object returned in Obtaining and Using a RegistryService Object. AnInternationalString
object is used for string values that may need to be localized.// Create organization name and description Organization org = blcm.createOrganization("The Coffee Break"); InternationalString s = blcm.createInternationalString("Purveyor of " + "the finest coffees. Established 1895"); org.setDescription(s); // Create primary contact, set name User primaryContact = blcm.createUser(); PersonName pName = blcm.createPersonName("Jane Doe"); primaryContact.setPersonName(pName); // Set primary contact phone number TelephoneNumber tNum = blcm.createTelephoneNumber(); tNum.setNumber("(800) 555-1212"); Collection phoneNums = new ArrayList(); phoneNums.add(tNum); primaryContact.setTelephoneNumbers(phoneNums); // Set primary contact email address EmailAddress emailAddress = blcm.createEmailAddress("jane.doe@TheCoffeeBreak.com"); Collection emailAddresses = new ArrayList(); emailAddresses.add(emailAddress); primaryContact.setEmailAddresses(emailAddresses); // Set primary contact for organization org.setPrimaryContact(primaryContact);Adding Classifications
Organizations commonly belong to one or more classifications based on one or more classification schemes (taxonomies). To establish a classification for an organization using a taxonomy, the client first locates the taxonomy it wants to use. It uses the
BusinessQueryManager
to find the taxonomy. ThefindClassificationSchemeByName
method takes a set ofFindQualifier
objects as its first argument, but this argument can be null.// Set classification scheme to NAICS ClassificationScheme cScheme = bqm.findClassificationSchemeByName(null, "ntis-gov:naics");The client then creates a classification using the classification scheme and a concept (a taxonomy element) within the classification scheme. For example, the following code sets up a classification for the organization within the NAICS taxonomy. The second and third arguments of the
createClassification
method are the name and value of the concept.// Create and add classification Classification classification = blcm.createClassification(cScheme, "Snack and Nonalcoholic Beverage Bars", "722213"); Collection classifications = new ArrayList(); classifications.add(classification); org.addClassifications(classifications);Services also use classifications, so you can use similar code to add a classification to a
Service
object.Adding Services and Service Bindings to an Organization
Most organizations add themselves to a registry in order to offer services, so the JAXR API has facilities to add services and service bindings to an organization.
Like an
Organization
object, aService
object has a name and a description. Also like anOrganization
object, it has a unique key that is generated by the registry when the service is registered. It may also have classifications associated with it.A service also commonly has service bindings, which provide information about how to access the service. A
ServiceBinding
object normally has a description, an access URI, and a specification link, which provides the linkage between a service binding and a technical specification that describes how to use the service using the service binding.The following code fragment shows how to create a collection of services, add service bindings to a service, then add the services to the organization. It specifies an access URI but not a specification link. Because the access URI is not real and because JAXR by default checks for the validity of any published URI, the binding sets its
validateURI
property to false.// Create services and service Collection services = new ArrayList(); Service service = blcm.createService("My Service Name"); InternationalString is = blcm.createInternationalString("My Service Description"); service.setDescription(is); // Create service bindings Collection serviceBindings = new ArrayList(); ServiceBinding binding = blcm.createServiceBinding(); is = blcm.createInternationalString("My Service Binding " + "Description"); binding.setDescription(is); // allow us to publish a bogus URL without an error binding.setValidateURI(false); binding.setAccessURI("http://TheCoffeeBreak.com:8080/sb/"); serviceBindings.add(binding); // Add service bindings to service service.addServiceBindings(serviceBindings); // Add service to services, then add services to organization services.add(service); org.addServices(services);Saving an Organization
The primary method a client uses to add or modify organization data is the
saveOrganizations
method, which creates one or more new organizations in a registry if they did not exist previously. If one of the organizations exists but some of the data have changed, thesaveOrganizations
method updates and replaces the data.After a client populates an organization with the information it wants to make public, it saves the organization. The registry returns the key in its response, and the client retrieves it.
// Add organization and submit to registry // Retrieve key if successful Collection orgs = new ArrayList(); orgs.add(org); BulkResponse response = blcm.saveOrganizations(orgs); Collection exceptions = response.getException(); if (exceptions == null) { System.out.println("Organization saved"); Collection keys = response.getCollection(); Iterator keyIter = keys.iterator(); if (keyIter.hasNext()) { javax.xml.registry.infomodel.Key orgKey = (javax.xml.registry.infomodel.Key) keyIter.next(); String id = orgKey.getId(); System.out.println("Organization key is " + id); org.setKey(orgKey); } }Removing Data from the Registry
A registry allows you to remove from the registry any data that you have submitted to it. You use the key returned by the registry as an argument to one of the
BusinessLifeCycleManager
delete methods:deleteOrganizations
,deleteServices
,deleteServiceBindings
, and others.The
JAXRDelete
sample program deletes the organization created by theJAXRPublish
program. It deletes the organization that corresponds to a specified key string and then displays the key again so that the user can confirm that it has deleted the correct one.String id = key.getId(); System.out.println("Deleting organization with id " + id); Collection keys = new ArrayList(); keys.add(key); BulkResponse response = blcm.deleteOrganizations(keys); Collection exceptions = response.getException(); if (exceptions == null) { System.out.println("Organization deleted"); Collection retKeys = response.getCollection(); Iterator keyIter = retKeys.iterator(); javax.xml.registry.infomodel.Key orgKey = null; if (keyIter.hasNext()) { orgKey = (javax.xml.registry.infomodel.Key) keyIter.next(); id = orgKey.getId(); System.out.println("Organization key was " + id); } }A client can use a similar mechanism to delete services and service bindings.
Using Taxonomies in JAXR Clients
In the JAXR API, a taxonomy is represented by a
ClassificationScheme
object.This section describes how to use the implementation of JAXR in the Java WSDP:
Defining a Taxonomy
The JAXR specification requires a JAXR provider to be able to add user-defined taxonomies for use by JAXR clients. The mechanisms clients use to add and administer these taxonomies are implementation-specific.
The implementation of JAXR in the Java WSDP uses a simple file-based approach to provide taxonomies to the JAXR client. These files are read at run time, when the JAXR provider starts up.
The taxonomy structure for the Java WSDP is defined by the JAXR Predefined Concepts DTD, which is declared both in the file
jaxrconcepts.dtd
and, in XML schema form, in the filejaxrconcepts.xsd
. The filejaxrconcepts.xml
contains the taxonomies for the implementation of JAXR in the Java WSDP. All these files are contained in the<
JWSDP_HOME
>/common/lib/jaxr-ri.jar
file, but you can find copies of them in the directory<
JWSDP_HOME
>/docs/jaxr/taxonomies
. This directory also contains copies of the XML files that the implementation of JAXR in the Java WSDP uses to define the well-known taxonomies that it uses:naics.xml
,iso3166.xml
, andunspsc.xml
. You may use all of these as examples of how to construct a taxonomy XML file.The entries in the
jaxrconcepts.xml
file look like this:<PredefinedConcepts> <JAXRClassificationScheme id="schId
" name="schName
"> <JAXRConcept id="schId
/conCode
" name="conName
" parent="parentId
" code="conCode
"></JAXRConcept> ... </JAXRClassificationScheme> </PredefinedConcepts>The taxonomy structure is a containment-based structure. The element
PredefinedConcepts
is the root of the structure and must be present. TheJAXRClassificationScheme
element is the parent of the structure, and theJAXRConcept
elements are children and grandchildren. AJAXRConcept
element may have children, but it is not required to do so.In all element definitions, attribute order and case are significant.
To add a user-defined taxonomy, follow these steps.
- Publish the
JAXRClassificationScheme
element for the taxonomy as aClassificationScheme
object in the registry that you will be accessing. For example, you can publish theClassificationScheme
object to the Java WSDP Registry Server. In order to publish aClassificationScheme
object, you must set its name. You also give the scheme a classification within a known classification scheme such asuddi-org:types
. In the following code fragment, the name is the first argument of theLifeCycleManager.createClassificationScheme
method call.ClassificationScheme cScheme = blcm.createClassificationScheme("MyScheme", "A Classification Scheme"); ClassificationScheme uddiOrgTypes = bqm.findClassificationSchemeByName(null, "uddi-org:types"); if (uddiOrgTypes != null) { Classification classification = blcm.createClassification(uddiOrgTypes, "postalAddress", "categorization" ); postalScheme.addClassification(classification); ExternalLink externalLink = blcm.createExternalLink("http://www.mycom.com/myscheme.html", "My Scheme"); postalScheme.addExternalLink(externalLink); Collection schemes = new ArrayList(); schemes.add(cScheme); BulkResponse br = blcm.saveClassificationSchemes(schemes); }
- The
BulkResponse
object returned by thesaveClassificationSchemes
method contains the key for the classification scheme, which you need to retrieve:if (br.getStatus() == JAXRResponse.STATUS_SUCCESS) { System.out.println("Saved ClassificationScheme"); Collection schemeKeys = br.getCollection(); Iterator keysIter = schemeKeys.iterator(); while (keysIter.hasNext()) { javax.xml.registry.infomodel.Key key = (javax.xml.registry.infomodel.Key) keysIter.next(); System.out.println("The postalScheme key is " + key.getId()); System.out.println("Use this key as the scheme" + " uuid in the taxonomy file"); } }- In an XML file, define a taxonomy structure that is compliant with the JAXR Predefined Concepts DTD. Enter the
ClassificationScheme
element in your taxonomy XML file by specifying the returned key ID value as theid
attribute and the name as thename
attribute. For the code fragment above, for example, the opening tag for theJAXRClassificationScheme
element looks something like this (all on one line):<JAXRClassificationScheme id="uuid:nnnnnnnn-nnnn-nnnn-nnnn- nnnnnnnnnnnn" name="MyScheme">
- The
ClassificationScheme
id
must be a UUID.- Enter each
JAXRConcept
element in your taxonomy XML file by specifying the following four attributes, in this order:
id
is theJAXRClassificationScheme
id
value, followed by a/
separator, followed by the code of theJAXRConcept
elementname
is the name of theJAXRConcept
elementparent
is the immediate parentid
(either theClassificationScheme
id
or that of the parentJAXRConcept
)code
is theJAXRConcept
element code value
- The first
JAXRConcept
element in thenaics.xml
file looks like this (all on one line):<JAXRConcept id="uuid:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2/11" name="Agriculture, Forestry, Fishing and Hunting" parent="uuid:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2" code="11"></JAXRConcept>- To add the user-defined taxonomy structure to the JAXR provider, specify the system property
com.sun.xml.registry.userTaxonomyFilenames
when you run your client program. The command line (all on one line) would look like this. A vertical bar (|
) is the file separator.java myProgram -DuserTaxonomyFilenames=c:\myfile\xxx.xml|c:\myfile\xxx2.xml
- You can use a
<sysproperty>
tag to set this property in abuild.xml
file. Or, in your program, you can set the property as follows:System.setProperty ("com.sun.xml.registry.userTaxonomyFilenames", "c:\myfile\xxx.xml|c:\myfile\xxx2.xml");Specifying Postal Addresses
The JAXR specification defines a postal address as a structured interface with attributes for street, city, country, and so on. The UDDI specification, on the other hand, defines a postal address as a free-form collection of address lines, each of which may also be assigned a meaning. To map the JAXR
PostalAddress
format to a known UDDI address format, you specify the UDDI format as aClassificationScheme
object and then specify the semantic equivalences between the concepts in the UDDI format classification scheme and the comments in the JAXRPostalAddress
classification scheme. The JAXRPostalAddress
classification scheme is provided by the implementation of JAXR in the Java WSDP.In the JAXR API, a
PostalAddress
object has the fieldsstreetNumber
,street
,city
,state
,postalCode
andcountry
. In the implementation of JAXR in the Java WSDP, these are predefined concepts in thejaxrconcepts.xml
file, within theClassificationScheme
namedPostalAddressAttributes
.To specify the mapping between the JAXR postal address format and another format, you need to set two connection properties:
- The
javax.xml.registry.postalAddressScheme
property, which specifies a postal address classification scheme for the connection- The
javax.xml.registry.semanticEquivalences
property, which specifies the semantic equivalences between the JAXR format and the other formatFor example, suppose you want to use a scheme that has been published to the IBM registry with the known UUID
uuid:6eaf4b50-4196-11d6-9e2b-000629dc0a2b
. This scheme already exists in thejaxrconcepts.xml
file under the nameIBMDefaultPostalAddressAttributes
.<JAXRClassificationScheme id="uuid:6EAF4B50-4196-11D6-9E2B- 000629DC0A2B" name="IBMDefaultPostalAddressAttributes">First, you specify the postal address scheme using the
id
value from theJAXRClassificationScheme
element (the UUID). Case does not matter:props.setProperty("javax.xml.registry.postalAddressScheme", "uuid:6eaf4b50-4196-11d6-9e2b-000629dc0a2b");Next, you specify the mapping from the
id
of eachJAXRConcept
element in the default JAXR postal address scheme to theid
of its counterpart in the IBM scheme:props.setProperty("javax.xml.registry.semanticEquivalences", "urn:uuid:PostalAddressAttributes/StreetNumber," + "urn:uuid:6eaf4b50-4196-11d6-9e2b- 000629dc0a2b/StreetAddressNumber|" + "urn:uuid:PostalAddressAttributes/Street," + "urn:uuid:6eaf4b50-4196-11d6-9e2b- 000629dc0a2b/StreetAddress|" + "urn:uuid:PostalAddressAttributes/City," + "urn:uuid:6eaf4b50-4196-11d6-9e2b-000629dc0a2b/City|" + "urn:uuid:PostalAddressAttributes/State," + "urn:uuid:6eaf4b50-4196-11d6-9e2b-000629dc0a2b/State|" + "urn:uuid:PostalAddressAttributes/PostalCode," + "urn:uuid:6eaf4b50-4196-11d6-9e2b-000629dc0a2b/ZipCode|" + "urn:uuid:PostalAddressAttributes/Country," + "urn:uuid:6eaf4b50-4196-11d6-9e2b-000629dc0a2b/Country");After you create the connection using these properties, you can create a postal address and assign it to the primary contact of the organization before you publish the organization:
String streetNumber = "99"; String street = "Imaginary Ave. Suite 33"; String city = "Imaginary City"; String state = "NY"; String country = "USA"; String postalCode = "00000"; String type = ""; PostalAddress postAddr = blcm.createPostalAddress(streetNumber, street, city, state, country, postalCode, type); Collection postalAddresses = new ArrayList(); postalAddresses.add(postAddr); primaryContact.setPostalAddresses(postalAddresses);A JAXR query can then retrieve the postal address using
PostalAddress
methods, if the postal address scheme and semantic equivalences for the query are the same as those specified for the publication. To retrieve postal addresses when you do not know what postal address scheme was used to publish them, you can retrieve them as a collection ofSlot
objects. TheJAXRQueryPostal.java
sample program shows how to do this.In general, you can create a user-defined postal address taxonomy for any
postalAddress
tModels that use the well-known categorization in theuddi-org:types
taxonomy, which has the tModel UUID uuid:c1acf26d-9672-4404-9d70-39b756e62ab4
with a value ofpostalAddress
. You can retrieve the tModeloverviewDoc
, which points to the technical detail for the specification of the scheme, where the taxonomy structure definition can be found. (The JAXR equivalent of anoverviewDoc
is anExternalLink
.)Running the Client Examples
The simple client programs provided with this tutorial can be run from the command line. You can modify them to suit your needs. They allow you to specify the IBM registry, the Microsoft registry, or the Registry Server for queries and updates; you can specify any other UDDI version 2 registry.
The client examples, in the
<
JWSDP_HOME
>/docs/tutorial/examples/jaxr
directory, are as follows:
JAXRQuery.java
shows how to search a registry for organizationsJAXRQueryByNAICSClassification.java
shows how to search a registry using a common classification schemeJAXRQueryByWSDLClassification.java
shows how to search a registry for Web services that describe themselves by means of a WSDL documentJAXRPublish.java
shows how to publish an organization to a registryJAXRDelete.java
shows how to remove an organization from a registryJAXRSaveClassificationScheme.java
shows how to publish a classification scheme (specifically, a postal address scheme) to a registryJAXRPublishPostal.java
shows how to publish an organization with a postal address for its primary contactJAXRQueryPostal.java
shows how to retrieve postal address data from an organizationJAXRDeleteScheme.java
shows how to delete a classification scheme from a registryJAXRGetMyObjects.java
lists all the objects that you own in a registryThe
<
JWSDP_HOME
>/docs/tutorial/examples/jaxr
directory also contains:
- A
build.xml
file for the examples- A
JAXRExamples.properties
file that supplies string values used by the sample programs- A file called
postalconcepts.xml
that you use with the postal address examplesBefore You Compile the Examples
Before you compile the examples, edit the file
JAXRExamples.properties
as follows. (See Using the JAXR API to Access the Registry Server for details on editing this file to access the Registry Server.)
- Edit the following lines in the
JAXRExamples.properties
file to specify the registry you wish to access. For both thequeryURL
and thepublishURL
assignments, comment out all but the registry you wish to access. The default is the Registry Server, so if you will be using the Registry Server you do not need to change this section.## Uncomment one pair of query and publish URLs. ## IBM: #query.url=http://uddi.ibm.com/testregistry/inquiryapi #publish.url=https://uddi.ibm.com/testregistry/protect/publish api ## Microsoft: #query.url=http://uddi.microsoft.com/inquire #publish.url=https://uddi.microsoft.com/publish ## Registry Server: query.url=http://localhost:8080/registry- server/RegistryServerServlet publish.url=http://localhost:8080/registry- server/RegistryServerServlet
- The IBM and Microsoft registries both have a considerable amount of data in them that you can perform queries on. Moreover, you do not have to register if you are only going to perform queries.
- We have not included the URL of the SAP registry; feel free to add it.
- If you want to publish to any of the public registries, the registration process for obtaining access to them is not difficult (see Preliminaries: Getting Access to a Registry). Each of them, however, allows you to have only one organization registered at a time. If you publish an organization to one of them, you must delete it before you can publish another. Since the organization that the
JAXRPublish
example publishes is fictitious, you will want to delete it immediately anyway. (It is particularly important to delete such organizations promptly, because the public registries replicate each other's data, and your fictitious organization may appear in a registry that is not the one you published it to and from which you therefore cannot delete it.)- The Registry Server gives you more freedom to experiment with JAXR. You can publish as many organizations to it as you wish. However, this registry comes with an empty database, so you must publish organizations to it yourself before you can perform queries on the data.
- Edit the following lines in the
JAXRExamples.properties
file to specify the user name and password you obtained when you registered with the registry. The default is the Registry Server default password.## Specify username and password if needed ## testuser/testuser are defaults for Registry Server registry.username=testuser registry.password=testuser- If you will be using a public registry, edit the following lines in the
JAXRExamples.properties
file, which contain empty strings for the proxy hosts, to specify your own proxy settings. The proxy host is the system on your network through which you access the Internet; you usually specify it in your Internet browser settings. You can leave this value empty to use the Registry Server.## HTTP and HTTPS proxy host and port; ## ignored by Registry Server http.proxyHost= http.proxyPort=8080 https.proxyHost= https.proxyPort=8080
- The proxy ports have the value 8080, which is the usual one; change this string if your proxy uses a different port.
- For a public registry, your entries usually follow this pattern:
http.proxyHost=proxyhost.mydomain http.proxyPort=8080 https.proxyHost=proxyhost.mydomain https.proxyPort=8080- Feel free to change any of the organization data in the remainder of the file. This data is used by the publishing and postal address examples.
Compiling the Examples
To compile the programs, go to the
<
JWSDP_HOME
>/docs/tutorial/examples/jaxr
directory. Abuild.xm
l file allows you to use the commandant buildto compile all the examples. The
Ant
tool creates a subdirectory calledbuild
and places the class files there.You will notice that the classpath setting in the
build.xml
file includes the contents of the directoriescommon/lib
andcommon/endorsed
. All JAXR client examples require this classpath setting.Running the Examples
Some of the
build.xml
targets for running the examples contain commented-out<sysproperty>
tags that set the JAXR logging level to debug and set other connection properties. These tags are provided to illustrate how to specify connection properties. Feel free to modify or delete these tags.If you are running the examples with the Registry Server, start Tomcat and the Xindice database. See Setting Up the Registry Server for details. You do not need to start Tomcat in order to run the examples against public registries.
Running the JAXRPublish Example
To run the
JAXRPublish
program, use therun-publish
target with no command line arguments:ant run-publishThe program output displays the string value of the key of the new organization, which is named "The Coffee Break."
After you run the
JAXRPublish
program but before you runJAXRDelete
, you can runJAXRQuery
to look up the organization you published. You can also use the Registry Browser to search for it.Running the JAXRQuery Example
To run the
JAXRQuery
example, use theAnt
targetrun-query
. Specify aquery-string
argument on the command line to search the registry for organizations whose names contain that string. For example, the following command line searches for organizations whose names contain the string "coff" (searching is not case-sensitive):ant run-query -Dquery-string=coffRunning the JAXRQueryByNAICSClassification Example
After you run the
JAXRPublish
program, you can also run theJAXRQueryByNAICSClassification
example, which looks for organizations that use the "Snack and Nonalcoholic Beverage Bars" classification, the same one used for the organization created byJAXRPublish
. To do so, use theAnt
targetrun-query-naics
:ant run-query-naicsRunning the JAXRDelete Example
To run the
JAXRDelete
program, specify the key string returned by theJAXRPublish
program as input to therun-delete
target:ant run-delete -Dkey-string=keyString
Running the JAXRQueryByWSDLClassification Example
You can run the
JAXRQueryByWSDLClassification
example at any time. Use theAnt
targetrun-query-wsdl
:ant run-query-wsdlThis example returns many results from the public registries and is likely to run for several minutes.
Publishing a Classification Scheme
In order to publish organizations with postal addresses to public registries, you must publish a classification scheme for the postal address first.
To run the
JAXRSaveClassificationScheme
program, use the targetrun-save-scheme
:ant run-save-schemeThe program returns a UUID string, which you will use in the next section.
You do not have to run this program if you are using the Registry Server, because it does not validate these objects.
The public registries allow you to own more than one classification scheme at a time (the limit is usually a total of about 10 classification schemes and concepts put together).
Running the Postal Address Examples
Before you run the postal address examples, open the file
postalconcepts.xml
in an editor. Wherever you see the stringuuid-from-save
, replace it with the UUID string returned by therun-save-scheme
target. For the registry server, you may use any string that is formatted as a UUID.For a given registry, you only need to save the classification scheme and edit
postalconcepts.xml
once. After you perform those two steps, you can run theJAXRPublishPostal
andJAXRQueryPostal
programs multiple times.
- Run the
JAXRPublishPostal
program. Notice that in thebuild.xml
file, therun-publish-postal
target contains a<sysproperty>
tag that sets theuserTaxonomyFilenames
property to the location of thepostalconcepts.xml
file in the current directory:<sysproperty key="com.sun.xml.registry.userTaxonomyFilenames" value="postalconcepts.xml"/>
- Specify the string you entered in the
postalconcepts.xml
file as input to therun-publish-postal
target:ant run-publish-postal -Duuid-string=uuidstring
- The program output displays the string value of the key of the new organization.
- Run the
JAXRQueryPostal
program. Therun-query-postal
target contains the same<sysproperty>
tag as therun-publish-postal
target.
- As input to the
run-query-postal
target, specify both aquery-string
argument and auuid-string
argument on the command line to search the registry for the organization published by therun-publish-postal
target:ant run-query-postal -Dquery-string=coffee -Duuid-string=uuidstring
- The postal address for the primary contact will appear correctly with the JAXR
PostalAddress
methods. Any postal addresses found that use other postal address schemes will appear asSlot
lines.- If you are using a public registry, make sure to follow the instructions in Running the JAXRDelete Example to delete the organization you published.
Deleting a Classification Scheme
To delete the classification scheme you published after you have finished using it, run the
JAXRDeleteScheme
program using therun-delete-scheme
target:ant run-delete-scheme -Duuid-string=uuidstring
For a UDDI registry, deleting a classification scheme removes it from the registry logically but not physically. You can no longer use the classification scheme, but it will still be visible if, for example, you call the method
QueryManager.getRegisteredObjects
. Since the public registries allow you to own up to 10 of these objects, this is not likely to be a problem.Getting a List of Your Registry Objects
To get a list of the objects you own in the registry, both organizations and classification schemes, run the
JAXRGetMyObjects
program by using therun-get-objects
target:ant run-get-objectsOther Targets
To remove the
build
directory and class files, use the commandant cleanTo obtain a syntax reminder for the targets, use the command
ant -projecthelp
Home
TOC Index |
This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.
All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.