Browser Configuration Guide - Table of Contents

The browser configuration guide explains how to configure or customize both the Registry Browser Java and Web UIs.

1. User Defined Queries

2. Configuring User Defined Query Panels

3. Setting Credentials For Anonymous Users

User Defined Queries

Introduction

The User Defined Queries feature allows users to deploy queries without writing code. To do this, complete the following steps:

1. Load the query into the database

2. Configure the query in the config.xml file.

Loading Queries into the Database

1. First, enter an AdhocQuery entry into the omar/misc/samples/SubmitObjectsRequest_AdhocQueries.xml file. Below is an example:

   <rim:AdhocQuery lid="urn:oasis:names:tc:ebxml-regrep:query:RegistryObjectVersionQuery"
         id="UUID of Query">
         <rim:Name>
             <rim:LocalizedString value="Name of Query"/>
         </rim:Name>
         <rim:Description>
             <rim:LocalizedString value="Description of Query"/>
         </rim:Description>
         <rim:QueryExpression queryLanguage="urn:uuid:c26215e8-7732-4c7f-8b04-bd8115c325e9">
             SELECT * FROM ExtrinsicObject WHERE lid LIKE '$lid' AND versionName LIKE '$versionName' AND
              contentVersionName LIKE '$contentVersionName' ORDER BY versionName, contentVersionName;
         </rim:QueryExpression>
     </rim:AdhocQuery>

   In the above example, the $lid, $versionName and $contentVersionName are all parameterized query placeholder values. The Registry Client will insert values for one, some or all of these into a query form. The Thin Client ensures that the query form's fields have a one to one mapping with a placeholder value. In this example, a query form may have three input fields, each one mapping to a placeholder value. When the Registry Client submits the query, each of the user's values are mapped to correct placeholder value. The Thin Client will then insert the values for each placeholder into the SQL string. If there is no value mapped to the placeholder, the predicate that contains that placeholder is pruned from the SQL query string. The Thin Client then submits the query to the JAXR Provider Package.

2. Run ant loadAdhocQuery to load the contents of the SubmitObjectsRequest_AdhocQueries.xml file into the database.

Configuring Queries in config.xml

1. Place an entry for your new query in the omar/src/java/org/freebxml/omar/client/ui/common/conf/config.xml file. For example:

   <Query>

   <AdhocQueryRef id="urn:uuid:d242d228-eba7-43e0-91ce-88aacbcc167c"/>
       <Parameter parameterName="$objectTypePath" datatype="taxonomyElement" defaultValue="RegistryObject">
         <rim:Name>
           <rim:LocalizedString value="Object Type"/>
         </rim:Name>
         <rim:Description>
           <rim:LocalizedString value="Type of Registry Object"/>
         </rim:Description>
         <rim:SlotList>
           <rim:Slot name="domain">
             <rim:ValueList>
               <rim:Value>urn:uuid:a7ec3db9-9342-4016-820c-cff66c0bb021</rim:Value>
             </rim:ValueList>
           </rim:Slot>
         </rim:SlotList>
       </Parameter>
       <Parameter parameterName="$name" datatype="string" defaultValue="%">
         <rim:Name>
           <rim:LocalizedString value="Name"/>
         </rim:Name>
         <rim:Description>
           <rim:LocalizedString value="Name of Registry Object"/>
         </rim:Description>
       </Parameter>
       <Parameter parameterName="$description" datatype="string" defaultValue="%">
         <rim:Name>
           <rim:LocalizedString value="Description"/>
         </rim:Name>
         <rim:Description>
           <rim:LocalizedString value="Description of Registry Object"/></rim:Description>
       </Parameter>
       <Parameter parameterName="$classificationPath" datatype="taxonomyElement">
         <rim:Name>
           <rim:LocalizedString value="Classification Schemes"/>
         </rim:Name>
         <rim:Description>
           <rim:LocalizedString value="All Classification Schemes in Registry"/>
         </rim:Description>
         <rim:SlotList>
           <rim:Slot name="domain">
             <rim:ValueList>
               <rim:Value>urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:ClassificationScheme</rim:Value>
             </rim:ValueList>
           </rim:Slot>
         </rim:SlotList>
       </Parameter> 

   </Query>

   The above example shows one <Query> entry. It has an <AdhocQueryRef> that points to the query stored in the database. There are four parameters, one for each of the parameterized query placeholders - $objectTypePath, $name, $description and $classificationPath. Two parameters have a data type of 'string', and two have a type of 'taxonomyElement'.

   The following datatypes are currently supported:

   Datatype	Default Component
   string	Text field
   taxonomyElement	Drop down list box - Single Classification Scheme or Concept Tree - All Classification Schemes
   boolean	Checkbox

   Table 1

   In the above example, the $objectTypePath taxonomyElement has a uuid that points to a single classification scheme. As such, it is displayed using a drop down list box. The $classificationPath taxonomyElement had a LID with the value urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:ClassificationScheme. Therefore, it points to all classification schemes, and according to Table 1, is displayed with a tree component.

   The first entry in the config.xml file is the first entry displayed in the drop down list box. You can change the order of the <Query> entries, to have a different query be the first displayed.

