Introduction

IBM® WebSphere® Service Registry and Repository V6 (hereafter referred to as Service Registry and Repository) is an industrial-strength tool that helps you achieve more business value from your service-oriented architecture (SOA) by enabling better management and governance of your services. You can use Service Registry and Repository to store information about services in your systems, or in other organizations' systems, that you already use, plan to use, or want to be aware of. For example, an application can check with Service Registry and Repository just before it invokes a service to locate the most appropriate service that satisfies its functional and performance needs. This capability helps make your SOA deployment more dynamic and more adaptable to changing business conditions.

Service Registry and Repository provides management for Service Metadata including WSDL and XML Schema documents. Service Registry and Repository maintains relationships between the documents in its database. These relationships can be manipulated at creation time to allow the user fine-grained control over specific versions of their services.

Before you begin this article, install WebSphere Service Registry and Repository to make full use of this article and the examples. A simple Java™ program using the EJB API shows how to tackle this subject programmatically. You should also download the code from the Downloads section of this article.

Use the instructions from Tim Baldwin's article on sample applications for WebSphere Service Registry and Repository, Introducing WebSphere Service Registry and Repository APIs to install the samples (see Resources). Use the sample name of "EJB-VersioningWithCollections". The code is available in the class "com.ibm.wsrr.samples.ejb.VersioningWithCollections".

Creating a document

Let's begin by creating an entry in the Repository, so that we have a document to work with. We can start with an XML Schema Document, in our case, myXmlSchemaDocument.xsd. When creating the document, you can add a version.

Tip: Notice that once a document has been created, the version cannot be changed.

The version field is a free format string in WebSphere Service Registry and Repository that lets you use any type of versioning system. By default, it is an empty string. For this example, set the version to 2.0.

1. Direct your browser to the machine running the Service Registry and Repository. The URL is usually of the form: http://hostname:9080/ServiceRegistry.
2. Select Service Documents => XSD Documents => Load Document (see Figure 1).
   
   Figure 1. Screenshot showing loading screen for myXmlSchemaDocument.xsd
   
   
   
3. Now that you've created the document, view it by selecting Service Documents=> XSD Documents.
4. Select myXmlSchemaDocument.xsd. The details view shows the version of the document is set to 2.0. See Figure 2.
   
   Figure 2. Screenshot showing summary screen for myXmlSchemaDocument.xsd
   
   
   
5. Select the content tab to view the document source. Additionally, you can download the original document by selecting the download document button (see Figure 3).
   
   Figure 3. Content screen for myXmlSchemaDocument.xsd
   
   
   

Linking versions

The Web Service, myWebService, can perform operations, but needs a datatype definition from myXmlSchemaDocument.xsd to do so. myWebService is defined by myWebService.wsdl.

In this example, we want to link to a particular version of myXmlSchemaDocument, version 2.0, that we created earlier. If we were to supply the Registry simply with myWebService.wsdl, the system would have no way of telling which version we wanted to link to.

Important technical note: The repository by default will only link to documents that do not have a version. In the example above, a new version-less myXmlSchemaDocument.xsd would be created in the repository from the URI in myWebService.wsdl.

So how do we logically associate documents together in the registry such that we can tell which versions belong together?

The answer lies within a new object called a GenericObject. We need to create a GenericObject to represent our collection of services and schemas that we want associated in the registry.

The structure that we are going to build looks like the collection hierarchy (see Figure 4):

In order to use collections, you need to use the WebSphere Service Registry and Repository API, rather than the Web User Interface (UI). This article uses the EJB API, but alternatively, you can also use the Web Services API or the command line interface.

Creating a generic object

Use the following steps to create a generic object to represent the collection of services and schemas that we want associated in the registry.

1. Create a generic object named, GenericObject, with the code in Listing 1.
   
   Listing 1. Create a GenericObject
   

   GenericObject myGenericObject = (GenericObject)DataFactory.INSTANCE.create(TypeConstants.SR_URI, TypeConstants.TYPE_GENERICOBJECT); // Generic objects must have a name set. myGenericObject.setName("myCollection");

   
   
2. Create the new myWsdlService.wsdl (see Listing 2).
   
   Listing 2. Create the wsdl document
   

   // Example code to create myWebService.wsdl which imports myXmlSchemaDocument.xsd FileInputStream is = new FileInputStream("resources/myWebService.wsdl"); WSDLDocument myWebServicesDoc = (WSDLDocument)SRXMLHelper.INSTANCE.load(is, TypeConstants.TYPE_WSDLDOCUMENT); myWebServicesDoc.setName("myWebService.wsdl"); myWebServicesDoc.setLocation("myWebService.wsdl");

   
   
