Introduction

IBM® WebSphere® Service Registry and Repository (hereafter known as Registry and Repository) is the master metadata repository for service interaction endpoint descriptions within a service-oriented architecture (SOA) environment. End-users can interact directly with Registry and Repository using a Web-based console application or an Eclipse-based plug-in. In addition, applications can fully interact with Registry and Repository using one or more of its Application Programming Interfaces (APIs). All the operations that can be performed using the Web-based console or the Eclipse plug-in can also be performed by application programs by using the API. In fact, the Web console and Eclipse plug-in are themselves simply applications written to use the Registry and Repository APIs.

This article briefly introduces some of the Registry and Repository APIs and illustrates their use with a comprehensive set of sample applications. The article concentrates on the J2EE-based EJB APIs, but in addition, a Web service API and a JMX-based administration API are also available. Subsequent articles may explore these other APIs in more detail.

Requirements

No special requirements are needed if you just want to browse through the sample applications; they are simply a set of Java™ programs and are provided in source code form.

If you want to run the samples, you will need access to an installed and running Registry and Repository server against which you have the authority to create, update, and delete registry documents. You will also need a J2EE application client environment from which to run the sample application.

To modify the samples to examine the source in greater detail or to run in a debug environment, you will need the Rational Software Development Platform.

Downloads

The bulk of the information provided by this article is supplied as a set of sample applications delivered by the associated downloads. The sample applications contain fully commented Java source code illustrating the use of most of the available Registry and Repository EJB-based APIs. Two downloads are provided:

1. The application (WSRRSamplesEAR.ear)

   Packaged as a J2EE client application EAR file, this can be run directly from the IBM WebSphere V6 application client environment.

2. The source code (WSRRSamplesSRC.zip)

   Packaged as two projects that can be imported to the IBM Rational Software Development Platform, this contains a convenient way to examine, modify, and run the source code for the application.

This rest of this article will outline how to install, run, and use these downloads and will briefly describe the set of sample applications provided.

Working with the sample application

You can obtain the application by downloading the associated WSRRSamplesEAR.ear file (see Downloads). This application has been designed to run with and has been tested using the IBM WebSphere V6 J2EE application client container using the launchClient command. It can be run on the same machine as IBM WebSphere Application Server (hereafter known as Application Server) that is running the Registry and Repository application by using the launchClient command from the server's bin directory, or it can be run from a remote client machine by installing the Application Client for Application Server V6.

Installing the sample application

To install the sample application, create a directory on your machine to hold the sample code. To illustrate, we assume you are using Windows and create a directory called C:\WSRRSample.

Download the WSRRSamplesEAR.ear file from the Downloads section of this article and put the EAR file into your C:\WSRRSample directory. In addition to the sample client application itself, the EAR file contains some extra resources that are required before the samples can be run. These additional resources need to be extracted from the EAR before it can be used. To do this, use a program such as WinZip or Unzip to unpack the EAR file into your samples directory. This should give you (among other things) the following files:

C:\WSRRSample\sdo-int.jar
C:\WSRRSample\resources\StockQuote.wsdl
C:\WSRRSample\resources\StockQuoteService.wsdl
C:\WSRRSample\resources\StockQuoteBinding.wsdl
C:\WSRRSample\resources\StockQuoteInterface.wsdl
C:\WSRRSample\resources\PurchaseOrder.xsd
C:\WSRRSample\resources\PurchaseOrder.xml
C:\WSRRSample\resources\SampleFruit.owl

Running the sample application

Run the sample applications using Application Server V6. launchClient command.

Before you can run the samples, update Application Server V6 or the Application Server V6 Application Client that you plan to use to add support for the later level of SDO required by Registry and Repository. To do this, you must copy the sdo-int.jar file from your samples directory to the classes directory of the Application Server or the client installation (you may need to create the classes directory if it does not already exist); typically this will be something like "C:\Program Files\IBM\WebSphere\AppServer\classes" or "C:\Program Files\IBM\WebSphere\AppClient\classes". If you are using an application server on which Registry and Repository itself has previously been installed you should find the sdo-int.jar is already present in the classes directory.

