7.3 Using the JAXR Examples | Java Web Services in a Nutshell

In order to use the example source code for this chapter, you need to install and configure the JAXR providers that you intend to use and set a small number of properties that the examples will use to locate and connect to the registry.

7.3.1 Using a UDDI Registry

Since the JAXR reference implementation includes a UDDI provider and a UDDI registry server, it is very simple to use the example source code with this registry type. The following sections describe what you need to do.

7.3.1.1 Edit the jwsnutJaxrExamples.properties file

The jwsnutJaxrExamples.properties file in your home directory (which should have been created according to the instructions given in Examples Online in the Preface) specifies the authentication information for the UDDI registry server and the URLs required to access it. In most cases, the default settings in this file, shown here, are appropriate:

 #  # User name and password for the UDDI JAXR registry server # JAXR_UDDI_USER = testuser JAXR_UDDI_PASSWORD = testuser # # URLs for the UDDI JAXR registry server # JAXR_UDDI_SERVER_QUERY_URL =       ${WEBURL}/${REGISTRY_SERVER_APP}/RegistryServerServlet JAXR_UDDI_SERVER_LIFECYCLE_URL =       ${WEBURL}/${REGISTRY_SERVER_APP}/ RegistryServerServlet

The JAXR_UDDI_USER and JAXR_UDDI_PASSWORD properties should be set to the username and password required to access the UDDI registry. The settings shown here are appropriate for the user that is already defined in the registry when you install the JWSDP or J2EE 1.4. If you intend to use a different test UDDI registry (such as those provided by the UDDI registry operators), you need to register with them and obtain a username and password.

The JAXR_UDDI_SERVER_QUERY_URL and JAXR_UDDI_SERVER_LIFECYCLE_URL properties are the URLs that should be used to send queries to the registry and to make registry updates, respectively. The values just shown are correct for the reference implementation, which is deployed as a service in the Tomcat web container or, in the case of the J2EE 1.4 platform, as an external service accessed via a connector. If you register with one of the UDDI operators, you should enter the appropriate URLs here. Note that registry queries typically do not require authentication and usually use the HTTP protocol, whereas updates are permitted only to registered users and require HTTPS. The reference implementation is a special case that uses HTTP in both cases (although it does require a valid username and password for updates).

7.3.1.2 Start the registry server

If you are using the registry in the JAXR reference implementation, you need to ensure that the Tomcat web container is running before attempting to use the example source code. This registry stores its data in an XML-based database called Xindice , which is also provided as part of the reference implementation. If you are using J2EE 1.4, you can start the registry server and the database at the same time as the J2EE application server by supplying the -startRegistry argument to its startup script:

 j2ee -startRegistry

If you are using the JWSDP, the registry server is started automatically.

7.3.1.3 Install the sample registry data

The example source code uses sample registry data that must be installed before any of the examples can be executed. To install the data, open a command window, make chapter7\setup (relative to the installation directory of the example source code) your working directory, and type the commands:

 ant compile ant run-uddi-install-client

The data only needs to be installed once. You can clean up your registry at any time using the run-uddi-delete-client target of the Ant buildfile:

 ant run-uddi-delete-client

7.3.2 Using an ebXML Registry

The JWSDP reference implementation does not include either an ebXML JAXR provider or an ebXML registry server. If you intend to run any of the examples that illustrate level 1 JAXR facilities, you need to obtain at least an ebXML JAXR provider. Having done so, you can then make use of a public test ebXML registry. Alternatively (and probably more conveniently), you can install a test registry of your own.

One source for both a provider and a registry server can be found at http://ebxmlrr. sourceforge .net. This site contains source and binary distributions for both components , together with installation and setup instructions. Having installed the software and deployed the registry server in the Tomcat web container using the instructions provided at the web site, follow the instructions shown next to configure the registry and set up the example source code to use it.

The example source code assumes that it is using the ebXML provider and registry from the web site just given. This assumption is necessary because the means by which a registry client authenticates to the registry, which is necessary in order to update its content, is registry-specific. The following instructions are specific to this particular registry implementation ” if you plan to use a different implementation, you may have to modify the example source code and perform the setup differently.

7.3.2.1 Create configuration files for the ebXML registry server

Among the files for the ebXML registry server there is one called ebxmlrr.properties . If the machine on which you are running the server is not connected to the Internet, you should copy this file to your home directory and edit the copy to look like the lines shown here so that both properties are set to false:

 #Decide whether to checkURLs in external links or not # ebxmlrr.persistence.rdb.ExternalLinkDAO.checkURLs=  false  #Decide whether to checkURLs in service bindings or not # ebxmlrr.persistence.rdb.ServiceBindingDAO.checkURLs=  false

You do not need to do this if your registry server will have Internet access.

7.3.2.2 Start the registry server

The registry server is deployed as a web application on the Tomcat web container; therefore, it is started at the same time as the web container itself. If the web container is currently active, stop and restart it so that the registry server reads the ebxmlrr.properties file set up in the previous step.

7.3.2.3 Create a registry user

The example source code needs to install some test data in the registry. Since only registered users can update the registry, you need to create an identity for yourself. As you'll see in Section 7.5.10 at the end of this chapter, an ebXML registry requires a client to provide a certificate as proof of identity. Therefore, part of the process of creating a new registry user involves obtaining a suitable certificate. The simplest way to do this is to use the registry browser that is supplied with the registry. Before you can do this, you need to create a file called .java.login.config in your home directory and add the following lines to it:

 JAXRTest {  com.sun.security.auth.module.KeyStoreLoginModule required debug=true   keyStoreURL="file://c:/homedir//jaxr-ebxml/security/keystore.jks";  };   jaxr-ebxml-provider {  com.sun.security.auth.module.KeyStoreLoginModule required debug=true   keyStoreURL="file://c:/homedir/jaxr-ebxml/security/keystore.jks";  };

