New integrated Content Management Framework (CMF)

RIFE now provides a Content Management Framework that is geared towards the process of storing, loading, validating, formatting, transforming, versioning, retrieving and streaming of various content types. Currently the emphasis has been placed on providing features that are needed when putting content data into a back-end repository and getting the data back out. The actual management of the content once it is stored has not yet been implemented in an elaborate manner, but this well be done in a future version (plus the integration and implementation of JSR-170 JCRQL to search for particular content).

These notes will only briefly cover the main features of the CMF, which is quite comprehensive.

Overview

The impatient reader may choose to skip down to the example. There you'll find the logic that is needed to store news items. Each news item has validated XHTML content and an optional image that is automatically scaled into two formats during storage and afterwards streamed directly to the browser. You'll see that very little code is needed to provide these functionalities.

All CMF content is stored in repositories that must have unique names. The installation of a content manager creates an initial default repository. If others are needed, they must be created explicitly.

repository:path

If the repository: prefix is omitted, the content will be stored in the 'default' repository. The path should start with a slash, which makes it 'absolute'; this is completely analogous to unix file system paths.

Content is stored through an instance of ContentManager and RIFE includes implementations for the storage in PostgreSQL, MySQL, Oracle, McKoiSQL, HypersonicSQL, Cloudscape and Firebird databases. Below are a few terms and their definitions in the context of the CMF:

Workflow

The database implementations have the following workflow:

Store content

1. Select a suitable content store based on the content's mime type
2. Look up the content repository
3. Store the content info (metadata) for the specified location (i.e. path)
4. Store the content attributes
5. Store the content data into the content store:
   1. Obtain a formatter for the content data
   2. Use the formatter to format the data:
      1. Load the raw content data into a newly-created Java object of an appropriate type (such as java.lang.String for text data and java.awt.Image for image data)
      2. Report any loading errors
      3. Format the content according to any attributes provided
      4. Transform the formatted content if a transformer has been provided
      5. Obtain the properties of the final content
      6. Convert the Java object back to raw content data
   3. Store the formatted content data into the content store
6. Store the formatted content data's properties

Use content data

1. Retrieve the content info for the specified location (i.e. path)
2. Select a suitable content store based on the mime type that is provided by the content info
3. Make the content data available via from content store:
   1. Look up the content data
   2. Call a ContentDataUser instance with the raw content data that was retrieved, and make it available to the caller

ContentQueryManager

To simplify working with content, a new query manager has been developed, called ContentQueryManager, which extends GenericQueryManager. This query manager class works hand-in-hand with CMF-specific constraints that are provided via the classes CmfValidation and CmfProperty. The additional constraints allow you to provide CMF-related metadata for bean properties while still having access to all regular constraints.

The most important additional constraint is 'mimeType'. Setting this constraint directs RIFE to delegate the handling of that property's data to the CMF instead of storing it as a regular column in a database table. The property content location (i.e. its full path) is generated automatically based on the bean class name, the instance's identifier value (i.e. the primary key used by GenericQueryManager), and the property name. So for example, if you have an instance of the NewsItem class whose identifier is 23, then the full path that is generated for a property named text is '/newsitem/23/text'. Note that this always specifies the most recent version of the property, but that older versions are also available from the content store.

To make it easy to handle file uploads (which are quite common when uploading content), the ConstrainedProperty class now has an additional file() constraint that will automatically create a file parameter for a submission bean and populate the property with the uploaded data after a submission.

Before being able to use the CMF and a ContentQueryManager, you must install both of them, as in this example:

Datasource ds = Datasources.getRepInstance().getDatasource("datasource");
DatabaseContentFactory.getInstance(ds).install();
new ContentQueryManager(ds, NewsItem.class).install();

Example: News Item

Here is a short example that demonstrates how to integrate a user-defined compound document called a "news item" with the CMF. A single image associated with the news item will be defined to have two sizes for delivery, "small" and "medium". When it is stored to the CMF, the image is rescaled in accordance with these size constraints, and it can also be automatically converted from other formats (such as PNG). These variants can also be streamed directly to a browser, based on which access path (small or medium) is used.

package com.mypackage.dao;

