JBoss Seam, Stripes and Hibernate: An Irreverent Look at Java Software Frameworks & RoR
By Angsuman Chakraborty, Gaea News NetworkTuesday, October 25, 2005
What is it with all these frameworks? Why can’t JBoss Seam or even good ‘ol Hibernate give me a simple HelloWorld example anymore?
Also have you noticed how complex it is to setup the whole JBoss Seam in the first place?
I am a simple person and Stripes looks much simpler. They also have a HelloWorld or Calculator, an absolutely simple example which you can build upon and play with. Also note how the examples are built without database requirement to setup. It took me about 5 minutes to setup and run the first example. If I were to judge a software solely by its documentation, JBoss Seam fails.
I dabbled with Hibernate before. Now I need to wet my feet again and I remembered an old question. Why in the world did they have to develop a query language like SQL? Why not SQL?
The problem with Seam or Hibernate type documentation is that they are not organized with readers in mind, they don’t take the readers step by step into the labyrinth of the mess they have created wonderful software they have created.
Reading each paragraph convinces you that the author was in real hurry, like in the last throes of death, while he was writing these chapters. It makes such chapters almost humanly impossible to understand without feeling absolute disgust and revulsion about software development in general. They make development a chore, a never-ending horror story. Everything and their great-anchestors are crammed into these chapters.
The only purpose they serve is to convince the readers to cough up and buy their books.
Do you know why RoR flourish? Not because they have something great or convoluted. It is because one fine guy has taken the time to create a framework which makes it simpler to develop applications and not make it even more complex than the problem it solves.
Hibernate and Seams team should read RoR and Stripes documentation before they embark on a massive rewrite of their tomes.
Even PHP Manual is a tome but a very readable tome. Tomes don’t have to be PITA.
One drawback with Stripes documentation is that it is still minimal. Tag library javadoc doesn’t substitute for documentation.
All in all I highly recommend Stripes framework. It solves only half of the puzzle which RoR solves fully. However it does it very well, even better than RoR.
With the other half completed, RoR will finally stop roaring so much 
To All Framework Authors: Please for the love of whoever you love take the effort to make something simple and elegant. And please spend twice as much time writing documentation which are for human consumption. Please read K&R, PHP Manual etc. to get a hang on writing easy to understand and interesting documents.
BTW: Hibernate with Annotation has a nice thing going, if only they knew how to document clearly.
If there is one thing I really hate about today’s java software frameworks, it is their documentation. The bottomline is framework must make our life simpler.
To summarize the points that can be addressed while documenting frameworks are.
- Start with a simple example; very simple one
- Say a simple story and carry it through the spectrum of broad capabilities
- Now delve in the complex details and exceptions and overrides.
- Stop flaunting your expertise.
In times such as this I head over to bile blog. He knows the pain which most framework developers (with the exception of Stripes and RoR) don’t.
Update: An article without an example is bland. So let me illustrate with a simple example from Seam.
The heading of the chapter is: Chapter 2. Seam concepts
The two core concepts in Seam are the notion of a context and the notion of a component. Components are stateful objects, usually EJBs, and an instance of a component is associated with a context, and given a name in that context. Bijection provides a mechanism for aliasing internal component names (instance variables) to contextual names, allowing component trees to be dynamically assembled, and reassembled by Seam.
Read it once, twice and then tell me if you understand what they are talking about. To me it reads like incoherent rambling of technical jargon, not a documentation.
First “context” in this context is not defined despite being mentioned. Then they simply include it in a sentence.
“Components are stateful objects, usually EJBs, and an instance of a component is associated with a context, and given a name in that context.”
I don’t know where to begin. Is it too much to expect a proper and meaningful yet simple sentence?
“Bijection provides a mechanism for aliasing internal component names (instance variables) to contextual names, allowing component trees to be dynamically assembled, and reassembled by Seam.”
Why wasn’t “bijection” introduced earlier? What is the context?
This strange sentence probably makes sense only to a Seams developer.
Are they being penalized to write simple meaningful sentences? Have they read their own documentation ever? Or have their brain become soft working on frameworks so as not to be able to comprehend the problem?
This is merely the tip of iceberg. Such haphazard, poor quality documentation is all throughout.
|
July 26, 2009: 3:52 pm
I totally agree with you. These days I am working on some of the issues with seam development. I do not find a single lucid document. Thanks |
|
September 23, 2008: 6:23 pm
I think Stripes doesn’t do much better either in terms of looking out for users who are new to the framework or switching over from other languages. I, for one, have quite a bit of experience with ASP.Net and PHP, and I must say people consider me fairly proficient. But it sucks badly when you cannot run a simple Hello World app in a new framework that you are trying out, and that’s exactly what is happening to me for two days now. For you the documentation might appear streamlined but not for someone who is trying to wrap their heads around the whole java framework thingy. Granted, that Stripes would be much better than other java frameworks, but I fail to see the usefulness of it when the quickstart sample itself from the website refuses to run and needs heavy tinkering. I am not new to Java, only to web frameworks. For the record, I cannot get it to locate my ActionBean that is bound to the URL, and they are all there in the exact places where the compiler/handler should look for them. I hope people would understand that the only expertise deemed required from an audience should be a certain level of programming proficiency, a general idea of how projects work, and not having extensive expertise in annotations and actions and dispatcher servlets. |
 jaseem |
