RIFE logo
This page last changed on Jan 17, 2007 by zachary.grafton@gmail.com.

Getting started

Installing RIFE

As mentioned, RIFE is built on the Java platform which means that you need to install a JDK to develop and run RIFE applications. Java can be downloaded from http://java.sun.com/ .

You also need a web server with servlet support and for this tutorial we have chosen Jetty, which is easy to setup and use. You can download it from the Jetty web page at http://jetty.mortbay.com/ .

RIFE itself can be downloaded from the RIFE site at http://rifers.org/downloads . There are a few different packages to choose from.

When setting up a new web application, the base package is a good starting point, since it contains the RIFE framework together with the necessary files for getting started with a web application. The directory structure in the zip file is only a recommendation, and you can change it to your liking. However, keeping the web.xml file in the recommended location makes it possible to package this directory as a war file easily and deploy it on any servlet engine. The jar file, on the other hand, contains just RIFE, which is convenient when upgrading RIFE in an existing application.

We'll set up a web application directory tree in our home directory, starting with Jetty.

mkdir ~/tutorial
cd ~/tutorial

jar xf {download directory}/jetty-{version}.zip

If you are using Debian 3.1 (Sarge) you can install Jetty using the following command. Jetty will be installed in the /usr/share/jetty directory. Use this directory where ever you see jetty-{version} in the rest of the document.

apt-get install jetty

After the Debian Jetty package is installed the service is automatically started. The ports used by Jetty are 8280 and 8079.

Now we need to setup our test application in the webapps subdirectory:

cd jetty-{version}
cd webapps

After that we unpack the RIFE distribution and set up the base directories for the web application:

jar xf {download directory}/rife-base-{version}.zip

mv rife-base-{version} my-application
cd my-application

cd WEB-INF

mkdir classes
cd classes

mkdir rep
mkdir sites
mkdir elements
mkdir templates

So far so good! It's probably a good idea to copy this whole directory hierarchy so that you can start over from a fresh setup after doing some experimenting, or just to have a boiler-plate application to start new projects from. For example:

cd ../../..
cp -r my-application ../../blueprint

Now we can start filling in the bits and pieces that are needed to create a very simple RIFE application. But first, we'd like to take the opportunity to explain a bit more about web applications and RIFE.

If you look at the contents of the RIFE zip file, you see that it contains the Java classes for RIFE along with a file called web.xml. Applications that are packaged this way can be used directly with any application server, by just dropping the file into the right directory.

The only thing missing from the zip file an actual implementation of a web application, which you'll soon be able to write yourself.

But first it's time to try out a finished RIFE application, and we'll use an example from the examples package that can be downloaded from the RIFE site . The package contains a number of examples that are ready to run and test. To try out the first example, a simple "Hello World" application, take the following steps:

First, go back into the webapps directory and unpack the examples there.

cd ~/tutorial

jar xf {download directory}/rife-examples-{version}.zip
cd rife-examples-{version}

Install RIFE into the web application's lib directory. We'll download the jar file from the RIFE site and put it in the right directory:

mkdir 01_helloworld/WEB-INF/lib
cp ROOT/WEB-INF/lib/rife-{version}.jar 01_helloworld/WEB-INF/lib/
mv 01_helloworld ../jetty-{version}/webapps/
Warning

Don't put this jar file in your servlet engine's lib, ext, or other engine-wide library location. Each web application needs to have its own private copy of the RIFE jar.

Now we can start the application and test it!

cd ~/tutorial/jetty-{version}

java -jar start.jar

If you installed the Debian Jetty package then you will not start Jetty as described above as it will cause a log4j error. To start Jetty in Debian do the following.

/etc/init.d/jetty start

You will see an exception when you start Jetty because the my-application web application is missing required files. We will add those later. The important part now is to look at the hello world example.

To try out the example, point your web browser to the location: http://localhost:8080/01_helloworld/home, which should show a "Hello world." message.

The following section will walk you through this example and explain the different parts.

A simple RIFE application

The center of every RIFE application is the repository. It keeps the different parts of the application together, such as configuration data, site users, data sources, etc. These parts are called participants.

The repository is available from anywhere in the application and offers a convenient way to initialize and access application-wide resources.

In the simple Hello World example, the repository file is located in ~/tutorial/jetty-{version}/webapps/01_helloworld/WEB-INF/classes/rep/participants.xml. From now on, we will skip the leading directories in the text, so, for example, this file will be referred to as rep/participants.xml.

The participants file for Hello World
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rep SYSTEM "/dtd/rep.dtd">

<rep>
  <participant param="sites/helloworld.xml">ParticipantSite</participant>
</rep>

Since this is a very simple example, we only have one participant, which is the site itself. As specified with the param attribute, the site file is found in sites/helloworld.xml. A real life application would most likely contain more participants.

A site is made up of elements, which are the smallest logical building blocks in the application. Elements are linked together to form a flow through the web site.

You can think of this as electronic components that need to be wired together before they become useful. An electronic component has no use by itself, but when it's combined with others, the most amazing products can be created.

It's also possible to use the same components but with different contact points wired together or in a different order. This will cause the functionality to dramatically change without the necessity to pull components apart or build new ones.

More even, when your product evolves you might need to include new components in between existing wires. It's not a big task to just remove the existing wire and put the new component in between. The rest of your product continues to function without you being bothered about it.

A RIFE element corresponds to the electronic component and the flow corresponds to the wiring. You can take any element from any application and just include it in the flow of another application (rewiring).

Each element can have input and output variables. These can be connected and data will be passed around when the links between them are followed.

If we take a look at the site structure defined in sites/helloworld.xml, we can see that it contains only one element called HELLOWORLD and that it's mapped to the URL /home.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE site SYSTEM "/dtd/site.dtd">

<site>
  <element id="HELLOWORLD" implementation="tutorial.helloworld.HelloWorld" url="home"/>
</site>

Since our first example only has one element, there are no inputs or outputs, and no links. Therefore, the entire element has been declared in-line. When you want to create reusable elements, you'll probably want to declare them in their own XML file. We'll talk about those features in more detail in the next example.

The important thing to notice here is the implementation attribute of the element tag. The implementation of the element can be either a Java class file or a Java source file, which is then compiled on the fly if needed, or a supported Java scripting language, like Groovy.

Our implementation of the element is a Java class that just outputs a greeting. It is implemented in HelloWorld.java

The Java element of Hello World
package tutorial.helloworld;

import com.uwyn.rife.engine.Element;
import com.uwyn.rife.template.Template;

public class HelloWorld extends Element
{
  public void processElement()
  {
    Template template = getHtmlTemplate("tutorial.helloworld");
    template.setValue("hello", "Hello world.");
    print(template);
  }
}

Element implementations must extend the com.uwyn.rife.engine.Element class and implement the processElement() method. As you can see, this element will use a template and output "Hello world." We will talk more about templates alter in the tutorial.

The previous Java code will use the template helloworld (an HTML file) defined at tutorial folder.

Let's see the template:

The HTML template of Hello World
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title><r:v name="hello"/></title>
</head>
    
<body>
    <r:v name="hello"/>
</body>
</html>

RIFE is responsible to wire the element definition to the Java code, then to the HTML template.

Now, let's take a look at a simple number guessing application.

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