public class NewsItem extends CmfValidation
{
    private int       mId = -1;
    private String    mTitle = null;
    private String    mText = null;
    private byte[]    mNewsImage = null;
    
    public NewsItem() { }
    
    protected void activateValidation()
    {
        addConstraint(new CmfProperty("title")
                            .notNull(true)
                            .maxLength(90));
        // specify a type for automatic validation 
        addConstraint(new CmfProperty("text")
                            .mimeType(MimeType.APPLICATION_XHTML)
                            .autoRetrieved(true)
                            .fragment(true)
                            .notNull(true)
                            .notEmpty(true));
        addConstraint(new CmfProperty("newsImage")
                            .persistent(false)
                            .file(true));
        // specify types for content delivery and sizes for automatic rescaling
        addConstraint(new CmfProperty("imageSmall")
                            .mimeType(MimeType.IMAGE_JPEG)
                            .contentAttribute("width", 70)
                            .editable(false));
        addConstraint(new CmfProperty("imageMedium")
                            .mimeType(MimeType.IMAGE_JPEG)
                            .contentAttribute("width", 120)
                            .editable(false));
        addConstraint(new CmfProperty("id")
                            .editable(false)
                            .saved(false));
    }
    
    public void   setId(int id)                      { mId = id; }
    public int    getId()                            { return mId; }
    public void   setTitle(String title)             { mTitle = title; }
    public String getTitle()                         { return mTitle; }
    public void   setText(String text)               { mText = text; }
    public String getText()                          { return mText; }

    // As always in RIFE, a setter/getter pair defines a property.
    // In this case, imageSmall and imageMedium are both "virtual"
    // properties, which reference the mNewsImage property, but 
    // are delivered after transformations, i.e. they are resized 
    // to the dimensions specified in the above Constraints. 
    public void   setNewsImage(byte[] newsImage)     { mNewsImage = newsImage; }
    public byte[] getNewsImage()                     { return mNewsImage; }
    public void   setImageSmall(byte[] imageSmall)   { }  // dummy setter 
    public byte[] getImageSmall()                    { return mNewsImage; }
    public void   setImageMedium(byte[] imageMedium) { }  // dummy setter 
    public byte[] getImageMedium()                   { return mNewsImage; }
}

<element implementation="com.mypackage.elements.AddNews"
    <submission name="add">
        <bean classname="com.mypackage.dao.NewsItem"/>
    </submission>
</element>

package com.mypackage.elements;

public class AddNews extends Element
{
    private Template mTemplate;
    
    public void initialize()
    {
        mTemplate = getHtmlTemplate("add_news");
    }
    
    public void processElement()
    {
        print(mTemplate);
    }
    
    public void doAdd()
    {
        NewsItem newsitem = (NewsItem)getSubmissionBean(NewsItem.class);
        
        if (!newsitem.validate())
        {
            generateForm(mTemplate, newsitem);
            print(mTemplate);
            return;
        }
        
        Datasource ds = Datasources.getRepInstance().getDatasource("datasource");
        ContentQueryManager manager = new ContentQueryManager(ds, NewsItem.class);
        manager.save(newsitem);
        
        mTemplate.setBlock("content", "content_success");
        print(mTemplate);
    }
}

This code takes care of all the logic to store a new news item with two variants of an optional image (small and medium) that are automatically scaled and stored as JPEGs in the CMF together with the article's text. The text will be validated and only valid XHTML Transitional 1.0 will be accepted. Depending upon which image handling libraries are available in the classpath of the application, the image when it is uploaded can be in one of many other formats which can be automatically converted to JPEG before storage into the CMF. Without any external libraries only the JDK standard types are supported: JPEG, GIF and PNG.

To display the news item in a browser, some of the work is done automatically for you for the text property since it has the autoRetrieved constraint. This will automatically fetch the content from the ContentStore and fill it into the bean as if it were stored in the actual news item table in a dedicated column. For images, you cannot use this since you have to generate some HTML code which fetches the images themselves from a dedicated URL (the src attribute of the image tag).

The CMF provides an element implementation that streams content data directly to a browser according to the path info that the element receives. This path info will be used as the content path when it is retrieved from the ContentManager. You can for example integrate this element in your site structure like this:

