Business Queries

One the easiest and most intuitive ways to explore the registry is through business queries. To use Business Queries make sure you select the Business Query radio button near the top of the Search Parameters Panel.

Business Queries allow you to search for objects using any combination of the following selection criteria:

• Type of object
• Name of object
• Description of object
• Classification
• Identifiers associated with object via ExternalIdentifiers
• URLs association with object via ExternalLinks

Object Type

The Object Type combo box allows you to specify the type of objects you are looking for. The choices are defined by the ObjectType Classification Scheme as shown in the Classification Schemes Dialog. There are several pre-defined ObjectTypes to choose from. In addition a registered user may also define additional custom ObjectTypes within the ClassificationSchemes dialog after logging on.

The ObjectTypes are organized hierarchically. This means that you can narrow or broaden your search by choosing an Object type lower (more specific) or higher (more general) in the hierarchy.

You can configure which ObjectType should be selected by default by configuring the index (from 0 to N) in the following property within the (User.Home)/jaxr-ebxml.properties file:

jaxr-ebxml.registryBrowser.objectTypeCombo.initialSelectionIndex

Name

The Name text field allows you to narrow your search by specifying a name pattern for the objects you are looking for. You can either type the exact name but more typically you may type a name pattern using '%' as a wild card character to match any number of characters.

Example: The following entries in the name dialog box will find the entry ebxml

1. ebxml
2. %xml%
3. %eb%

Description

The Description text field allows you to narrow your search by specifying a description pattern for the objects you are looking for. You can either type the exact description but more typically you may type a description pattern using '%' as a wild card character to match any number of characters.

Case Sensitive Searches

Name and description based searched are case-insensitive by default. Check the Case Sensitive CheckBox above Name filed if you wish to make your search match name and description in a case sensitive manner.

Classifications

The most powerful way to discover objects of interest is to search by Classifications. Objects in the registry are often classified using one or more Classifications based upon values defined as Concepts within a ClassificationScheme.

To enter one or more Classifications in the Classifications List box do the following:

1. Right-click inside your chosen field and select insert to display a Classification Panel dialog.
2. Define a Classification by specifying a Concept within a Classification Scheme. Click OK when you have selected an object or cancel if you do not want to choose one.
3. Your selection will be entered inside the classifications List box in the Search Parameters Panel. Right-click the entry to edit or remove it.
   
   Note: You can repeat the insert/edit/remove process to further modify your Classifications for the search and you can clear all search parameters and results by selecting Clear button at the top of the Search Parameters Panel.

ExternalIdentifiers

A less commonly used Search criteria is to search for registry objects by ExternalIdentifiers associated with the objects. An ExternalIdentifier is similar to a Classification. The main difference is that instead of specifying a Concept within a Classification Scheme you specify a ClassificationScheme and a textual value within that ClassificationScheme. For example the ClassificationScheme may be "US Social Security #" while the value may be the actual US Social Security Number for an individual.

Entering an ExternalIdentifier is done in a similar manner as described for entering Classifications.

ExternalLinks

A less commonly used Search criteria is to search for registry objects by ExternalLinks associated with the registry objects. An ExternalLink is essentially a glorified HTTP address (URL). So ExternalLInk based searches allow you to search for any object that has certain URL patterns associated with it. For example you can find all objects with the URL pattern of '%ebxml%'.

Entering an ExternalLinkr is done in a similar manner as described for entering Classifications.

Performing the Search

When you have specified one or more Search Parameters for the Business Query, select Search button to search for objects matching all the specified Search Parameters.

Adhoc Queries

Adhoc queries allow you to use powerful SQL queries to specify exactly what objects you are interested in. Unlike Business Queries that have fixed semantics where all specified criteria must match, ad-hoc queries allow you to specify arbitrary predicate conjugation using the rich expressive syntax of the SQL 92 query syntax.

To use Ad-hoc Queries make sure you select the Ad-Hoc Query radio button near the top of the Search Parameters Panel. See Figure 3.3 for a picture of the Ad-hoc Query Search Parameters Panel.

Form Based Parameterized Query Interface

While SQL queries are very powerful, they are also not very user friendly and can be intimidating to most users. The Registry Browser Java UI's ad-hoc query capability provides you with the best of both worlds by hiding the complexity of ad-hoc queries behind parameterized forms.

