Java API for XML Registries

We have discussed XML registries and seen the UDDI and ebXML registry service specifications in detail. Now let's put these concepts to service by using the Java API for XML Registries (JAXR).

What Is JAXR?

JAXR specifies a standard interface to invoke all types of XML registries. This allows Java developers to use simple Java method calls to JAXR objects, called JAXR providers, without worrying about how to author XML according to the registry specification. The JAXR provider will author the correct XML structures itself. We'll look at the JAXR specification and architecture in detail here.

JAXR Architecture

Figure 13.6 is a simple illustration of the JAXR architecture.

Figure 13.6. The JAXR architecture.

The following entities are identified in Figure 13.6:

• A client application consisting of two modules: a JAXR client and a JAXR provider.

• An XML registry this might be a UDDI registry or an ebXML registry.

The client application could be a JFC/Swing application that needs to invoke an XML registry. Alternately, it could be a server-side component.

The JAXR client talks to the JAXR provider to invoke the XML registry. The JAXR client does not know anything about the XML syntax or format required by the XML registry. It will issue simple Java method calls to the JAXR provider, which will in turn author the required XML, invoke the XML registry, and bring back the results. Naturally, JAXR providers will have to implement (and expose) several interfaces so that JAXR clients can use them. We'll shortly see the details of these interfaces.

Arrangement of Registry Objects in JAXR

The following are the major classes that JAXR has defined. They map to different data structures of XML registries:

• Organization is the parent structure of all other smaller structures. It represents an organization (perhaps a business organization) that might need several attributes associated with it, such as its description, the name of its contact person, phone number, email address, a list of services that it provides, and so on. All these attributes are also defined as classes.

• InternationalString defines the description about an organization.

• ExternalLink is used whenever we need to refer to some URI that is external to the XML registry.

• PersonName specifies the name of a person (maybe the contact person of an organization). Similarly, EmailAddress specifies an email address, PhoneNumber specifies a phone number, and PostalAddress specifies an address. All these classes (PersonName, EmailAddress, PhoneNumber, and PostalAddress) form structures that combine in a User class. The User object eventually becomes part of the Organization.

• Service represents a service that an Organization offers. Therefore, an Organization may have more than one Service object.

The preceding list is not exhaustive. It only gives you an idea about how JAXR has modeled objects within objects (a tree of objects) to handle XML registry structures. In fact, UDDI also defines a similar tree. You'll see more about UDDI in upcoming chapters.

Putting JAXR to Work

All JAXR classes are packaged in two packages:

• javax.xml.registry Contains API interfaces and classes that define the mechanism for accessing the registry.

• javax.xml.registry.infomodel Contains interfaces and classes that define the types of objects that reside in a registry.

We'll now describe the steps for using JAXR to invoke an XML registry.

Connecting to a Registry

No matter what you want to do with a registry, first you should connect to it. For this purpose, you'll start from the Connection interface (included in the javax.xml.registry package). Connection represents a client session with a JAXR provider. A client must establish a connection with a JAXR provider to use it. The javax.xml.registry package contains a class named ConnectionFactory, which has a static method newInstance. The newInstance method creates a new connection.

You also need to specify the properties of the target XML registry (for example, whether it is a UDDI registry).

Once you have established a connection, you will use the getRegistryService method of the Connection interface to get a RegistryService object. RegistryService is another interface included in the javax.xml.registry package. It enables the client to obtain other interfaces it uses to access the registry.

The following lines of code accomplish this by first creating a Connection and then getting a RegistryService object:

 Properties properties = new Properties();  properties.setProperty("javax.xml.registry.queryManagerURL", file); properties.setProperty("javax.xml.registry.lifeCycleManagerURL",filep); properties.setProperty("javax.xml.registry.factoryClass", "com.sun.xml.registry.uddi. ConnectionFactoryImpl"); ConnectionFactory connectionFactory = ConnectionFactory.newInstance(); connectionFactory.setProperties(properties); Connection connection = connectionFactory.createConnection(); RegistryService regService = connection.getRegistryService(); 

After you have the registry service object, the next step depends upon what you want to do with the registry. Logically, you can either read from (search) the registry, or write to it (publish).

Reading from an XML Registry Through the JAXR Provider

JAXR has provided a BusinessQueryManager interface (also included in the javax.xml.registry package) that handles all types of read operations (search queries) that you might want to execute. The RegistryService object that you already have will give you the BusinessQueryManager object. The following line of code will bring you the BusinessQueryManager object:

 BusinessQueryManager bqm = regService.getBusinessQueryManager();  

BusinessQueryManager has a number of find methods. For example, findOrganizations() will find a number of Organizations matching the search criteria, and findServices() will find all the Service objects matching the search criteria.

We will now look at findOrganizations and findServices in detail. The following lines of code will bring a bulk response containing a list of organizations:

 Collection listOfBusinessNames = new ArrayList();  listOfBusinessNames.add("WaxSys"); listOfBusinessNames.add("Crystal"); listOfBusinessNames.add("Chimera"); BulkResponse response = bqm.findOrganizations(null, listOfBusinessNames, null, null, null,  null); 

