RIFE with frustration

I’ve been working on a little pilot project using RIFE, spurred on by some of the glowing reports I’ve read of how productive it is, and I’m finding it a bit frustrating. Mostly it comes down to the documentation, or lack thereof.

What I want is fairly basic stuff: a web site where you can sign up as a member, and if you’re logged in, additional content appears on pages (e.g. a “log out” button) and you’re allowed to visit restricted-access pages.

I figured I’d start with the simple blog from the RIFE web site’s “theater” section. That went pretty smoothly and it all made sense; kudos to the RIFE guys on that. Then I started trying to extend it from there. I figured a good first step would be to add the notion of users.

The documentation describes how to set up authentication for a fixed, sysadmin-controlled list of users, “memory users” in RIFE lingo. That’s fine as a trivial example to demonstrate how to set up authentication elements and child triggers, so I’m not saying get rid of it… but I doubt there are very many site designrs who actually want that kind of authentication. As soon as I got the memory users working, the step I wanted to take next was to make RIFE read users from a database instead.

There is a section of the user’s guide that describes the element configuration to use database authentication, but that’s all it describes. Put that configuration in place, and then what? You have no users! What table does the authentication system use for user data, and what are its columns? How does one add or remove a user? Does the table have to be managed by the authentication classes, or can they use a user-supplied table that has other data about users than just their login names and passwords? Is it possible to store session data somewhere other than a database, e.g. in a clustered cache?

I downloaded the Elephant source, since I know it has a user database. (Elephant is a multiuser blog application written using RIFE.) Dug through its config files and found that its database authentication element is a little four-line class that extends a class called PurgingDatabaseAuthenticated. Great, I thought, I’ll just read the Javadocs on that class. Nope. The Javadocs don’t contain so much as a one-line summary of what the class is for, let alone a description of how to use it. Neither do the Javadocs for its superclass, or its super-superclass, or any of its ancestors until you get all the way up to Element, which is too general to have any bearing on the question. What is the “entrance” method that the Elephant authentication class implements? What inputs does it take, and what does it have to do? It’s a mystery.

One thing I did manage to crib from the Elephant source, a completely undocumented feature as far as I can tell, is how to use global cookies instead of URL decoration to keep track of the fact that I’m logged in. This is another thing that, I suspect, 99% of people are going to want to do. It shouldn’t be so obscure. In fact, in my opinion it should be what’s described first in the documentation, with the URL decoration method given as an alternative later on. I’d go edit the Wiki docs myself, but to be honest I am not confident I really understand it even though I have it working.

Query building is another area that seems a bit mysterious. What exactly do all those methods on the Select class do? (Not one of them has a description in the Javadoc, and only a couple of them are used in the examples in the other documentation.) What order can you use them in if you’re building a query dynamically?

Am I just missing the big picture here? It feels like in order to know how to use RIFE, you have to have been following the mailing list for long enough to have read all the design discussions for all the major features. I have so far spent about an hour looking for nonexistent documentation or examples for every ten minutes I’ve spent writing new code; if there is a huge productivity boost to be had from RIFE, I’m sure not seeing it yet.

Maybe part of my frustration is that I’ve been using the Spring framework; its developers seem to regard documentation as an integral aspect of coding. I don’t think I’ve ever seen them put out even a prerelease version of something that wasn’t pretty well-documented, though I’m sure others can point out counterexamples. But the point is, Spring feels like something its developers expect and intend other people to use. RIFE does not feel like that. It seems to view documentation (or, in other words, enabling people other than the author to use its features) as an afterthought at best, which to me is a big, big problem if it aims to be more than a tiny niche product. That’s a pretty harsh thing to say, maybe, but after working my way through the woefully outdated user’s manual (just compare how it tells you to do database access with what the blog demo tells you) and reading page after Javadoc page without any method descriptions, it’s a hard conclusion to escape.

As a new user I don’t mind learning what I need to learn, but I need there to be some way to learn what I need to learn, and I’m not really sure that’s the case with RIFE right now. The learning curve is far steeper than the framework’s complexity warrants. Which is a pity because I really do like some things about it, enough that I’ve been willing to keep plugging away when good sense tells me I’ve already wasted more time than it would have taken to do what I’m trying to do in some other environment.

One Response to “RIFE with frustration”

  1. Geert Bevin Says:

    For those that stumble into this blog post, we are actually discussion all of this on the mailinglist:

    This is an excerpt of my initial reaction:
    “Hi Steven,

    I’m sorry that you’re bumping into this block.

    I agree that documentation is lacking in some areas, mostly for code
    that was initiated earlier than three years ago. We’ve tried to fill
    in the Javadocs holes and I think that in the areas that we did
    cover, we’re doing an excellent job at this. In contrast to what
    you’re saying, there have been many compliments about the quality of
    the current documentation (even though there are lacunas). Also,
    since three years, no public APIs get committed anymore without
    Javadocs. Additionally, as you probably saw, each release contains
    extremely detailed release notes with examples that are afterwards
    aggregated in the wiki’s cookbook. I think that there is no open-
    source project out there that does this as extensively. Stating that
    documentation is an afterthought thus feels really very harsh to me.
    A project with the momentum of Spring, with their amount of
    contributors and commercial companies behind it, is of course able to
    provide a lot more in terms of books and user guides. There’s only so
    much that a small team of motivated developers can do for free in
    their spare time. However, if you do feel that some areas need to be
    improved quicker, you’re always welcome to contribute to the effort
    and document your findings either in articles or Javadoc additions
    that you can send to me as patches.

    … more …”

Leave a Reply