3. Create the code to retrieve the myXmlSchema.xsd version 2.0 that we created earlier.
   
   Listing 3. Retrieve the xml schema document
   

   // Example code to retrieve myXmlSchema.xsd with a version string of "2.0" // Assuming we don't already know the bsrURI of the required XSD document we // need to run a property query. PropertyQuery propertyQuery = (PropertyQuery)DataFactory.INSTANCE.create(TypeConstants.SR_URI, TypeConstants.TYPE_PROPERTYQUERY); String xpath = "/WSRR/XSDDocument[@name='myXmlSchemaDocument.xsd" " + "and @version='2.0' " + "and @namespace='http://com.ibm.wsrr.samples/xsd']"; propertyQuery.setQueryExpression(xpath); // We only need the "bsrURI" of the XSDDocument BSRSDOHelper.INSTANCE.addProperty(propertyQuery, "prop1", "bsrURI"); System.out.println(" running query " + xpath); List results = serviceRegistry.executeQuery(propertyQuery); propertyQuery = null; //The result size should be 1. System.out.println(" result size = " + results.size()); PropertyQueryResult result = (PropertyQueryResult)results.get(0); String myXmlSchemaDocumentBsrUri = BSRSDOHelper.INSTANCE.getPropertyQueryResultValue(result, "bsrURI"); System.out.println(" result: " + myXmlSchemaDocumentBsrUri); // Example code to retrieve myXmlSchema.xsd with a version string of "2.0" // given its bsrURI System.out.println(" retrieving myXmlSchemaDocument.xsd from the repository"); XSDDocument myXmlSchemaDoc = (XSDDocument)serviceRegistry.retrieve(myXmlSchemaDocumentBsrUri);

   
   
4. Link the documents together under the GenericObject myCollection using two user defined relationships (see Listing 4 below).
   
   Listing 4. Link the objects
   

   BSRSDOHelper.INSTANCE.addRelationship(myGenericObject,"myRelationship1", myWebServicesDoc); BSRSDOHelper.INSTANCE.addRelationship(myGenericObject,"myRelationship2", myXmlSchemaDoc);

   
   
5. Now that the collection is complete, send it to the registry to be stored (see Listing 5).
   
   Listing 5. Persist the collection
   

   serviceRegistry.create(myGenericObject);

   
   

Good job! You've saved the document and associated it with the correct version!

Notice that when creating collections, if the registry fails to find the document that it is trying to resolve from an import link, it will look first in the Repository itself, and follow the document URI secondly.

Making sure everything works

Let's check that everything went as planned.

1. Find the WSDL document. Select Service Documents => WSDL Documents (see Figure 5).
   
   Figure 5. myWebService.wsdl
   
   
   
2. Select myWebService.wsdl => imported schemas (see Figure 6).
   
   Figure 6. Screenshot showing the imported schemas
   
   
   
3. Select myXmlSchemaDocument.xsd and check that the version is 2.0 as expected.
4. Objects of type GenericObject are known as Concepts in the Service Registry and Repository Web UI. To view the GenericObject that we created earlier, select Unified Service Metadata => Concepts (see Figure 7).
   
   Figure 7. The GenericObject
   
   
   

Important technical note: The GenericObject is no longer required now that the association has been created between the documents. Deleting the GenericObject will not affect the imported XSD Documents relationship.

Congratulations! You successfully created a schema document with a version and then associated it with a new Web service in the WebSphere Service Registry and Repository.

Conclusion

You have been introduced to the concept of using a collection to manage documents. In this article you were taken through step-by-step instructions for creating and managing versioned documents within WebSphere Service Registry and Repository. You created a versioned schema document within the Repository and then deliberately associated a new Web service with this specific versioned schema document. Future articles in this series will go into more advanced scenarios covering detailed explanations of the scoping rules and how to use collections from the Web Services API.

Back to top

Downloads

Information about download methods

Resources

• "Introducing WebSphere Service Registry and Repository APIs" (developerWorks, November 2006) is an introduction to Service Registry and Repository APIs. You can use the sample name of "EJB-VersioningWithCollections". The code is available in the class "com.ibm.wsrr.samples.ejb.VersioningWithCollections".
  
  
• IBM WebSphere Service Registry and Repository product information provides information about Service Registry features and enhancements.
  
  
• The WebSphere Service Registry and Repository InfoCenter provides resources to help you get started with Service Registry.
  
  
• "Introducing IBM WebSphere Service Registry and Repository, Part 1" (developerWorks, Sept 2006) is an introduction to the main concepts and capabilities of the WebSphere Service Registry and Repository.
  
  
• "Introducing IBM WebSphere Service Registry and Repository, Part 2" (developerWorks, Sept 2006) is an architectural overview of the WebSphere Service Registry and Repository, its capabilities and its role throughout the service-oriented architecture (SOA) lifecycle.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Creating a document
• Linking versions
• Creating a generic object
• Making sure everything works
• Conclusion
• Downloads
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Service Registry and Repository
• Article: WebSphere Service Registry and Repository
• Buy: WebSphere Service Registry and Repository

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers