Hi All,

I know this may be controversial, but I'd like to make a call for better documentation. Everytime I mention something like this everybody goes "their documention is excellent" and refuse to listen any further. Don't get me wrong - the documentation is good. I'd just like to know if it could be made better.

My problems are really to do with:
a) Good examples
b) Recommended approaches

Good examples

The documentation covers an awful lot, but leaves a few huge holes. As a result, I imagine thousands of users are scratching their heads, hundreds are leaving Hibernate after scratching, and thousands are scratching around other people's code. This is all a huge waste of time (yes I know, we all have important things to do).

What do I mean by good examples? Here are some:

Hibernate has one-to-one one-to-many many-to-many etc. and examples of these are given in terms of hibernate's configuration. All of these with bi-directionality and without. However, examples are not given in Java - leading to huge tracts of people making implementation mistakes (not updating both sides of a many-to-many etc.)
These are common, repeatable, things. Almost everybody who uses Hibernate needs to do these things. If there were clear examples that people could use, far fewer mistakes would be made, and the threshold required for uptake would be lowered. Most people use Hibernate with xdoclet - how about a list along these and these lines, but together with Java code and xdoclet annotated code for each combination (one-to-many, one-to-many-with-inverse, one-to-many-with-bidrection) etc.

Assuming all readers can piece together these kinds of things easily is a mistake. Assuming readers can find it in the sample applications you point to is a mistake. For example, I (and others) spent hours looking at freeroller's code (why? Because media-coverage is extensive that freeroller is a hibernate app), which seems to be a bird's nest of castor and hibernate. I spent hours looking at struts-resume, which is not at all definitive and whcih has things like classes representing the link table in a many-to-many.

Another example is things like the "inverse=true" option. What this means, I have no idea. The documentation defines it in terms of itself (mark this collection as the "inverse" end of a bidirectional association), and tells you where to use it in a few places. Fine, you dutifully use it in a few places. But that is not understanding, and again prone to error without good examples. Which side of a many-to-many bidirectional do I mark as inverse. An arbitrary side? What if there is no obvious parent-child? Why must I mark an arbitrary side as the inverse, why can't hibernate do it. What are the implications on the Java code that I have to write. What are the implications, if any, of doing it. etc.

Hibernate can do complex amazing cascading of assigned identifiers. No good examples are given of this (that I could find). It's an awesome feature, lost to the masses.

Again, hours of scratching scratching.

Recommended approaches

By recommended approaches I am talking about a step up, architecturally. For example, what is the recommended approach in a tiered-system for updating adding a link between two objects in a many-to-many relationship. Apparently one should find the one object, find the other, and the add to each side of the collection. This may sound obvious, but to people coming from an SQL background you keep thinking "but, isn't finding the objects expensive. In SQL I can do one simple UPDATE given the UID's, I don't need to locate both ends". But of course in an O/R setting you typically do.

People are writing web apps - a lot. I imagine this is one of Hibernate's big markets. But there is no recommended methodology.

And again, we have to all scratch around tons of (sometimes badly written) code trying to find "the approach".

I've got a headache, I'll stop now :)

Well done to all involved with Hibernate. Contrary to what you may think, I think it's awesome. I want it to be more accessible, that's all.
Jeff

OK, of course documentation can always be improved. However what we really need right now is the book, so we are concentrating upon that. All the kind of things you describe are covered in the book, but this will take us about 400 pages!

Yes documentation can always be improved. I would say that the book will fill in many of the gaps. It will also highlight any areas that require further clarification.

The things you are asking for are all complex and can not be dealt with in a short tutorial or a brief note somewhere. Our reference documentation is just that, a reference to look up mapping parameters or HQL operators.

Documenting application architecture and "best solutions" is not as easy as some people think: It takes not hours, but months of time.

I've been working on the book for many months now and it will answer all of those questions. In fact, I believe it is unique in this aspect: No other ORM documentation talks about application architecture and comes with a full example application. I promise it is not a "Hello World", but as close as possible to a real world scenario. The current chapter 3 on TSS should give you an overview, but expect some additions to the model in the subsequent chapters.

As Gavin said, we are concentrating on the book now, it is definitely the missing important piece of documentation for Hibernate and the only sensible way to deliver a full example app with (beginner and expert level) instructions.

