test

Service Registry 3 2005Q4 Developer's Guide

Chapter 2 Setting Up a JAXR Client

This section 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 section covers the following topics:

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. See To Stop and Restart the Application Server Domain for the Registry in Service Registry 3 2005Q4 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:

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 2005Q4 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 asant 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 JAXRExamples.properties file. See To Edit the Security Settings of the JAXRExamples.properties File for details.

ProcedureTo Create a Keystore for Your Certificate

To create a JKS keystore for your certificate, you use the asant 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.

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 security.storepass property of the file JAXRExamples.properties.

Steps

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

    For example, you might use the following command:


    cd registry/samples/query-id

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


    asant move-keystore -Dp12path=path_of_p12_file -Dalias=your_user_name
-Dpassword=your_password

    Use a command like the following:


    asant move-keystore -Dp12path=/home/myname/testuser.p12 -Dalias=testuser
-Dpassword=testuser

    To see a syntax reminder for this target, use the command asant -projecthelp.

ProcedureTo Edit the Security Settings of the JAXRExamples.properties File

Steps

  1. Open the file <INSTALL>/registry/samples/common/JAXRExamples.properties in a text editor.

  2. Find the following lines:


    security.keystorePath=<home_dir>/soar/3.0/jaxr-ebxml/security/keystore.jks
security.storepass=ebxmlrr
security.alias=
security.keypass=

  3. To specify the security.keystorePath property, replace <home_dir> with the absolute path of your home directory (for example, /home/myname).

  4. For the value of the security.alias property, specify the user name that you provided to the User Registration Wizard.

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

  6. 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:

Creating or Looking Up a Connection Factory

A client creates a connection from a connection factory. This section describes how to obtain a connection factory in two ways:

Obtaining a ConnectionFactory Instance

To use JAXR in a stand-alone client program, you must obtain an instance of the abstract class ConnectionFactory. To do so, call the getConnectionFactory method in the JAXR provider’s JAXRUtility class.

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

Looking Up a Connection Factory

A JAXR provider can supply one or more preconfigured connection factories for use in J2EE applications. To obtain these factories, clients look them up using the Java Naming and Directory Interface (JNDI) API.

To use JAXR in a deployed J2EE application, you use a connection factory supplied by the JAXR Resource Adapter (RA). To access the connection factory, you need to use a connector resource whose JNDI name is eis/MYSOAR. The Registry configuration process creates this resource. To look up the connection factory in a J2EE component, use code like the following:

import javax.xml.registry.*;
import javax.naming.*;
...
    Context context = new InitialContext();
    ConnectionFactory connFactory = (ConnectionFactory)
         context.lookup("java:comp/env/eis/MYSOAR");

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. (The strings should have no line breaks.)

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

The client then obtains the connection factory as described in Creating or Looking Up 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.

Creating a Connection 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();
LifeCycleManager blcm =
     rs.getLifeCycleManager();

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. The life cycle manager is either a LifeCycleManager object or a BusinessLifeCycleManager object. If the client is using the Registry for simple queries only, it might need to obtain only a query manager.