Some of the sample applications require that the ontology system from the SampleFruit.owl file is pre-loaded into Registry and Repository. The easiest way to do this is to use the Registry and Repository console application to load the OWL file from your C:\WSRRSample\resources directory.

To run the samples, ensure that your current working directory is C:\WSRRSample and issue the following command (this should all appear on one line):

<was_install_base>\bin\launchClient WSRRSamplesEAR.ear
        -CCproviderURL=iiop://<wsrr_host_server> EJB-SimpleDocument

Where:

• was_install_base is the root of your Application Server or client installation. Typically this will be something like "C:\Program Files\IBM\WebSphere\AppServer" or "C:\Program Files\IBM\WebSphere\AppClient".
• wsrr_host_server is the host name and nameserver port for Registry and Repository that you want to access. If the nameserver port is the default port 2809, this can be omitted. To access a private instance of Registry and Repository running on your local machine, you might specify iiop://localhost:2809/.
• EJB-SimpleDocument is the name of the sample application you want to run. This can be any of the sample application names listed in Table 1 below.

If the sample application runs successfully, you will see a number of progress messages written to the console. If something does not work, you will see Java exceptions reported.

Working with the sample source code

You can further unpack the WSRRSamples.jar file from the expanded application EAR file to view the source code for the applications; however, it is easier and probably more useful to install the associated source code projects into a Rational Software Development Platform environment. The samples were developed and tested using Rational Software Architect V6.0.1.1 but should be compatible with the other products in the IBM Rational Software Development Platform that support the development of WebSphere J2EE applications, such as Rational Application Developer for WebSphere.

Installing the sample source code

To install the source code projects, download the WSRRSamplesSRC.zip file from the Downloads section of this article.

From inside the Rational Software Development Platform, select File => Import and choose the Project Interchange import source. In the import dialog, select the previously downloaded WSRRSamplesSRC.zip file and import into your workspace the two projects contained within it:

• WSRRSamples

  This is a Java project containing the source code for the samples themselves.

• WSRRSamplesEAR

  This is an Enterprise Application project that contains the extra resources needed for the samples and is used to package the final client application EAR file.

The sample source code structure

The WSRRSamples project is a standard J2EE Application Client Project, all the source code is contained in the appClientModule folder. The default package contains a Main class that processes the program arguments (in this case, that is the name of the sample that is to be run) and creates and invokes an instance of the required sample application class.

The samples themselves are all found in the com.ibm.wsrr.samples.ejb package. Each sample extends a base class called EJBSample that provides an invocation framework and some methods common to all the samples:

• The setUp() and a tearDown() methods are called respectively before and after the main run() method for each sample. The main purpose of these methods is to remove any documents and objects related to the sample applications from the registry both before trying to run the sample, to ensure it starts in a clean environment, and at the end to try to tidy up. However, if exceptions are thrown when running a sample, it might leave some documents and objects in the registry.

  In addition, the setUp() method always ensures that all the Registry and Repository datatypes are correctly registered with SDO, this is something all Registry and Repository applications should do before any Registry and Repository APIs are invoked.

• The three methods getServiceRegistrySession(), getServiceRegistryGovernance() and getServiceRegistryOntology() are used by all the sample applications to obtain references to the three Registry and Repository API EJBs. Note that for clarity in the samples, there is no exception handling associated with these methods. A real application would need to check for and handle errors when trying to create the EJB instances.

Running the sample source code

To run the sample applications from inside the Rational Software Development Platform, you must create a suitable run-configuration.

Use these steps to run the sample:

1. Select the Run => Run option from the menus.
2. From the run-configuration dialog box, select (from the left-hand side) Application Server V6 Application Client configuration and click New.
3. Give the new configuration a suitable name.
4. Adjust the Application, Arguments and Classpath settings as follows:

From the Application tab:

