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 Java WSDP Registry Server for queries and updates; you can specify any other UDDI version 2 registry.

The client examples, in the <INSTALL>/j2eetutorial14/examples/jaxr/simple/src/ directory, are as follows:

JAXRQuery.java shows how to search a registry for organizations.

JAXRQueryByNAICSClassification.java shows how to search a registry using a common classification scheme.

JAXRQueryByWSDLClassification.java shows how to search a registry for Web services that describe themselves by means of a WSDL document.

JAXRPublish.java shows how to publish an organization to a registry.

JAXRDelete.java shows how to remove an organization from a registry.

JAXRSaveClassificationScheme.java shows how to publish a classification scheme (specifically, a postal address scheme) to a registry.

JAXRPublishPostal.java shows how to publish an organization with a postal address for its primary contact.

JAXRQueryPostal.java shows how to retrieve postal address data from an organization.

JAXRDeleteScheme.java shows how to delete a classification scheme from a registry.

JAXRPublishConcept.java shows how to publish a concept for a WSDL document.

JAXRPublishHelloOrg.java shows how to publish an organization with a service binding that refers to a WSDL document.

JAXRDeleteConcept.java shows how to delete a concept.

JAXRGetMyObjects.java lists all the objects that you own in a registry.

The <INSTALL>/j2eetutorial14/examples/jaxr/simple/ directory also contains the following:

A build.xml file for the examples

A JAXRExamples.properties file, in the src subdirectory, that supplies string values used by the sample programs

A file called postalconcepts.xml, also in the src subdirectory, that serves as the taxonomy file for the postal address examples

You do not have to have the Application Server running in order to run most of these client examples. You do need to have it running in order to run JAXRPublishConcept.java and JAXRPublishHelloOrg.java.

If you want to run the Application Server and the Registry Server at the same time, you should be aware that they both use the same port, 8080, to run the Web container. You need to change this port for either the Application Server or the Java WSDP.

You specified the Web container port for the Application Server (called the HTTP port) when you installed it. If you did not specify a nondefault port for the Application Server, it is probably easier to change the Java WSDP port. This involves two tasks:

Open the file <JWSDP_HOME>/conf/server.xml in a text editor. Find the comment "Define a non-SSL Coyote HTTP/1.1 Connector on port 8080." In the Connector element that follows, change this attribute to some other port value, such as 8082 or 8083:

port="8080"

Open the file <JWSDP_HOME>/jwsdp-shared/bin/launcher.xml in a text editor. Find the following lines (they are all on one line in the file):

<sysproperty key="org.apache.xindice.host" value="desired Xindice host"/> <sysproperty key="org.apache.xindice.port" value="desired Xindice port"/>

Make the host and port values the same as those for the Web container (the host is ordinarily localhost). Uncomment these properties, and then save the file.

Now, when you start the Java WSDP Web container, Tomcat, as described in Running the Examples, there will be no port conflict with the Application Server.

Before You Compile the Examples

Before you compile the examples, edit the file <INSTALL>/j2eetutorial14/examples/jaxr/simple/src/JAXRExamples.properties as follows.

Edit the following lines to specify the registry you wish to access. For both the queryURL and the publishURL assignments, comment out all but the registry you wish to access. The default is the Java WSDP Registry Server.

## Uncomment one pair of query and publish URLs. ## IBM: #query.url=http://uddi.ibm.com/testregistry/inquiryapi #publish.url=https://uddi.ibm.com/testregistry/publishapi ## Microsoft: #query.url=http://test.uddi.microsoft.com/inquire #publish.url=https://test.uddi.microsoft.com/publish ## Registry Server: query.url=http://localhost:8080/RegistryServer/ publish.url=http://localhost:8080/RegistryServer/

If you are using the Java WSDP Registry Server and if it is running on a system other than your own, specify the fully qualified host name instead of localhost. Do not use https: for the publishURL. If Tomcat is using a nondefault port, change 8080 to the correct value for your system.

The IBM and Microsoft registries both contain a considerable amount of data 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 URLs of the SAP registry; feel free to add them.

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. Because the organization that the JAXRPublish example publishes is fictitious, you will want to delete it immediately anyway.

Be aware also that because the public registries are test registries, they do not always behave reliably.

The Java WSDP Registry Server gives you more freedom to experiment with JAXR. You can publish as many organizations, concepts, and classification schemes to it as you wish. However, this registry comes with an empty database, so you must publish data to it yourself before you can perform queries on the data.

To use a public registry, edit the following lines to specify the user name and password you obtained when you registered with the registry. Do not change the lines if you will use the Registry Server.

## To use a public registry, edit user name and password. ## To use the Registry Server, use testuser/testuser. registry.username=testuser registry.password=testuser

If you will be using a public registry, edit the following lines, 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 Java WSDP 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

If you are running the Application Server on a system other than your own or if it (not the Java WSDP Tomcat) is using a nondefault HTTP port, change the following lines:

link.uri=http://localhost:8080/hello-jaxrpc/hello?WSDL ... wsdlorg.svcbnd.uri=http://localhost:8080/hello-jaxrpc/hello

Specify the fully qualified host name instead of localhost, or change 8080 to the correct value for your system.

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. If you will be using a public registry, try to make the organization names unusual so that queries will return relatively few results.