<element id="SERVE_CONTENT" file="rife/cmf/serve_content.xml" url="/content/*">
    <property name="datasource"><config param="datasource"/></property>
</element>

The 'datasource' property has to contain the name of the datasource to use, which in this case is fetched from the config.

Once this element is in place, you just need a template to display the news item, like this for example:

<div><!--V 'title'/--></div>
<div><!--V 'image'--><!--/V--></div>
<div><!--V 'content'/--></div>

The following element implementation will display the news item according the id that has to be provided as an input:

package com.mypackage.elements;

public class ViewNews extends NewsCommon
{
    public void processElement()
    {
        Template t = getHtmlTemplate("view_news");

        int id = getInputInt("id");

        Datasource ds = Datasources.getRepInstance().getDatasource("datasource");
        ContentQueryManager manager = new ContentQueryManager(ds, NewsItem.class);

        NewsItem newsitem = (NewsItem)mNewsItems.restore(id);
        if (null == newsitem)
        {
            return;
        }
        
        t.setBean(newsitem);
        if (mNewsItems.hasContent(newsitem, "imageMedium")
        {
            t.setValue("image", mNewsItems.getContentForHtml(newsitem, "imageMedium",
                                    getSite().resolveId(".SERVE_CONTENT")));
        }
    }
}

[ top ]

Support for McKoiSQL, HypersonicSQL, Cloudscape and Firebird databases

RIFE now fully supports McKoiSQL, HypersonicSQL, Cloudscape and Firebird in the database query builders and in every integrated framework:

• authentication,
• credentials,
• CMF,
• scheduler,
• resources,
• generic query manager.

[ top ]

Added support for Janino and Groovy for site declaration, element declaration and template tag filtering

It has previously been possible to use Janino and Groovy for element implementations. These scripting languages have now also been integrated into other scriptable aspects of RIFE.

Instead of using OGNL for template tag filtering, you can use Janino or Groovy simply by changing the language identifier and the tag name:

<!--V 'GROOVY:name'-->Evaluated to false<!--/V-->
<!--B 'GROOVY:name:[[ true ]]'-->
    Evaluated to true
<!--/B-->

<!--V 'JANINO:name'-->Evaluated to false<!--/V-->
<!--B 'JANINO:name:[[ true ]]'-->
    Evaluated to true
<!--/B-->

Elements can be declared in Groovy and Janino like this. Instead of referring to an XML file to integrate them in the site structure, just refer to the script file instead:

processor.element(implementation:"com.package.MyElement") {
    input(name:"input1")
    input(name:"input2")
    output(name:"output1")
    exit(name:"exit1")
    submission(name:"submission1") {
        param(name:"param1") {
            defaultvalue("default1")
            defaultvalue("default2")
        }
        param(name:"param2")
        param(regexp:"paramC(.*)")
        file(name:"file1")
    }
}

builder
    .setImplementation("com.uwyn.rife.engine.testelements.engine.Simple")
    .addInput("input1")
    .addInput("input2")
    .addOutput("output1")
    .addExit("exit1")
    .enterSubmission("submission1")
        .addParameter("param1", new String[] {"default1", "default2"})
        .addParameter("param2")
        .addParameterRegexp("paramC(.*)")
        .addFile("file1")
    .leaveSubmission();

Site structures can be declared in Groovy and Janino like this. Instead of referring to an XML file, just refer to the script file instead:

processor.site(fallbackid:"ELEMENT4") {
    globalexit(name:"globalexit1", destid:"ELEMENT6")
    globalvar(name:"globalvar1") {
        defaultvalue("default1")
    }
    globalvar(name:"globalvar2")

    element(id:"ELEMENT4", file:"element4.xml")
    element(id:"ELEMENT5", file:"element5.xml")

    subsite(id:"SUBSITE", file:"subsite.groovy", urlprefix:"/subsite", inherits:"ELEMENT4")

    group(inherits:"ELEMENT5") {
        globalvar(name:"globalvar4")

        element(id:"ELEMENT6", file:"element6.janino", url:"/test/element6", inherits:"ELEMENT4")
        element(file:"element7.groovy", url:"/test/element7")
    }
}

builder
    .setFallback("ELEMENT4")
    