Of course, this limits our time for other documentation at the moment. I'd appreciate any contribution to the "Hibernate Examples", which is on "official" set of tutorials, articles and workshops about Hibernate. We already have the "Quickstart" and our "Toolset" workshop. Juergen promised to write a "Hibernate & Spring" tutorial (hey juergen ;) and I hope others will contribute too. Just contact me for the details.

Thanks all - it seems these problems are recognised and are being worked on.

You have my money - when can I expect to be able to buy the book?

We are still in the process of writing the book, so it will take at least 2 (or even 4) months until its in print. We will publish a release data as soon as we know it :)

This may be sound inflamatory... not meant so. I think, as another guy noted, that some parts of Hibernate are really underdocumented. The team says the doc's are great, but I disagree. Parts of the doc are no good. Other parts are great.

Bad parts: Such as inverse=true|false which confuses the hell out of me (and others, it seems...) Also, not much about architecture.

Do you not document properly until the book to earn money?

If not, please documented this damn 'inverse' thing properly!

Thanks.

One thing that I can't help but wondering about the docs:

The "whole synthetic key being superior" thing.

I keep hearing about how it's better to use them, and I believe you guys, I've done it that way, however:

If there was an *example* of how this could (or even better -- WOULD) bite you, it wouldn't be such a tough sell to people who've never done it this way before.

As it is, in 4.1.5, you get told there is a better way in 6.4, with a link to it. You click on it, and immediately get told that the FK class must do this, that, and the other thing (which it would have to do anyway) and cannot use generators.

And, oh yeah, if the datbase is going to enforce that part of your composite key is a foreign key into another table, is this something you need to worry about?

I'm not saying the above answers aren't there; They just aren't immediately obvious, and the sales job pushing composite key classes isn't that great. As a result, this is what immediately occurs in the head of a newbie like me. It's probably also why newbies seem to always be asking about implementing many-to-one tags.

My .02 Euros.

Yeah. This is the first mention of 'inverse' in the reference doc:

"inverse (optional - defaults to false) mark this collection as the "inverse" end of a bidirectional association "

Oh? How interesting. But where was inverse explained again....

The next mention:

"Large Hibernate bags mapped with inverse="false" are inefficient and should be avoided, blah, blah, blah."

OK - but where was inverse explained again...

See this too: http://forum.hibernate.org/viewtopic.ph ... ht=inverse

Documentation critisism ends quietly again...

Read the well-known Scott Ambler paper. It is linked from our site.

Essentially this is a data modelling issue. Natural keys are actually inherently denormalized (the same business information is spread out over many tables) and are VERY difficult to adapt to changes in the business requirements.

Example 1:

What I thought was constant for a row turns out to now be updateable. But to update the PK requires updates to all foreign keys that refer to it. This ends up requiring that I refactor all tables with foreign keys.

Example 2:

What I thought was unique, turns out to not be unique. I'd better refactor all tables with foreign keys.

In addition, particularly in the case of composite keys, natural keys may be slower to index than synthetic keys (at least for very huge tables).

From the reference doc:

"Now that the Child entity is managing the state of the link, we tell the collection not to update the link. We use the inverse attribute.

<set name="children" inverse="true">
<key column="parent_id"/>
<one-to-many class="Child"/>
</set>"

Explain this! It says child is managing the state... yet it is the inverse which means NOT managed the state of link.

Is this an error?

It may be helpful to have the current version of the docs with inline comments, like php.net does with their docs. When I have to hack PHP, the comments are often more helpful than the docs themselves.

Overall, I'm very happy with the Hibernate docs, which makes it hard for me to write more articles about it. :)

hmm - that I actually think would be splendid idea.....

Christian - what do you think ? Is it doable, now we got the new wiki with comment possibility ?

That was the whole idea when we switche to the new wiki version in August. ;)

Actually, I just need some time to implement it, but it will not be a real problem. What is a real problem for me is the demand for better documentation, and people are right about this.

The problem is, that we can't offer detailed documentation for each and every part of "data structures", "application design" and "persistence". People expect us to explain stuff like that in much more detail, because it's all part of the "full" solution.

We are currently not able to provide this without a full example and more introductory material. Thats why we are writing the book, to have it in context and properly explained. Just in case some people wondered what we are doing all the time. :)

P.S. There are many ways to improve Hibernate and all of you can participate. Write an article for a Java magazine/website about Hibernate and some of the interesting things you did with it. Document a nice pattern you are using on our Wiki. Write down an overview of your last project on the "Who is using Hibernate?" Wiki page.