You can edit the src/JAXRExamples.properties file at any time. The asant targets that run the client examples will use the latest version of the file.

Compiling the Examples

To compile the programs, go to the <INSTALL>/j2eetutorial14/examples/jaxr/simple/ directory. A build.xml file allows you to use the following command to compile all the examples:

The runtime classpath setting in the build.xml file includes JAR files in several directories in the Application Server installation. All JAXR client examples require this classpath setting.

Running the Examples

If you are running the examples with the Java WSDP Registry Server, start the Java WSDP Tomcat (<JWSDP_HOME> is the location of the Java WSDP on your system).

On Windows, from the Start menu, choose Programs Right Arrow

Java Web Services Developer Pack 1.x Right Arrow

Start Tomcat or use the following command:

You do not need to startTomcat in order to run the examples against public registries.

Running the JAXRPublish Example

To run the JAXRPublish program, use the run-publish target with no command-line arguments:

The 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 run JAXRDelete, you can run JAXRQuery to look up the organization you published.

Running the JAXRQuery Example

To run the JAXRQuery example, use the asant target run-query. Specify a query-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):

Running the JAXRQueryByNAICSClassification Example

After you run the JAXRPublish program, you can also run the JAXRQueryByNAICSClassification example, which looks for organizations that use the Snack and Nonalcoholic Beverage Bars classification, the same one used for the organization created by JAXRPublish. To do so, use the asant target run-query-naics:

Running the JAXRDelete Example

To run the JAXRDelete program, specify the key string displayed by the JAXRPublish program as input to the run-delete target:

Publishing a Classification Scheme

To publish organizations with postal addresses to public registries, you must first publish a classification scheme for the postal address.

To run the JAXRSaveClassificationScheme program, use the target run-save-scheme:

You do not have to run this program if you are using the Java WSDP 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 src/postalconcepts.xml in an editor. Wherever you see the string uuid-from-save, replace it with the UUID string returned by the run-save-scheme target (including the uuid: prefix). For the Java WSDP Registry Server, you can use any string that is formatted as a UUID.

For a given registry, you only need to publish the classification scheme and edit postalconcepts.xml once. After you perform those two steps, you can run the JAXRPublishPostal and JAXRQueryPostal programs multiple times.

Run the JAXRPublishPostal program. Specify the string you entered in the postalconcepts.xml file, including the uuid: prefix, as input to the run-publish-postal target:

asant -Duuid-string=uuidstring run-publish-postal

The uuidstring would look something like this (case is not significant):

uuid:938d9ccd-a74a-4c7e-864a-e6e2c6822519

The program output displays the string value of the key of the new organization.

Run the JAXRQueryPostal program. The run-query-postal target contains the same <sysproperty> tag as the run-publish-postal target.

As input to the run-query-postal target, specify both a query-string argument and a uuid-string argument on the command line to search the registry for the organization published by the run-publish-postal target:

asant -Dquery-string=coffee -Duuid-string=uuidstring run-query-postal

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 as Slot 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 the run-delete-scheme target:

For the public UDDI registries, deleting a classification scheme removes it from the registry logically but not physically. The classification scheme will still be visible if, for example, you call the method QueryManager.getRegisteredObjects. However, you can no longer use the classification scheme. Therefore, you may prefer not to delete the classification scheme from the registry, in case you want to use it again. The public registries normally allow you to own up to 10 of these objects.

Publishing a Concept for a WSDL Document

Then run the JAXRPublishConcept program using the run-publish-concept target:

The program output displays the UUID string of the new specification concept, which is named HelloConcept. You will use this string in the next section.

After you run the JAXRPublishConcept program, you can run JAXRPublishHelloOrg to publish an organization that uses this concept.

Publishing an Organization with a WSDL Document in Its Service Binding

To run the JAXRPublishHelloOrg example, use the asant target run-publish-hello-org. Specify the string returned from JAXRPublishConcept (including the uuid: prefix) as input to this target:

The program output displays the string value of the key of the new organization, which is named Hello Organization.

After you publish the organization, run the JAXRQueryByWSDLClassification example to search for it. To delete it, run JAXRDelete.

Running the JAXRQueryByWSDLClassification Example

To run the JAXRQueryByWSDLClassification example, use the asant target run-query-wsdl. Specify a query-string argument on the command line to search the registry for specification concepts whose names contain that string. For example, the following command line searches for concepts whose names contain the string "helloconcept" (searching is not case-sensitive):

This example finds the concept and organization you published. A common string such as "hello" returns many results from the public registries and is likely to run for several minutes.

Deleting a Concept

To run the JAXRDeleteConcept program, specify the UUID string displayed by the JAXRPublishConcept program as input to the run-delete-concept target:

Deleting a concept from a public UDDI registry is similar to deleting a classification scheme: The concept is removed logically but not physically. Do not delete the concept until after you have deleted any organizations that refer to it.

Getting a List of Your Registry Objects

To get a list of the objects you own in the registry--organizations, classification schemes, and concepts--run the JAXRGetMyObjects program by using the run-get-objects target:

If you run this program with the Java WSDP Registry Server, it returns all the standard UDDI taxonomies provided with the Registry Server and not just the objects you have created.