September 17, 2008: 11:53 pm
I am using JBoss Seam(JSF, EJB3.0). I have a table MapGroupObject with composite primarykey(groupId, objectId). groupId is the primary key of Groups table and objectId is the primary key of Objects table. Wt should I write in the bean class of MapGroupObject so that I can use select query for MapGroupObject table. |
 Mahesh Lavannis |
August 29, 2008: 2:05 pm
Trouble with documentation is the amount of time it takes to write good documentation. |
 sp |
December 4, 2006: 9:59 am
I agree with you on “The problem with Seam or Hibernate type documentation is that they are not organized with readers in mind, they don’t take the readers step by step into the labyrinth of the mess they have created wonderful software they have created.” |
 Kman |
November 2, 2006: 6:04 am
Nice article. the only thing that i can do is just agree with you. Just read the seam documentation for setting up a simple project. Or just test their examples and try to debug them if something goes wrong. Bad documentation is not better than no documentation. I believe the best way to document a framework is to provide really stupid samples and example projects. |
 Prasad |
June 29, 2006: 3:47 am
There are some bugs in the Stripes Framework. (i) I have given (ii) I am putting a object in memory using wizard forms. But it is retaining the values across the pages. Hope someone give some solution to these problems. |
|
February 19, 2006: 8:06 pm
Testimonials Introduction Since Stripes was released in September 2005 people have been saying a lot of nice things about it. This page pulls together some quotes from people who have found Stripes one way or another and, unsolicited,… |
|
October 26, 2005: 11:37 pm
@Tim I fully agree with you. This is also the reason why documentation shouldn’t be created by developers in the first place. Writing good documentation is art. Who are my readers? What are their use cases? How easy can I make it for them. As we write use cases for development, I think we should write use cases for documentation too. @Emmanuel Unless you are Mrs. Rowling or Vikram Seth |
|
October 26, 2005: 1:03 pm
Quality of documentation is something I’ve spend quite a bit of time thinking about over the years, and I think it boils down to something very simple. You have to write documentation that is structured in the manner your reader needs it. The easiest way to write documentation is to write it in a structure parallel to your software. That leads to more of a reference, which is only useful once you already know your way around. And you still have to piece lots of things together when you want to get something done. My approach these days is to think through the question “what are my users going to be trying to do” and then write documents about that. I’m glad you like the results -Tim Fennell |
|
October 25, 2005: 11:58 am
@Emmanuel It would be great if it is only me, but I seriously doubt it. The documentation may look great to you as you are possibly immersed in hibernate. But look at it, or ask someone to, from the perspective of an outsider wishing to learn this framework (possibly on a deadline). > So maybe that’s just you esp since you had to use more than 500 words to express this idea I used 500 words that to cover Hibernate (with/without) annotations, Stripes and Seams I do know Hibernate. It is Hibernate with Annotations which is new to me. > you should now that writing a book is a real PITA and don’t really feed you. So such evil plan just does not make sense. I am running out of ideas to explain such painfully hard-to-read docs. You can possibly help me to understand why it is so. The problem is not that they do not contain information. They do. However it is not clearly presented in a phased manner. They are just crammed haphazardly. Please consider revising the docs with some professional technical writers. I tried to summarize at the end how I think the docs can be improved. You can probably take a leaf out of Picocontainer’s idea of 1-minute introduction, 2-minute introduction and 5-minute tutorial etc. Look at it this way. You guys have spent lots of time in creating a good framework which have own critical acclaim. Would’t you like to make it easier for people to understand? |
 Emmanuel Bernard |
October 25, 2005: 10:47 am
Interesting, that’s the first time so far I read a global negative feedback on Hibernate Annotations documentation. This is usually the opposite, and the opposite on the Hibernate doc as a whole. So maybe that’s just you esp since you had to use more than 500 words to express this idea BTW, you should now that writing a book is a real PITA and don’t really feed you. So such evil plan just does not make sense. |
Sudhakar