    .addGlobalExit("globalexit1","ELEMENT6")

    .addGlobalVar("globalvar1", new String[] {"default1"})
    .addGlobalVar("globalvar2")
        
    .enterElement("element4.xml")
        .setId("ELEMENT4")
    .leaveElement()
        
    .enterElement("element5.xml")
        .setId("ELEMENT5")
    .leaveElement()

    .enterSubsite("subsite.groovy")
        .setId("SUBSITE")
        .setUrlPrefix("/subsite")
        .setInherits("ELEMENT4")
    .leaveSubsite()

    .enterGroup()
        .setInherits("ELEMENT5")
    
        .addGlobalVar("globalvar4")
    
        .enterElement("element6.janino")
            .setId("ELEMENT6")
            .setUrl("/test/element6")
            .setInherits("ELEMENT3")
        .leaveElement()
    
        .enterElement("element7.groovy")
            .setUrl("/test/element7")
        .leaveElement()
    .leaveGroup();

[ top ]

Full J2SE 5.0 support

All RIFE core features (including continuations) have been ported to J2SE 5.0 and fully tested.

Since RIFE has been using generic types since the beginning, the APIs are very strongly typed and offer many usability benefits when using them with a generics-capable compiler (such as J2SE 5.0 or Omnicore CodeGuide). In many places the APIs have been designed to take advantage of generics beyond the trivial generification that is offered by many IDEs. The javadocs also contain valuable information since the types of collection items and other class capabilities are displayed everywhere. Aside from the JDK itself, RIFE is probably the largest generics-aware Java project in existence.

[ top ]

Added support for deferment and forwarding to elements

The defer() and forward(String url) element methods permit better integration of RIFE applications with in-container and external web applications.

The defer() method will only work if RIFE is used as a servlet filter (which is its default mode of operation). It simply interrupts any RIFE processing immediately and makes the servlet engine continue the processing of the filter chain.

The forward(String url) method is like the standard servlet forward method, except that it goes much further. You can provide it with any URL, both local and remote. It will send a request to that URL and output its response through the response of the element that executed the forward.

[ top ]

Removed element init parameters and replaced them with properties

Conceptually speaking, init parameters were very close to element instance properties, and during the business logic of reusable elements, checks for the presence of both were often needed. Therefore, we have now replaced init parameters with static declaration properties that are overridden by element instance properties.

Most users can simply replace <initparam> ... </initparam> by <property> ... </property>, and everything should continue to function as before.

Concretely, if you declare an element like this:

<element implementation="com.package.MyElement">
    <property name="name">default</property>
</element>

The 'name' property of that element will contain the 'default' value if it is not overridden in the site structure.

Now if you define the element like this in the site structure:

<site>
    <element id="THEID" file="myelement.xml" url="/myelement">
        <property name="name">overridden</property>
    </element>
</site>

The 'name' property of that element instance will contain the 'overridden' value instead.

[ top ]

Ordinal manager

The OrdinalManager class makes it possible to easily manage an integer ordinal column that is typically used to determine the order of the rows in a specific table.

The basic version manages the ordinals for the entire table, but it is also possible to create an OrdinalManager that uses several independent ranges of ordinals according to a restricting integer column.

For example, consider the following 'article' table:

id          INT
categoryId  INT
ordinal     INT
name        VARCHAR(30)

with the following rows:

