Sample code for Registry and Repository programming APIs
This content is part # of 3 in the series: Introducing IBM WebSphere Service Registry and Repository, Part 3
This content is part of the series:Introducing IBM WebSphere Service Registry and Repository, Part 3
Stay tuned for additional content in this series.
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.
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.
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:
- 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.
- 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.
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
- 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
- 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 V184.108.40.206 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:
This is a Java project containing the source code for the samples themselves.
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
EJBSample that provides an invocation framework
and some methods common to all the samples:
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
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:
- Select the Run => Run option from the menus.
- From the run-configuration dialog box, select (from the left-hand side) Application Server V6 Application Client configuration and click New.
- Give the new configuration a suitable name.
- 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:portwhere 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:
- Select Windows => Preferences, expand the Java section, and select Installed JREs.
- Select the WebSphere V6 JRE and click Edit.
- Uncheck the box labeled Use default system libraries.
- 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.
Table 1. The Sample Registry and Repository Applications
|Sample Name and Class||Overview|
|EJB-SimpleDocument||Very basic create, retrieve and delete of a simple registry document.|
|EJB-SplitDocument||Shows loading and processing a WSDL document that has been split into the standard three pieces and referenced and connected using "import" statements.|
|EJB-ObjectProperties||Shows how to view and manipulate the meta-data properties associated with objects in the registry. Both standard Registry and Repository modeled properties and additional user-defined properties are shown.|
|EJB-ObjectRelationships||Shows how to view and manipulate the meta-data relationships established between objects in the registry. Both standard Registry and Repository modeled relationships and additional user-defined relationships are shown.|
how classifications from an ontology system can be used to
classify and locate objects in the registry. |
Note: this application requires that the SampleFruit.owl is preloaded into the registry.
|EJB-PredefinedQueries||Shows how to run the the built-in predefined queries to locate registry content.|
|EJB-GraphQueries||Shows how to run the graph queries using XPATH search expressions to locate and return full objects and connected graphs of related objects from the registry.|
|EJB-PropertyQueries||Shows how to run the property queries using XPATH search expressions to return subsets of meta-data property information associated with objects in the registry. Property queries are typically faster and return less information than graph queries.|
|EJB-GenericObjects||Shows how the create, retrieve and delete generic objects that are used to represent arbitrary concepts stored within the registry.|
|EJB-DocumentVersioning||Shows how a generic object collection may be used to resolve versioning issues related to "import" statements when documents are stored in the registry.|
|EJB-LogicalObjects||Shows some examples of the logical model objects that are automatically derived from physical documents that get stored in the registry.|
how to browse and navigate the classification systems stored
in the registry. |
Note: this application requires that the SampleFruit.owl is preloaded into the registry.
|EJB-DocumentGovernance||Shows how to drive a simple governance life cycle for an object stored in the registry.|
|EJB-CollectionGovernance||Shows how a collection of objects may governed as a single entity and how to drive the governance life cycle for such a collection.|
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.
- WebSphere Service Registry and Repository product documentation in the IBM Knowledge Center
- SOA programming model for implementing Web services article series
- WebSphere Service Registry and Repository developer center