c:/homedir should be replaced by the path name of your home directory. On a Windows system, this would be something like c:/Documents and Settings/My Name . Note that forward slashes are acceptable (since this is a URL) and that the text shown in bold should appear on a single line (even though it is split over two lines here for the sake of readability).

Next, copy the file jaxr-ebxml.properties from the ebXML download to your home directory and modify the lines beginning with jaxr-ebxml.security so that they look like this:

 jaxr-ebxml.security.keystore=security/keystore.jks jaxr-ebxml.security.storepass=ebXMLStorePassword jaxr-ebxml.security.keypass=ebXMLKeyPassword

These lines are used to create the keystore for the certificate that is used to authenticate you to the registry server. You do not have to use the values for the storepass and keypass keys shown here, but if you change them, you must remember to use the same values when registering yourself with the server.

Now start the registry browser by making the root directory of the registry server download your working directory and typing the command:

 ant run.browser

Select the URL of the registry in the Registry Location field (this is http://localhost:8080/ebxmlrr/registry/soap if the web container is running on your local system) and then press the "Show User Registration Wizard" toolbar button (which has an icon showing a person and a small green cross). This displays a dialog that allows you to create your identity within the registry. Many of the fields in this dialog can be left empty. However, you must provide at least a username, and you must complete the following fields that appear at the bottom of the dialog:

Keystore Alias: This is the name under which the certificate that authenticates you will be held within the keystore. You should remember the value that you enter here, because you will need to use it later. As an example, I'll suppose that you choose the alias ebXMLtestuser .
Keystore Password: This is the password that will be used to protect the keystore. You should use the value assigned to the jaxr-ebxml.security.storepass key in the jaxr-ebxml.properties file, which, in the example just shown, is ebXMLStorePassword .
Private Key Password: This is the password that will be used to protect the private key corresponding to your certificate in the keystore. You should use the value assigned to the jaxr-ebxml.security.keypass key in the jaxr-ebxml.properties file, which, in the example just shown, is ebXMLKeyPassword .

Once you complete the dialog, press the OK button. You are then presented with another dialog that authenticates you to the registry server using the certificate that has just been created. Enter the same alias and passwords that you supplied to the registration wizard and press OK . If you don't see any errors, then your identity has been successfully registered.

7.3.2.4 Edit the jwsnutJaxrExamples.properties file

Several properties need to be set in the jwsnutJaxrExamples.properties file in your home directory before you can successfully run the example source code with an ebXML registry. Typical settings for these properties are shown here.

 # # URLs for the ebXML JAXR registry server, if installed # JAXR_EBXML_SERVER_QUERY_URL = ${WEBURL}/ebxmlrr/registry/soap JAXR_EBXML_SERVER_LIFECYCLE_URL = ${WEBURL}/ebxmlrr/registry/soap # Location of the lib directory for the ebXML registry # provider, if it is installed. This should be something # like c:/ebxmlrr-client/lib. JAXR_EBXML_PROVIDER=c:/ebxmlrr-client/lib #  # Authentication for the ebXML JAXR registry server. # JAXR_EBXML_KEYSTORE_FILE=${user.home}/jaxr-ebxml/security/keystore.jks JAXR_EBXML_ALIAS = ebXMLtestuser JAXR_EBXML_KEY_PASSWORD = ebXMLKeyPassword JAXR_EBXML_KEYSTORE_PASSWORD = ebXMLStorePassword

JAXR_EBXML_SERVER_QUERY_URL and JAXR_EBXML_SERVER_LIFECYCLE_URL are the URLs that map to the registry server's query and update functionality. The values shown here are correct for the default deployment in the Tomcat web container.

The JAXR_EBXML_PROVIDER property is the full pathname of the directory in which the client-side JAR files for the ebXML JAXR provider are located. The correct path depends on where you install the JAXR provider. You can easily locate it by looking for a file called jaxr-ebxml.jar .

The remaining properties relate to the keystore for the user that you registered earlier in Section 7.3.2.3. The JAXR_EBXML_KEYSTORE_FILE property supplies the full pathname of the keystore itself. You may use the property ${user.home} to refer to your home directory, as shown here. The location of the keystore is always ${user.home}/jaxr-ebxml/ , followed by the value of the jaxr-ebxml.security.keystore property from the file jaxr-ebxml.properties ; hence, the value shown here is correct if you use the settings shown in Section 7.3.2.3. The JAXR_EBXML_ALIAS , JAXR_EBXML_KEY_PASSWORD , and JAXR_EBXML_KEYSTORE_PASSWORD properties must have the same values as those supplied when completing the user details in the user registration wizard of the registry browser, as the values shown here illustrate.

7.3.2.5 Install the sample registry data

With all of the configuration details in place, the last step is to install the test data in the registry. Make sure that the Tomcat web server is running, then make chapter7\setup (relative to the installation directory of the example source code) your working directory and type the commands:

 ant compile ant run-ebxml-install-client

The data only needs to be installed once. You can clean up your registry at any time using the run-ebxml-delete-client target of the Ant buildfile:

 ant run-ebxml-delete-client

Note that, since the UDDI and ebXML registries are separate, installing or removing the data for one of them has no effect on the other.