Chapter 2 Setting Up a JAXR Client

This chapter describes the first steps to follow to implement a JAXR client that can perform queries and updates to Service Registry. A JAXR client is a client program that uses the JAXR API to access registries.

This chapter covers the following topics:

• Starting the Registry

• Getting Access to the Registry

• Establishing a Connection to the Registry

• Obtaining and Using a RegistryService Object

Starting the Registry

To start the Registry, you start the container where the Registry is installed, the Sun Java System Application Server.

If the Registry is not already running, start it or ask your system administrator to do so. See To Stop and Restart the Application Server Domain for the Registry in Service Registry 3.1 Administration Guide for instructions.

Getting Access to the Registry

Any user of a JAXR client can perform queries on the Registry for objects that are not restricted by an access control policy. A user must, however, obtain permission from the Registry for the following actions:

• To add data to the Registry

• To update Registry data

• To perform queries for restricted objects

The Registry uses client-certificate authentication for user access.

To create a user that can submit data to the Registry, use the User Registration Wizard of the Web Console. The Web Console is part of the Registry software. For details on using the wizard to obtain a user name and password as well as a certificate that authorizes you to use the Registry, see Creating a User Account in Service Registry 3.1 User’s Guide. You can also use an existing certificate that you obtained from a certificate authority.

Before you can publish to the Registry, you must move the certificate from the .p12 file that you downloaded to a JKS keystore file. The keystore file must reside at the following location in your home directory: $HOME/soar/3.0/jaxr-ebxml/security/keystore.jks. The example programs include an Ant target that performs this task. For details, see To Create a Keystore for Your Certificate.

After you create a user account and a keystore, edit the build.properties file. See To Edit the Security Settings of the build.properties File for details.

To Create a Keystore for Your Certificate

To create a JKS keystore for your certificate, you use the Ant target move-keystore, which is defined in the file INSTALL/registry-samples/common/targets.xml. This targets file is used by all the build.xml files in the example directories.

---

Note –

The Admin Tool keystoreMover command performs the same function as this Ant target. See keystoreMover in Service Registry 3.1 Administration Guide for details.

---

The move-keystore target uses a property named keystoreFile that is defined in the file INSTALL/registry-samples/common/build.properties. Do not change the definition of this property. The move-keystore target also specifies a keystore password of ebxmlrr. This value is used in the storepass property of the file build.properties.

1. Go to any of the example directories except common.

   For example, you might use the following command:

   cd registry-samples/search-id

2. Run the following command (all on one line):

   Ant-base/ant move-keystore -Dp12path=path-of-p12-file -Dalias=your-user-name -Dpassword=your-password

   Use a command like the following:

   Ant-base/ant move-keystore -Dp12path=/home/myname/testuser.p12 -Dalias=testuser -Dpassword=testuser

   To see a syntax reminder for this target, use the command Ant-base/ant -projecthelp.

To Edit the Security Settings of the build.properties File

1. Open the file INSTALL/registry-samples/common/build.properties in a text editor.

2. Find the following lines:

   alias= keypass=

3. For the value of the alias property, specify the alias that you provided to the User Registration Wizard.

4. For the value of the keypass property, specify the password that you provided to the User Registration Wizard.

5. Save and close the file.

Establishing a Connection to the Registry

The first task that a JAXR client must complete is to establish a connection to a registry. Establishment of a connection involves the following tasks:

• Obtaining a Connection Factory

• Creating a Connection

Obtaining a Connection Factory

A client creates a connection from a connection factory. To obtain an instance of the abstract class ConnectionFactory, the client calls the getConnectionFactory method in the JAXR provider’s JAXRUtility class.

import org.freebxml.omar.client.xml.registry.util.JAXRUtility;
...
ConnectionFactory factory = JAXRUtility.getConnectionFactory();

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 to be accessed. The following code provides the URLs of the query service and publishing service for the Registry if the Registry is deployed on the local system.

Properties props = new Properties();
props.setProperty("javax.xml.registry.queryManagerURL",
    "http://localhost:6480/soar/registry/soap");
props.setProperty("javax.xml.registry.lifeCycleManagerURL",
    "http://localhost:6480/soar/registry/soap");

The client then obtains the connection factory as described in Obtaining a Connection Factory, sets its properties, and creates the connection. The following code fragment performs these tasks:

ConnectionFactory factory = JAXRUtility.getConnectionFactory();
factory.setProperties(props);
Connection connection = factory.createConnection();

The makeConnection method in the sample programs shows the steps used to create a JAXR connection.

Table 2–1 lists and describes the two properties that you can set on a connection. These properties are defined in the JAXR specification.

Table 2–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

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 that the client will use:

RegistryService rs = connection.getRegistryService();
DeclarativeQueryManager bqm = rs.getDeclarativeQueryManager();
BusinessLifeCycleManager blcm = rs.getBusinessLifeCycleManager();

Typically, a client obtains two objects from the RegistryService object: a query manager and a life cycle manager. The query manager is either a DeclarativeQueryManager object or a BusinessQueryManager object; both of these implement the base interface QueryManager. The life cycle manager is a BusinessLifeCycleManager object, which implements the base interface LifeCycleManager. If the client is using the Registry for simple queries only, it might need to obtain only a query manager.

If your program uses implementation-specific features of the Service Registry JAXR provider, you need to use the implementation-specific version of the respective query manager or life cycle manager: BusinessQueryManagerImpl, DeclarativeQueryManagerImpl, or BusinessLifeCycleManagerImpl.