• In the Enterprise application section, click the pulldown arrow and select the WSRRSamplesEAR.
• In the Application client module section, click the pulldown arrow and select WSRRSamples.
• Check the box labeled Enable application client to connect to a server.
• Below this, select the Use provider URL option and in the text box enter a URL of the form iiop://wsrr_host_server:port where wsrr_host_server is the host name and port is the nameserver port for the Registry and Repository server instance to which you want to connect.

From the Arguments tab:

• In the Program arguments box, enter the name of the sample application you want to run, for example, put EJB-SimpleDocument. This should be the last argument, any launchClient "-CC" arguments that you want to use must be listed first.
• In the Working directory section, uncheck the box labeled Use default working directory, click the Workspace button and select the WSRRSamplesEAR project for the new working directory.

From the Classpath tab:

• Highlight the User Entries section, and click the Add External JARs button.

  From the default list of JARs already present note the location of the j2ee.jar, navigate the Jar Selection dialog to the same location and add two additional jars from the same place: emf.jar and wsdl4j.jar.

• Highlight the Bootstrap Entries section and click the Add JARs button.

  On the JAR Selection dialog, expand the WSRRSamplesEAR project and add the sdo-int.jar to the bootstrap class path.

The run configuration should now be ready to invoke your selected Registry and Repository sample application. Click Run and view the console output to check if the sample runs successfully.

Important: If you are trying to connect to a secure Registry and Repository server, you should see a pop-up appear asking for your userid and password before the sample is able to complete.

Possible security errors

When running the samples using the Rational Software Development Platform to a secure Registry and Repository server, some people have reported getting security exceptions that include the following error message: "Reason: java.lang.SecurityException: The provider IBMJCE may not be signed by a trusted party". These messages appears to occur because the JVM environment established by Rational to run the application includes the IBMJCE provider jar on the JVM boot classpath, something that does not happen when a standard JVM is run from a command line.

If you see this error, you will need to modify the JRE used by Rational to run the application to remove this jar from the boot classpath. You can modify the JRE as follows:

1. Select Windows => Preferences, expand the Java section, and select Installed JREs.
2. Select the WebSphere V6 JRE and click Edit.
3. Uncheck the box labeled Use default system libraries.
4. Scroll down the list of libraries to find the ibmjceprovider.jar, select it, and click Remove.

Modifying the JRE removes the jar from the JRE boot classpath only. Modifying the JRE does not remove the jar from the system. The jar remains in the correct place and available for the JVM to use if and when it is needed.

If you test against a non-secure Registry and Repository server, or you do not see this specific security exception, you do not need to make these changes.

Understanding the sample applications included in the package

This table gives a summary of the sample applications included in the package. To run a sample, the Sample Name should be used as the last parameter for the launchClient command.

You should look at and understand the first two samples, the SimpleDocument and SplitDocument applications, first since most of the other samples reuse the code from one or other of these to create documents and objects in the registry on which further action can be taken.

Some of the sample applications need to use APIs and techniques that are explored in more detail in one or more of the other samples; where this is the case, the comments in the class prolog will indicate any other related samples that you might want to examine.

Conclusion

This article provided a brief introduction for various Registry and Repository APIs and demonstrated their use via a comprehensive set of sample applications built around the J2EE-based EJB APIs.

Back to top

Downloads

Information about download methods

Notes

1. Contains the ready to run WebSphere client application and associated resources.
2. Contains the full source code and project files for the Rational Software Development Platform.

Resources

• The IBM WebSphere Service Registry and Repository product information.
  
  
• The InfoCenter for the IBM WebSphere Service Registry and Repository.
  
  
• "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) life cycle.
  
  
• WebSphere business integration zone
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Working with the sample application
• Working with the sample source code
• Understanding the sample applications included in the package
• Conclusion
• Downloads
• Resources
• About the author
• 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

Discover knowledge paths

Skill-building guides for WebSphere, Linux, open source, cloud, Java, business analytics, and more.

Special offers