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 <INSTALL>/j2eetutorial/examples/jaxr 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

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

The <INSTALL>/j2eetutorial/examples/jaxr directory also contains:

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

A file called postalconcepts.xml that you use with the postal address examples

A file called postal.properties that specifies the location of the user taxonomy file for the postal address examples

The instructions that follow assume that you have started Sun ONE Studio. You do not need to have the Sun ONE Application Server running in order to use JAXR.

Mounting the Filesystem

Before you can compile the examples, you must mount the filesystem. To do so:

Select the Filesystems tab of the Explorer.

Choose Mount Filesystem from the File menu.

Mount the following directory:

<INSTALL>/j2eetutorial/examples/jaxr

Editing the Properties File

Before you compile the examples, edit the file JAXRExamples.properties as follows.

Right-click the file and choose the Edit menu item.

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 Sun ONE Studio internal UDDI Server Registry, so if you will be using this registry on your own system, 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/ publishapi ## Microsoft: #query.url=http://test.uddi.microsoft.com/inquire #publish.url=https://test.uddi.microsoft.com/publish ## Registry Server: query.url=http://localhost:8089/registry-server/ RegistryServerServlet publish.url=http://localhost:8089/registry-server/ RegistryServerServlet

If the internal UDDI Server Registry 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.

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

The internal UDDI Server Registry 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 to specify the user name and password you obtained when you registered with the registry. The default is the internal UDDI Server Registry default password.

## Specify username and password if needed ## testuser/testuser are defaults for internal Registry 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 internal UDDI Server Registry.

## HTTP and HTTPS proxy host and port; ## ignored by internal Registry 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 examples, JAXRPublish and JAXRPublishPostal.

Save and close the file.

You can edit the JAXRExamples.properties file at any time. When you run the client examples, they use the latest version of the file.

Starting the Internal UDDI Server Registry

If you plan to use the internal UDDI Server Registry, perform the following steps:

Select the Runtime tab of the Explorer.

Expand the UDDI Server Registry node.

Right-click the Internal UDDI Registry node and choose the Start Server menu item.

Setting the Compilation Classpath

Before you can compile the programs, you need to set the compilation classpath. To do so:

Choose Options from the Tools menu.

Expand the Building node, then the Compiler Types node.

Choose External Compilation.

Select the Expert tab.

Click the Class Path property, then double-click the ellipsis in the value field.

In the property editor, click Add JAR/Zip.

In the file chooser, navigate to the directory <S1STUDIO_HOME>/jwsdp/common/lib and choose the jaxr-api.jar file. (This file is also in <S1AS7_HOME>/share/lib.)

Click OK.

Click OK in the property editor, then click Close in the Options window.

Compiling the Examples

To compile the programs:

In the Filesystems tab of the Explorer, right-click the <INSTALL>/j2eetutorial/examples/jaxr directory.

Choose the Compile All menu item.

Compiler messages appear in an output window.

Running the JAXRPublish Example

To run the JAXRPublish program, right-click the file in the Filesystems tab and choose the Execute menu item.

The program output appears in an output window associated with the Running tab of the main window. It displays the string value of the key of the new organization, which is named "The Coffee Break."

Do not dismiss the output window. You'll need its contents in the future. Return to the Editing tab to continue running the examples.

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:

Click the JAXRQuery file in the Filesystems tab.

In the property window for the file, choose the Execution tab.

Click Arguments.

Enter a string in the value field, such as coffee.

Right-click the JAXRQuery file in the Filesystems tab and choose the Execute menu item.

The program searches the registry for organizations whose names contain the string you specified. 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 run the program, right-click the JAXRQueryByNAICSClassification file in the Filesystems tab and choose the Execute menu item

Running the JAXRDelete Example

To run the JAXRDelete example, you need to provide the key returned by the JAXRPublish program. Perform the following steps:

Click the Running tab in the main window.

In the Output window tab for the JAXRPublish example, select the organization key value from the program output. It looks something like f2c2827a-b1f2-c282-3fd27a5c1893. Right-click in the window and choose the Copy menu item.

Click the JAXRDelete file in the Filesystems tab.

In the property window for the file, choose the Execution tab.

Click Arguments.

Paste the key string you copied in step 2 into the value field.

Right-click the JAXRDelete file in the Filesystems tab and choose the Execute menu item.

The program deletes the specified organization from the registry.

Running the JAXRQueryByWSDLClassification Example

To run the JAXRQueryByWSDLClassification example, right-click the file in the Filesystems tab and choose the Execute menu item.

This 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, right-click the file in the Filesystems tab and choose the Execute menu item.

