RIFE logo
This page last changed on Nov 25, 2005 by pazu.

Adding configuration to the friends application

Some explanation on RIFE participants

This chapter explains how to add configurability to the friends application. As an example we will make the title of the display page configurable. This can be useful if there are several different people that use the same application, and they want the title to be, for example, "Friends of Mikael" instead of "My friends".

Configuration is handled by a participant named ParticipantConfig. We have already seen ParticipantSite but only talked very briefly about participants, so we'll take the opportunity to explain a bit more about what participants are and how they work.

Various types of participants

A participant is a part of an application that handles a certain task. Simple applications might not use any other participants than ParticipantSite, but as the complexity grows, participants might be needed. Sometimes it might even be necessary to develop custom participants, in addition to the ones available within RIFE.

There are several built-in participants in RIFE for handling various tasks, and in this chapter we are going to take a closer look at the one for handling configuration. In the next chapter we will use the datasources participant, but for a complete list of built-in participants in RIFE, please look at the API documentation for the package com.uwyn.rife.rep.participants.

Execution of participants

The participants are started in the order they are listed in the repository definition file. Each participant is launched in its own thread and they will therefore all execute simultaneously. In case this behavior isn't desired, it can be changed by adding the attribute blocking="true" to the participant tag. For example, if we want to be sure that the config participant has started before trying to start the site we would change the above ParticipantConfig definition to:

<participant param="rep/config.xml" blocking="true">ParticipantConfig</participant>

RIFE participants also have built-in dependencies. This means that if a certain participant depends on information that is provided by another participant, RIFE will block the thread of the dependent participant until the required participant is fully initialized. For most cases you thus don't have to handle the execution order manually.

Configuration in the friends application

Now that you know a bit more about participants you should feel comfortable about adding the configuration participant to the repository. We begin by editing the participants file.

Participant file for Friends database
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rep SYSTEM "/dtd/rep.dtd">

<rep>
  <participant param="rep/config.xml">ParticipantConfig</participant>
  <participant param="sites/friends.xml">ParticipantSite</participant>
</rep>

The configuration participant takes a parameter specifying which file contains the configuration data, in this case rep/config.xml. The configuration file we are going to use looks like:

A configuration file
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "/dtd/config.dtd">

<config>
  <param name="DISPLAY_TITLE">Friends of Mikael</param>
</config>

The configuration parameter "DISPLAY_TITLE" will now be available from the element implementation. Now we just need to modify our template display.html by adding a value tag for the title. This tag can be used to set the title from our implementation.

Display template modified to use configuration data for title
<html>
  <head><title><!--V 'title'-->My Friends<!--/V--></title></head>
  <body>
    <h3><!--V 'CONFIG:DISPLAY_TITLE'-->My Friends<!--/V--></h3>

    <!-- Rest of the template -->

  </body>
</html>

In the templates chapter we mentioned that the string between the opening tag and the closing tag, here "My Friends", is the default value that will be used if we don't provide a value. This template shows two different ways of setting the title. The first way is to access the configuration value directly with a template value tag:

<!--V 'CONFIG:DISPLAY_TITLE'-->

The other way is to access it from the Java implementation and use setValue to set it in the template.

Config config = Config.getRepInstance();
if (config.hasParameter("DISPLAY_TITLE"))
{
  template.setValue("title", config.getString("DISPLAY_TITLE"));
}

If the value is set in the configuration file it's used as title, otherwise the default string "My Friends" will be used.

More on configuration

While we're at it, we might as well show some more features of the configuration system in RIFE.

Accessing parameters from within the configuration file

In our Friends example we might want to have custom titles for all of our pages (Display, Add, Remove, ...). The Add page, for example, could be "Add a Friend of Mikael". In case there are many pages where the title should include the user's name, it will soon get very tedious to change them all when the name of the user changes. RIFE has a solution for this: it is possible to access parameters from the configuration file itself.

Using the values from within the configuration file
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "/dtd/config.dtd">

<config>
  <param name="USERNAME">Mikael</param>
  <param name="DISPLAY_TITLE">Friends of <value name="USERNAME"/></param>
  <param name="ADD_TITLE">Add a Friend of <value name="USERNAME"/></param>
</config>

The parameter "USERNAME" is used to construct the title for both the Display page and the Add page. If someone else wants to change the name, they just have to do it in one place.

Configuration selectors

When developing an application, it is often necessary to have a different set of configuration options than when the application is deployed. It is also useful during the development process, since there may be several developers, all testing the software on different computers with different setups.

The configuration system in RIFE has a solution for this as well. The Config participant is able to choose from a set of different configuration files depending on the host name, operating system or user name.

<participant param="XmlSelectorHostname">ParticipantConfig</participant>

Here the configuration participant is going to look for the file config-{host}.xml. In other situations it might be different configure settings depending on operating system, where the selector name would be XmlSelectorOs. If configure settings depend on the username the selector XmlSelectorUser is used.

When using a configuration selector, the different configuration files must be named according to a certain pattern:

Filename convention when using selectors
Host name:        rep/config-{host}.xml
Operation system: rep/config-{OS}.xml
User name:        rep/config-{user}.xml

The host, OS, and user strings are normalized to use all lower case letters and with any dots and spaces ('.' and ' ') replaced with underscore ('_') characters.

Configuration file inclusion

When using configuration selectors, not all parameters are necessarily different between different setups. In those cases it's often preferred to keep those common settings in a separate file that is shared by the different configuration files. RIFE supports inclusion of files in configuration files. This makes it possible for all the selector specific files to include the same common configuration file.

<include file="rep/config-common.xml"/>

Now only one file has to be edited to change the common options instead of each of the selector specific files.

OK, now we have looked at displaying the friends, and visited a little side-track to explain participants and configuration in RIFE a bit more in detail. Let's move on to adding the actual data layer.

Document generated by Confluence on Oct 19, 2010 14:56