Web UI Registry Browser Client Configuration Guide

(Early Draft v0.1)

1. Introduction

This document describes how to configure or customize the Web UI Registry Browser Client Registry Browser.

The Web UI Registry Browser Client is based on Java Server Faces 1.0 and designed to work with standard web browsers such as Mozilla, Netscape and Internet Explorer. It requires that JavaScript be supported and enabled in the browser.

To install and setup up the Web UI Registry Browser Client, first read the User Guide.

2. Configuring the Overall Layout

Introduction

This section describes how to configure the overall layout of the thin client. By layout, we mean the size, location and number of panels. The next section describes the layout in more detail.

  1. Description of Layout

    The Web UI Registry Browser Client is organized as follows - it has one main panel that contains four additional panels:

  2. Banner panel - this is the top, horizontal panel with a logo, title and tool bar.

  3. Discovery panel - this is left side panel with links to Explore Registry and Search Registry. As the title suggests, this panel is used to discover what content is in the Registry and Repository. The content is made up of Registry Information Model (RIM) metadata objects.

  4. Search Results panel - this is the right upper panel that contains the results of a query or explore task. It contains a tabular display of RIM object search results. A subset of the RIM object's attributes is displayed as columns, and each result is displayed as rows. A drill-down can be done on each search result.

  5. Detail panel - this is the right lower panel that contains the results of the drill-down. The result contains all the RIM object's attributes and composed objects displayed in one file tab. Other RIM objects, related to the drill down object, are also displayed in separate, sequential file folders.

See the figure below for more information:



Figure 1 - Registry Browser Web UI - Page Layout

3. Configuring Individual Pages

Introduction

The Web UI Registry Browser Client's pages are written using Java Server Faces (JSF) 1.0. One can reconfigure the contents in the page by updating the JSF tags. Note: before making too many changes to the page files, it is recommended that you become familiar with JSF. Start by going through the Java Server Faces chapter of the JWSDP Tutorial.

Also, adding new components for the JSF pages, requires the development of new Java classes. See the section below for more details.

An Example

The Banner.jsp file contains the following JSF tags:

<f:view>

<h:panelGrid columns="2" width="100%">

<h:panelGrid columns="2">

<h:graphicImage url="images/freebxmlLogo.jpg" height="50" width="250"/>

<h:outputText value="#{bundle.applicationTitle}" styleClass="bannerPanel-applicationTitle"/>

</h:panelGrid>

<jsp:include page="ButtonPanel.jsp"/>

</h:panelGrid>

</f:view>

To change the logo that appears in the upper left corner, checkin a new image file to the omar/src/images/org/freebxml/omar/client/ui/thin directory. For example, myLogo.gif. Then, change the name of the image file in the Banner.jsp page:

<f:view>

<h:panelGrid columns="2" width="100%">

<h:panelGrid columns="2">

<h:graphicImage url="images/myLogo.jpg" height="50" width="250"/>

<h:outputText value="#{bundle.applicationTitle}" styleClass="bannerPanel-applicationTitle"/>

</h:panelGrid>

<jsp:include page="ButtonPanel.jsp"/>

</h:panelGrid>

</f:view>

Redeploy the new Banner.jsp page, and you should see your logo on the Web UI Registry Browser Client.

You may also make other stylistic changes to page including:

  • Change the number of columns in the <h:panelGrid> tag. This will change how the components are laid out in the page.
  • Change the text that is displayed in the <h:outputText> tag. This will involve adding a new entry to the omar/src/resources/org/freebxml/omar/client/ui/thin/bundles/LocalizedText.properties. See the localization section below for more details.
  • - You may make changes to the HTML in the page to change things such as the background page color.

4. Configuring Page Navigation

Introduction

Since the Web UI Registry Browser Client is based on JSF, it uses the JSF page navigation mechanism. Specifically, the page navigation rules are described in omar/conf/faces-config.xml.

Example

The following shows an example of how to change the page navigation.

<navigation-rule>

<description>

</description>

<from-view-id>/Details.jsp</from-view-id>

<navigation-case>

<description>

</description>

<from-outcome>showDetailsPage</from-outcome>

<to-view-id>/DetailsWrapper.jsp</to-view-id>

</navigation-case>

<navigation-case>

<description>

</description>