2. Remove your ~/omar/3.0-post-alpha2-dev/jaxr-ebxml/registry-browser-config.xml file. The new config.xml will be deployed in its place.

3. Run ant deploy.restart

4. Verify that you can see your new queries in the Thin Client's Discovery panel.

Troubleshooting

1. If you get the following exception in your browser or log file:

   exception 
   javax.servlet.ServletException: Error testing property 'textValue' in bean of type null
   javax.faces.webapp.FacesServlet.service(FacesServlet.java:209)

   root cause
   javax.faces.el.PropertyNotFoundException: Error testing property 'textValue' in bean of type null
   com.sun.faces.el.PropertyResolverImpl.getType(PropertyResolverImpl.java:342)
   com.sun.faces.el.impl.ArraySuffix.getType(ArraySuffix.java:240)

   This means that either:

   1. The value of a parameterName attribute of a <Parameter> element does not match any placeholders in the SQL string in the database. For example, using the ExtrinsicObject Version query above, a parameterName="$versionDescription? would cause this exception because 'versionDescription' is not a valid placeholder in the SQL string.

   2. The Thin Client was not able to parse the placeholder in the SQL string. It may be do to an invalid character in the SQL string.

Configuring User DefinedQuery Panels

The user defined query panels can be configured through the following properties:

Table 2

Setting Credentials For Anonymous Users

This feature involves configuring credentials for anonymous users. In other words, it is possible to load credentials for one user without requiring explicit authentication. This can be useful when doing prototyping or development, when the overhead of explicit authentication is not needed.

Please follow these steps:

1. Create a user and its credentials. If such a user does not already exist, do the following:

   1. Create the following properties in omar/build.properties:

      testUserAlias="testuser?
      
      
                      testUserPass="testuserpasswd?

   2. Run the 'ant createTestUser' target. This will create the Test User and load its credentials into the client keystore file. Default keystore file is ${user.home}/omar/<current build>/jaxr-ebxml/security/keystore.jks.

2. In the jaxr-ebxml.properties file, set the key password of the user. For example:

   jaxr-ebxml.security.keypass=testuserpasswd

3. In omar-common.properties, set the name of the anonymous user principal. For example:

   omar.security.anonymousUserPrincipalName=testuser

4. Run the 'ant deploy' target and bounce Tomcat.

When you access the Thin Client, it will use the omar.security.anonymousUserPrincipalName property to determine the user principal. It will then use the jaxr-ebxml.security.keypass property to load the user's credentials from the client keystore. These credentials are then set in the ConnectionImpl object for the duration of the user's session. The Thin Client will display the anonymous user's name in the banner. If anonymous user credentials are not set, the Thin Client will display 'Registry Guest'.