The program returns a UUID string, which you will use in the next section.

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

Running the postal address examples involves the following steps:

Specifying the UUID of the classification scheme in the postalconcepts.xml file

Specifying the pathname of the postalconcepts.xml file in the postal.properties file

Running the JAXRPublishPostal example

Running the JAXRQueryPostal example

Specifying the UUID

Before you run the postal address examples, you need to specify the UUID of the classification scheme in the postalconcepts.xml file:

Click the Running tab in the main window.

In the Output window tab for the JAXRSaveClassificationScheme example, select the postal scheme key value from the program output. It looks something like this: uuid:f2be7262-aff2-be76-b3fa-ddd3e4e600f5. Right-click in the window and choose the Copy menu item.

Right-click the file postalconcepts.xml and choose the Edit menu item.

Wherever you see the string uuid-from-save, replace it with the UUID string you copied in step 2.

Save and close the file.

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

Editing the Properties File

Next, edit the postal.properties file to specify the correct pathname for the postalconcepts.xml file:

Right-click the file postal.properties and choose the Edit menu item.

Specify the correct pathname for the postalconcepts.xml file. On a UNIX system the pathname may be relative, but on a Windows system it must be absolute and must be specified using double backslashes. For example, you might enter the following (all on one line):

com.sun.xml.registry.userTaxonomyFilenames=D:\\Sun\\AppServer7
\\docs\\tutorial\\examples\\jaxr\\postalconcepts.xml

Running the JAXRPublishPostal Example

The JAXRPublishPostal example uses the postal.properties file to set the system property com.sun.xml.registry.userTaxonomyFilenames to the correct location of the postalconcepts.xml file. You need to specify this file and the UUID string of the classification scheme as command-line arguments.

Click the JAXRPublishPostal file in the Filesystems tab.

In the property window for the file, choose the Execution tab.

Click Arguments, then double-click the ellipsis to bring up the property editor.

Enter the pathname of the postal.properties file and the UUID string of the classification scheme. On a Windows system, you must specify the full pathname. For example, you might specify the following, all on one line:

D:\MyTutorial\j2eetutorial\examples\jaxr\
postal.properties uuid:f2be7262-aff2-be76-b3fa-ddd3e4e600f5

Click OK. Notice that on a Windows system, the pathname appears with double backslashes.

Right-click the JAXRPublishPostal file and choose the Execute menu item.

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

Running the JAXRQueryPostal Example

Like the JAXRPublishPostal example, the JAXRQueryPostal example expects the postal.properties file pathname and the UUID string as command-line arguments. It also expects a query string.

Click the JAXRQueryPostal file in the Filesystems tab.

In the property window for the file, choose the Execution tab.

Click Arguments, then double-click the ellipsis to bring up the property editor.

Enter the pathname of the postal.properties file, the query string, and the UUID string of the classification scheme. On a Windows system, you must specify the full pathname. For example, you might specify the following, all on one line:

D:\\Sun\\AppServer7\\docs\\tutorial\\examples\\jaxr\\
postal.properties coffee uuid:f2be7262-aff2-be76-b3fa-
ddd3e4e600f5

Right-click the JAXRQueryPostal file and choose the Execute menu item.

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

You may or may not want to delete the classification scheme you published. 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. However, once you have created a classification scheme for postal addresses in a public registry, you may want to leave it there for future use.

The Sun ONE Studio internal UDDI Server Registry imposes no limit on the number of classification schemes you can own.

To delete the classification scheme you published after you have finished using it, run the JAXRDeleteScheme program as follows:

Click the Running tab in the main window.

In the Output window tab for either the JAXRSaveClassificationScheme, JAXRPublishPostal, or JAXRQueryPostal example, select the value of the UUID string from the program output. Right-click in the window and choose the Copy menu item.

Click the JAXRDeleteScheme file in the Filesystems tab.

In the property window for the file, choose the Execution tab.

Click Arguments.

Paste the UUID string you copied in step 2 into the value field.

Right-click the JAXRDeleteScheme file in the Filesystems tab and choose the Execute menu item.

The program deletes the specified classification scheme from the registry.

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.

Right-click the file in the Filesystems tab and choose the Execute menu item.

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

Stopping the Internal UDDI Server Registry

If you started the internal UDDI Server Registry, perform the following steps after you have finished using the examples:

Select the Runtime tab of the Explorer.

Expand the UDDI Server Registry node.

Right-click the Internal UDDI Registry node and choose the Stop Server menu item.

All of the material in The J2EE Tutorial for the Sun ONE Platform is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.