Notice that we have passed a collection of strings (listOfBusinessNames) to the findOrganizations() method. This will bring all Organizations with names matching any of the strings that we have included in the listOfBusinessNames collection (WaxSys, Crystal, Chimera).

The findOrganizations() method has several other parameters as well that help in specifying search criteria, but we have used only the listOfBusinessNames as the search criteria.

The BulkResponse returned by the findOrganizations() method might contain a number of organizations. Each organization is represented by an Organization object. The Organization interface is included in the javax.xml.registry.infomodel package. The javax.xml.registry.infomodel package represents the information model of JAXR. All data structures (such as Organization, Service, ServiceBinding, User, and so on) representing information contained in an XML registry are included as interfaces in this package.

The following lines of code will read the first Organization object from the BulkResponse:

 Collection organizations = br.getCollection();  Iterator orgIter = organizations.iterator(); while (orgIter.hasNext()) {   Organization org =(Organization) orgIter.next();   System.out.println("Organization name: " + org.getName());   System.out.println("Organization description: " + org.getDescription());   System.out.println("Organization Key ID: " + org.getKey().getId(); } 

Every organization in BulkResponse is identified by a unique identification. We can use this identification to get more details about the organization, such as the services it offers. The following line of code shows how to get the key:

 String myBusinessKey = org.getKey().getId()  

We will pass this key to the findServices() method to get a list of all the services that this organization offers:

 BulkResponse response = bqm.findServices (myBusinessKey, null, null, null, null);  

The findServices() method also returns a BulkResponse. You can iterate through the BulkResponse to learn more details about the service. For this, you will call the getCollection() method of BulkResponse to get a collection of Service objects. You will then call the Iterator() method of the Collection object and iterate on the returned Iterator object.

We have discussed the use of BusinessQueryManager for reading business services data from an XML registry. There are a number of possible read operations (queries) that can be performed on an XML registry. You will follow the preceding approach for any query requirement.

Writing Data to an XML Registry Through a JAXR Provider

JAXR has provided a BusinessLifeCycleManager interface in the javax.xml.registry package that handles all write operations (create, save, update, delete, and so on) that you might want to perform on an XML registry.

The first step for writing to an XML registry is the same as the read operation: get the RegistryService object. After you have the RegistryService object, you will call its getBusinessLifeCycleManager() method to get the BusinessLifeCycleManager object:

 BusinessLifeCycleManager blcm = regService.getBusinessLifeCycleManager();  

Writing data to an XML registry requires authentication. Before you can use the BusinessLifeCycleManager to write data to an XML registry, you should get authentication from the registry by providing a username and password. The question of how to obtain a username and password are not addressed by JAXR. Obtaining a username and password is a registry-specific task, so you will have to obtain them from some other process.

When you have the username and password, you will pass them on to the PasswordAuthentication constructor. The next step is to add this to your credentials. The following code shows how to do this:

 String username = "bsiddiqui";  String password = "121lhr"; PasswordAuthentication passwdAuth = new PasswordAuthentication (username, password. toCharArray()); Set creds = new HashSet(); creds.add(passwdAuth); connection.setCredentials(creds); 

Now you are all set to start writing to the registry. BusinessLifeCycleManager has a number of methods to write an organization record in an XML registry; for example, organization, classification, service and service binding, and so on. We will demonstrate how to create a new organization and add a service to it.

The first step is to create a new organization:

 Organization organization = blcm.createOrganization("MyBusinessOrganization");  

The CreateOrganization() method returns a newly created organization object. We will add the following structures one by one to this organization object:

• Description (an InternationalString object containing a brief description about the organization)

• Contacts (whom to contact in this organization, specified by a User object)

• Services (services offered by this organization)

The following line of code shows how to add a description to the organization. You first create a description on the BusinessLifeCycleManager and then call the setDescription() method of the organization object:

 InternationalString description = blcm.createInternationalString("J2EE and XML get  married");  organization.setDescription(description); 

To add a contact, you will use several JAXR classes, namely PersonName, TelephoneNumber,and EmailAddress. You will create objects of these classes and then add them to the User class one by one:

 User primaryContact = blcm.createUser();  PersonName pName = blcm.createPersonName("BiBi"); primaryContact.setPersonName(pName); TelephoneNumber tNum = blcm.createTelephoneNumber(); tNum.setNumber("(92) 300-8484756"); Collection phoneNums = new ArrayList(); phoneNums.add(tNum); primaryContact.setTelephoneNumbers(phoneNums); EmailAddress emailAddress = blcm.createEmailAddress("[e-mail] "); Collection emailAddresses = new ArrayList(); emailAddresses.add(emailAddress); primaryContact.setEmailAddresses(emailAddresses); 

After the user is ready, you will set this user as the primary contact in the organization:

 organization.setPrimaryContact(primaryContact);  

To add services to an organization, you will create services individually, set their descriptions, add these services to a collection, and then add this collection to the organization object:

 Collection services = new ArrayList();  Service service = blcm.createService("Service Name"); InternationalString serviceDesc = blcm.createInternationalString("My Service Desc"); service.setDescription(serviceDesc); services.add(service); organization.addServices(services); 

In the preceding code, you can see that we have a hierarchy of data structures (objects). Smaller data objects become a part of larger data objects and so on, until everything finally gets placed in an organization object.