Any number of ad-hoc queries may be configured for the Registry Browser Java UI. Each ad-hoc query may have any number of parameters defined. A user selects a pre-configured query and simple enters the parameters for that query and performs the search. From a user's perspective ad-hoc queries are even simpler than Business Queries to use. The next sections describe how to use ad-hoc queries.

Select Query

The first thing you must do is to select a previously configured ad-hoc query using the Select Query combo box. All queries in this combo are user configurable and extensible as defined later.

The following queries have been pre-configured in the standard distribution:

• Find All My Objects: Finds all objects owned by the user. Requires user to logon.
• Find All Objects Owned By Organizations: Finds all objects that are owned by a specified Organization.
• Arbitrary Query: This allows you to type in an arbitrary SQL query conforming to the ebXML Registry relational schema. This is useful only to experts.

Ad-hoc Query Parameters

When you select a query the Ad-hoc Query Parameters form below the Select Query combo changes to display the form appropriate for the configured query. The fields in the form are chosen according to the data type of the field. Enter parameters in the fields.

Performing the Search

When you have specified the Search Parameters for the Ad-hoc Query, select Search button to search for objects matching the specified Search Parameters.

Configuring A New Ad-Hoc Query

While use of Ad-hoc queries is simple, their configuration is the harder task and requires knowledge of SQL-92 as well as the relational schema defined in file <ebxmlrr>/conf/database.sql .

1. Check if you have a file named <user.home>/jaxr/ebxml/registry-browser-config.xml . If not then copy the file <jaxr>/src/com/sun/xml/registry/client/browser/conf/config.xml to <user.home>/jaxr/ebxml/registry-browser-config.xml .
2. Edit the <user.home>/jaxr/ebxml/registry-browser-config.xml i n a text editor or an XML Editor.
3. For each new query add a <Query> element (both open and close tags). The Query element has the following sub-elements:
• Name : This is the name used to identify the query in the Select Query Combo in the Ad-hoc Query Parameters Panel. Don't make it too long.
• Description : This is a more detailed description of the query. It is shown in the Description text box in the Ad-hoc Query Parameters Panel.
• Parameter : One or more Parameter elements may be added for each parameter in the parameterized Query. Each Parameter has Name and Description sub-elements. Most importantly it has an attribute named datatype (usually string) which determines how to display the parameter field in the form.
  
  
• SQLQuery : One SQLQuery element defines the actual SQL query. For each positional parameter use $1, $2 etc.
  
  
4. Validate you newly modified <user.home>/jaxr/ebxml/registry-browser-config.xml file with a schema-aware XML validator. This will prevent downstream grief.
5. Now re-start your Registry Browser Java UI and navigate to Ad-hoc Query Parameters Panel. You will now be able to test your query. It is likely to not work the first time. In which case iterate and try again. Note that it is a good idea to test your query with parameters filled in using the pre-defined Arbitrary Query ad-hoc query.
   
   

Search Results Panel

When the user performs a Search, the objects matching the search are displayed in the Search Results table. Each row in the table represents an object that was matched. Each column represents an attribute of the object being displayed in that row. The columns of the table vary depending upon the type of type of objects being displayed and is completely configurable by the user. In case the search matches multiple types of objects, the browser will use the configuration matching the most specific (lower in hierarchy) ObjectType that is a common base type for all the objects.

Sorting of Search Results

The Search Results table may be sorted by the values in any column. Simply click on the column header and the entire table will re-sort according to the values in that column. To sort in reverse order simply hold down the SHIFT key when clicking on the column header.

Web Browser Integration (Hyper Link Support)

The Search Results Table cells display HTTP URLs using a blue hyper link visual style. Clicking on a hyper link will launch a Web Browser displaying that web page. If this does not work for you you may need to configure the following property in your <user.home>/jaxr-ebxml.properties file:

In this property you specify the actual URL using the variable '$url'. Below is a sample configuration that works with Mozilla and Netscape browser family:

Search Results Table Configuration

The Search Results Table is configured within the <user.home>/jaxr/ebxml/registry-browser-config.xml file

This element defines configuration for handling a specific type of object within the Registry Browser Java UI. In particular it configures the Search Results table columns in the browser. The details of ObjectTypeConfig, its attributes and sub-elements are describes as annotations within the XML Schema file:

For some example of use see:

What Can Be Configured

• Configure which object attributes to show as columns
• Column header to display for each column
  
  
• Width of each column as a percentage of Scroll Panel containing the table (visible portion of table)
  
  
• Data type for each column