<from-outcome>showDetailsHelp</from-outcome>

<to-view-id>/UserGuide.html</to-view-id>

</navigation-case>

</navigation-rule>

This fragment from the omar/faces/faces-config.xml file, provides the navigation from the Details.jsp main page to the DetailsWrapper.jsp and UserGuide.html. If you wanted to map a different page to the showDetailsHelp outcome, you can change /UserGuide.html to /MyUserGuide.html. This would present your own user guide to your clients.

Note: the outcome text in this example is produced by the freebxml Java Bean classes. Changing the outcome text, and other changes, requires advanced understanding of the Web UI Registry Browser Client. Contact the ebxmlrr-team alias before making such changes.

4. Configuring Web UI Registry Browser Client Servlet

Introduction

The omar/conf/web.xml file is used to configure the Registry Browser Web UI Client servlet.

Example

<servlet-mapping>

<servlet-name>

ebxmlrr-thin-receiver-servlet

</servlet-name>

<url-pattern>

/registry/thin/*

</url-pattern>

</servlet-mapping>

You can change the Web UI Registry Browser Client URL pattern by changing /registry/thin to a different value.

6. Configuring Localization

Introduction

All Web UI Registry Browser Client labels and messages are stored in resource bundles as properties. This enables the Registry Browser Web UI Client to be localized. You can add additional resource bundles with properties for different locales.

Locale for the Web UI Registry Browser Client interface can be selected form the drop-down menu on the upper right corner of the page. When user starts a session Web UI Registry Browser Client will try to find a match between its supported Locales and user supported locales. If a match is not found, default is used.

Default Locale and list of available Locales are configurable through these properties in jaxr-ebxml.properties:

# List of locales for which thin client interface translations are available. Pipe -separated.

omar.client.thinbrowser.supportedlocales=en_US|fi|fr_CA|pt_BR



# Default locale to be shown whn thin client starts.

omar.client.thinbrowser.defaultlocale=en_US

Examples

To add additional properties to the default locale, place them in:

omar/src/resources/org/freebxml/omar/client/ui/thin/bundles/LocalizedText.properties

To add additional properties to the en_US locale, place them in:

omar/src/resources/org/freebxml/omar/client/ui/thin/bundles/LocalizedText_en_US.properties

Other properties files may also be added to the directory above.

To use a localized message property in a JSF page, do the following:

  1. Import the resource bundle into the JSF page. For example:

    <f:loadBundle basename="org.freebxml.omar.client.ui.thin.bundles.LocalizedText" var="bundle"/>
  2. Use a JSF tag to display the value of the property based upon the variable value in step 1. In this example, the variable has a value of bundle::

    <h:outputText value="#{bundle.applicationTitle}"/>

7. Configuring Security: Container Authentication

Introduction

The Web UI Registry Browser Client is deployed into a web container. The can be configured to protect the Web UI Registry Browser Client URL through an authentication scheme.

Example

In omar/build.properties set the following property:

deployWithSecurityConstraints=true

Set to true to include the <security-constraints> tag in the web.xml file. This will instruct the web container to require that users authenticate to access the ebxmlrr web client.

Then, run the build.sh deploy target. This will create a web.xml file with the following entries:

<security-constraint>

<web-resource-collection>

<web-resource-name>omar</web-resource-name>

<url-pattern>/registry/thin/*</url-pattern>

<url-pattern>/registry/http/*</url-pattern>

<http-method>GET</http-method>

<http-method>POST</http-method>

</web-resource-collection>

<auth-constraint>

<role-name>*</role-name>

</auth-constraint>

</security-constraint>

<login-config>

<auth-method>FORM</auth-method>

<realm-name>default</realm-name>

<form-login-config>

<form-login-page>/Login.jsp</form-login-page>

<form-error-page>/LoginError.jsp</form-error-page>

</form-login-config>

</login-config

This entry will protect the /registry/thin and/registry/http URIs by requiring users to authenticate before giving access to pages with this URI. If the user has not authenticated, the request is directed to Login.jsp.

The user fills out Login.jsp, and submits it to the web container. The container then authenticates the request using one of several schemes: ACL file, LDAP, etc.

Note: the web server must be configured properly to handle the authentication request. Consult your web server's documentation to do this.

8. Configuring Security: JAAS

Introduction

Both the Web UI Registry Browser and Thick clients using the Java Authentication and Authorization Service for pluggable authentication.

The Java Authentication and Authorization Service (JAAS) is a set of APIs that enable services to authenticate and enforce access controls upon users. It implements a Java technology version of the standard Pluggable Authentication Module (PAM) framework, and supports user-based authorization.

JAAS Configuration File

JAAS uses a configuration file to determine what pluggable authentication modules are required. The default configuration file is ${user.home}/.java.login.config and contains the following module:

jaxr-ebxml-provider-3.0-alpha2 {

com.sun.security.auth.module.KeyStoreLoginModule required

debug=true keyStoreURL="file:/home/user/omar/3.0-alpha2/jaxr-ebxml/security/keystore.jks";

};

This module instructions the JAAS framework to load the KeyStoreLoginModule.

See the JAAS Configuration Guide for more configuration options.

Deploying a Custom Configuration File

If you would like to deploy a custom JAAS configuration file, do the following:

  1. Copy of omar/conf/jaxr.java.login.config.sample to jaxr.java.login.config
  2. Insert your own values into jaxr.java.login.config. See the JAAS Configuration Guide for details.
  3. Deploy the jaxr.java.login.config file into the omar/build/lib/classes/org/freebxml/omar/client/xml/registry/util directory.
  4. 4. Jar up these files into jaxr-ebxml.jar

Note: at present, there is no build target that handle steps 3 above. An alternative, for now, is to unjar the jaxr-ebxml.jar file, place the jaxr.java.login.config file into the directory shown above, and rejar. You can create an Ant target like this:

<target name=?deploy.java.login.config?>

<unjar src="${build.jars}/jaxr-ebxml.jar" dest="${build.jars}/tmp"/>

<delete dir="${build.jars}/tmp/META-INF"/>

<delete file="${build.jars}/jaxr-ebxml.jar"/>

<copy file="config/jaxr.java.login.config"

tofile="${build.jars}/tmp/org/freebxml/omar/client/xml/registry/util/jaxr.java.login.config"

overwrite="true"/>

<jar jarfile="${build.jars}/jaxr-ebxml.jar" basedir="${build.jars}/tmp"/>

</target>

Setting the JAAS Callback Handler

The JAAS callback handler is a pluggable class that exposes an interface for the gathering of authentication credentials. It can display a GUI to user, read credentials from a keystore based on properties, or some other method.

The default Web UI Registry Browser Client callback handler is org.freebxml.omar.client.xml.registry.jaas.ThinClientCallbackHandler. This will read credentials from the keystore specified by the ${user.home}/.java.login.config file.

To reset the handler, set the following property in the jaxr-ebxml.properties file:

jaxr-ebxml.security.jaas.callbackHandlerClassName=

9. Configuring Web UI Client Certificate Authentication

In order to publish content and view restricted Registry data, a user must be authenticated. Web UI authentication is based on client certificates. Below are the steps needed to configure the Registry to support this type of authentication:

  1. Configure your web server to open a secure port (one that listens for https requests). The secure port enables your web server to obtain client certificates through the secure connection handshake. See the HTTPS Configuration Guide for details. This document will also explain how to configure your web server to use the Registry keystore as its trust store.
  2. In jaxr-ebxml.properties, set this property:

    org.freebxml.omar.client.xml.registry.localCall=true
  3. Run ant deploy, and restart your web server.

After this is done, the Web UI will automatically authenticate registered users using their client certificates. See the User Registration Guide for details on user registration and client certificates.

10. Configuring Hidden Classification Schemes

If you wish to hide some of the ClassificationSchemes so that they do not appear in the Basic Query's ClassificationScheme tree nor via the Explorer, set this property in the jaxr-ebxml.properties file:

jaxr-ebxml.registryBrowser.ConceptsTreeModel.hiddenSchemesList=
<class scheme id1>|<class scheme id2>| ...

For example:

jaxr-ebxml.registryBrowser.ConceptsTreeModel.hiddenSchemesList=
urn:oasis:names:tc:ebxml-regrep:classificationScheme:ObjectType

Above is an example that will cause the Web UI to not display the ObjectType Classification Scheme. Use the pipe '|' character as the delimiter for hiding multiple schemes.