 id | categoryId | ordinal | name
----+------------+---------+-----------------------
  2 |          1 |       0 | some article
  0 |          1 |       1 | another one
  3 |          1 |       2 | boom boom 
  1 |          2 |       0 | this is yet an article
  5 |          2 |       1 | an article for you
  4 |          3 |       0 | our latest article
  6 |          3 |       1 | important one

You can clearly see three independent ordinal ranges according to the categoryId column.

The OrdinalManager allows you to easily change the order of the articles by moving them up and down. Additional methods are also available to perform a number of low-level operations. Take a look at the javadocs for more information.

[ top ]

Paged navigation builder

The PagedNavigation class provides utility methods to generate navigation for paged lists.

The generation of the navigation depends on a collection of block and value IDs that should be defined in a template. Following is a table of all the IDs and their purpose:

In addition to these template conventions, you must also provide one exit and one output that will be used to create the links that will perform the actual paging behaviour of the navigation. By default, the change_offset exit and the offset output will be used. It is up to you to create the datalink and flowlink and to correctly handle the offset value when it changes.

A very basic paged navigation could for example be defined like this:

<!--B 'NAV:FIRSTRANGE'--><a href="[!V 'EXIT:QUERY:change_offset'/]">&lt;&lt;</a><!--/B-->
<!--B 'NAV:FIRSTRANGE:DISABLED'-->&lt;&lt;<!--/B-->
<!--B 'NAV:PREVIOUSRANGE'--><a href="[!V 'EXIT:QUERY:change_offset'/]">&lt;</a><!--/B-->
<!--B 'NAV:PREVIOUSRANGE:DISABLED'-->&lt;<!--/B-->
<!--B 'NAV:ABSOLUTERANGE'-->&nbsp;<a href="[!V 'EXIT:QUERY:change_offset'/]"><!--V 'ABSOLUTERANGE_TEXT'/--></a>&nbsp;<!--/B-->
<!--B 'NAV:ABSOLUTERANGE:DISABLED'-->&nbsp;<!--V 'ABSOLUTERANGE_TEXT'/-->&nbsp;<!--/B-->
<!--B 'NAV:NEXTRANGE'--><a href="[!V 'EXIT:QUERY:change_offset'/]">&gt;</a><!--/B-->
<!--B 'NAV:NEXTRANGE:DISABLED'-->&gt;<!--/B-->
<!--B 'NAV:LASTRANGE'--><a href="[!V 'EXIT:QUERY:change_offset'/]">&gt;&gt;</a><!--/B-->
<!--B 'NAV:LASTRANGE:DISABLED'-->&gt;&gt;<!--/B-->

Pages: <!--V 'NAV:RANGECOUNT'/--> ( <!--V 'NAV:FIRSTRANGE'/-->
       <!--V 'NAV:PREVIOUSRANGE'/--> <!--V 'NAV:NEXTRANGE'/-->
       <!--V 'NAV:LASTRANGE'/--> | <!--V 'NAV:ABSOLUTERANGES'/--> )

This templating could result in the following output, where all the underlined parts are clickable and will trigger the change_offset exit and provide a new corresponding value for the offset output:

Pages: 9 ( << < > >> | 1 2 3 4 5 6 7 8 9 )

The element that displays the list and calls the navigation generation method could for example be like this:

public class List extends Element
{
    public final static int LIMIT = 10;
    public final static int SPAN = 5;
    
    public void processElement()
    {
        Template t = getHtmlTemplate("article.list");
        DatabaseArticles manager = DatabaseArticlesFactory.getInstance();
        
        int count = manager.countArticles();
        if (0 == count) t.setBlock("content", "noarticles");
        else
        {
            int offset = getInputInt("offset", 0);
            
            PagedNavigation.generateNavigation(this, t, count, LIMIT, offset, SPAN);
            
            Collection<Article> articles = manager.listArticles(LIMIT, offset);
            for (Article article : articles)
            {
                t.setBean(article);
                t.appendBlock("articles", "article");
            }
        }
        
        print(t);
    }
}

Take a look at the javadocs for more information.

[ top ]

Reloading localization resource bundles

The standard JDK java.util.ResourceBundle class caches all bundles after their first load. While this is good for performance, it makes the development of localized web applications cumbersome since a developer has to restart the application after each change to a properties file. RIFE's com.uwyn.rife.tools.Localization class provides helper methods to easily obtain resource bundles and now also includes a ResourceBundle implementation that will automatically reload when the content changed. Each time a resource bundle is obtained, the modification time is checked and when it's newer than a previous version, it's loaded again. This ensures that all modifications are immediately reflected. Since all features that use resource bundles in RIFE depend on this class, this feature is now also active throughout the whole of the framework. You can set the L10N_RESOURCEBUNDLE_AUTO_RELOAD configuration parameter to turn the automatic reloading off, in that case the standard JDK class will be used. By default, reloading resource bundles will be used.

[ top ]