Red Hat

In Relation To

The Hibernate team blog on everything data.

Hibernate 2.1.2

Posted by    |       |    Tagged as Hibernate ORM

I just released 2.1.2 . This is a maintenence release, meaning no especially exciting new features (the interesting work is all going on in the 2.2 branch). However there are some small changes that might make a big performance difference in certain specific cases, especially if you are using a second-level cache. I'm hoping that this release brings the 2.1 branch to the same level of maturity that we were able to achieve with 2.0.3.

Books for free...

Posted by    |       |    Tagged as Java EE

This is a reply on the Hibernate forum, read the full thread for the context.

As some noticed, I'm a bit impulsive about that kind of thing right now. We get one question a day, sometimes friendly, sometimes not so friendly, if we could just set up the book (Hibernate in Action) for free download or simply send it over.

Don't take it personal if I'm getting annoyed about that. It's sometimes just embarrassing when someone gives you the feeling that you owe them something, just because they use Hibernate. I'd like to explain why its not about the money for the book.

First, and that is really my own personal opinion, a professional Java developer should have enough money for whatever book in any case. Books are important, read at least one each month, better two. I don't buy any of that offshore jobs talk, but knowledge is the only thing that keeps you in business. I don't want to discuss $5 Amazon shipping costs about that.

Now I'd like to start a little rant here, so you better stop reading if you are not in the mood :)

Our software is free, our documentation is of course free, and we will always provide free support on a personal level in this forum, and whenever we think it is needed.

I also think that our software and the whole project shows that we are serious about what we are doing. We worked many nights and weekends last year. Gavin and me quit our jobs to make this possible. Max, David, Steve, Emmanuel spend hours a day after work, writing interesting things and answering questions (now up to 120/day) on the forum.

We really believe in professional open source as a business model in the software sector. Actually I'm now also employed by JBoss Group. We have two people working fulltime on Hibernate.

How do we earn our salary?

With open source, there are no license fees. This is great for developers, as they can sell the software they'd like to use to their project managers and accountants easily. Well, of course only if all the other qualities are right:

  • good software
  • good documentation and free support
  • commercial support (risk management)
  • nice extras

A successful vendor of closed software can provide the second for free, but you have to pay for the other three most of the time. Sometimes its hidden, sometimes not. The situation is quite different with an open source software project. First, there are no hidden costs, because you actually can't hide anything. Second, we as software developers don't like hiding any costs somewhere, we are not good with that kind of thing. It's much easier to tell people what they need and what it costs upfront. I also like the look on peoples faces if you admit that Hibernate solves only 95% of their problems, not 100! Shocking! The truth!

It's hard to break with the traditions and I remember the early Linux days when it was first used used commercially. You actually had to tell people that free software is good because they don't pay money for licenses. They wouldn't believe you, just don't ask for a (real) reason. Usually they expected some hidden costs in the other three items and simply denied that it was any good at all.

Sometimes, I think it was too much propaganda back then, now everyone expects everything for free!

To support a business, some revenue must be made from at least one of the four elements I listed.

I'm not talking about the book, because that really doesn't pay. I think most people know that books don't pay in the end, at least if your name is not Fowler or Bloch. Why do we write it then? It helps us to get more people (and therefore ideas and opinions) into Hibernate, and we can finally write down some thoughts we can't express in any other medium.

And yes, we also hope that it will help us to grow the Hibernate business. Thats our job. There is no professional quality without that background, or at least not for a long period of time.

Hibernate is naturally a very open project driven by the users. This will not change, no matter what our business model is. We think that listening to users and balancing requests is the heart of the project, it is the reason why people like it and why it works(tm).

If you are having problems...

Posted by    |       |    Tagged as

I just finished a consulting job at a large retailer where we managed to increase the performance of a Hibernate application by perhaps two orders of magnitude with just some fairly simple changes. It really drove home to me how almost all performance problems I've ever seen can be solved by either or both of:

  • appropriate session handling
  • appropriate association fetching strategies

(Note that I have not yet met a serious performance problem in Hibernate 2.x that I could not solve quite quickly.)

Hibernate's Session object is a powerful abstraction that allows some extremely flexible architectural choices. Unfortunately, this flexibility comes at a cost: many people seem to stuff it up! There are three well-understood patterns for managing Hibernate sessions correctly (actually, three-and-a-half, as I've recently discovered) and three common antipatterns. The fact that the antipatterns are more common than they should be suggests a real problem with our existing documentation, and highlights the fact that /we need to get this book out!/

The main reason we've previously been unable to explain the correct ways to handle Hibernate sessions is that we simply havn't had a decent language for describing our ideas. Since we've developed this language in the process of writing the book, explanations are much easier. The key concept is the notion of an /application transaction/. An application transaction is a unit of work from the point of view of the user; it spans multiple requests and multiple database transactions - it does, however, have a well-defined beginning and end. Even if you don't currently use this notion explicitly, you probably /do/ use it implicitly in your application.

Briefly, the three acceptable approaches are: session-per-request, session-per-request-with-detached-objects and session-per-application-transaction. A variation of the third approach is the newly-discovered session-per-application-transaction-with-flush-delayed-to-the-last-request (phew!). The three broken approaches are: session-per-operation (ie. many-sessions-per-request), session-per-user-session and session-per-application. If you are using any of these approaches, please stop.

The three acceptable approaches each have different performance and architectural implications and there is no best solution. It is incredibly important to choose the approach that is most suitable to your particular application (this was the key to the two-orders-of-magnitude improvement described above).

Association fetching is, I think, covered quite well in our documentation, but we still sometimes see people struggling with the dreaded n+1 SELECTs problem. So let me be very clear: Hibernate /completely/ solves the n+1 SELECTs problem! However, it takes some thought and a (very) little work on the part of the user to take full advantage of this fact. We recommend that all associations be configured for lazy fetching by default. Then, for particular use cases, eager outer join fetching may be chosen by specifying a LEFT JOIN FETCH clause in a HQL query, or by calling setFetchMode() for a Criteria query. (If you are too lazy to do this work, you could even try the new batch fetching features of Hibernate 2.1. We don't recommend this less elegant approach, however.)

Less common performance problems may be fixed by using a second-level cache, or occasionally by managing flushing manually (set the session flush mode to FlushMode.NEVER and flush manually when required). However, in almost all cases, acceptable performance can be achieved by concentrating upon the two items listed above.

Don't lock in the middle tier!

Posted by    |       |    Tagged as

One of the reasons we use relational database technology is that existing RDBMS implementations provide extremely mature, scalable and robust concurrency control. This means much more than simple read/write locks. For example, databases that use locking are built to scale efficiently when a particular transaction obtains /many/ locks - this is called /lock escalation/. On the other hand, some databases (for example, Oracle and PostgreSQL) don't use locks at all - instead, they use the multiversion concurrency model. This sophisticated approach to concurrency is designed to achieve higher scalability than is possible using traditional locking models. Databases even let you specify the required level of transaction isolation, allowing you to trade isolation for scalability.

Unfortunately, some Java persistence frameworks (especially CMP engines) assume that they can improve upon the many years of research and development that has gone into these relational systems by implementing their own concurrency control in the Java application. Usually, this takes the form of a comparatively crude locking model, with the locks held in the Java middle tier. There are three main problems with this approach. First, it subverts the concurrency model of the underlying database. If you have spent a lot of money on your Oracle installation, it seems insane to throw away Oracle's sophisticated multiversion concurrency model and replace it with a (less-scalable) locking model. Second, other (non-Java?) applications that share the same database are not aware of the locks. Finally, locks held in the middle tier do not naturally scale to a clustered environment. Some kind of distributed lock will be needed. At best, distributed locking will be implemented using some efficient group communication library like JGroups. At worst (for example, in OJB), the persistence framework will persist the locks to a special database table. Clearly, both of these solutions carry a heavy performance cost. Accordingly, Hibernate was designed to /not require/ any middle-tier locks - even thread synchronization is avoided. This is perhaps the best and least-understood feature of Hibernate and is the key to why Hibernate scales well. So why do other frameworks not just let the database handle concurrency?

Well, the only good justification for holding locks in the middle tier is that we might be using a middle-tier cache. It turns out that the problem of ensuring consistency between the database and the cache is an extremely difficult one and solutions usually do involve some use of middle-tier locking. (Incidently, most applications which use a cache do not solve this problem correctly, even in a non-clustered environment.)

So, for example, when Hibernate integrates with JBoss Cache, the cache implementation must obtain clustered locks internally (again, using JGroups). In Hibernate, we consider it a quality-of-service concern of the cache implementation to provide this kind of functionality. We can do this because Hibernate, unlike many other persistence layers, features a two-level cache architecture. This design separates the transaction-scoped /session cache/ (which does /not/ require middle-tier locking and delegates concurrency concerns to the database) from the process or cluster scoped /second-level cache/ (which /may/ require middle-tier locks). So when the second-level cache is disabled for a particular class, no middle-tier lock is required. Hence, in this case, the scalability of Hibernate is limited only by the scalability of the underlying database. Our design also allows us to consider other, more sophisticated approaches to ensuring consistency between the second-level cache and database - approaches that do not require the use of middle-tier locking. I'll keep this stuff secret for now; it is an active area of investigation!

Jason's observations

Posted by    |       |    Tagged as

Jason has pointed out some interesting things about the current release of Hibernate.

First, he notes that Hibernate's query cache may not currently be used with SwarmCache. This is due to SwarmCache not being a /replicated/ cache - it uses clustered eviction. Hibernate's query cache may be used with any replicated clustered cache, as long as clocks are synchronized in the cluster. Our documentation should make this requirement clearer. (For most applications, the query cache is not an especially useful feature, so this issue affects only a small number of users.)

Second, he has noticed that Hibernate currently writes to the second-level cache too often. I had not previously been aware of this issue. Hibernate was optimized with local, perhaps disk-backed, cache implementations in mind, where lookups are at least as expensive (in the case of a disk-backed cache, /more/ expensive) than puts. Jason has pointed out that in the case of a clustered cache, this is reversed and puts are much more expensive than lookups. We will provide a switch in a future point release of Hibernate 2.1 to adjust this behavior.

Finally, Jason is unhappy that we are not supporting JDK dynamic proxies and require CGLIB for lazy association fetching. (CGLIB causes problems if the JVM is running with a restrictive security policy.) Well, as I explained to Jason, Hibernate already provides a hook to allow the proxy implementation to be customized using a custom persister. (Dynamic proxy support could be implemented with a very small amount of code.) This evening I actually refactored this stuff slightly and introduced a ProxyFactory interface to make the hook more obvious.

I'd like to point out that the Hibernate project has many thousands of users and just a handful of active developers. As a result, we must prioritize feature requests by two considerations: first, how many users beg for the feature; second, how strategic a feature is with respect to the future direction of the project. We simply do not implement every requested feature since we have limited resources and are fighting a continual battle against code bloat (bloat is a /very/ serious issue if you are the person maintaining and enhancing the codebase). Hibernate is open source, so users with special requirements can always use a patched version in their application. In addition, we do not usually process feature requests via IM or javablogs.com! The correct process is to submit an enhancement request to JIRA (and let other users comment and vote) or, even better, to start a discussion in the mailing list. We may be an open source project; this does not mean that we are completely unprofessional and disorganized!

Criteria queries reloaded

Posted by    |       |    Tagged as

There were quite a few comments in response to my post about Criteria queries. I finally get around to responding. A number of people suggest a more tree-oriented approach, where we treat all logical operators as binary. For example, anonymous suggests the following:

session.createCriteria( Project.class,
  or(
      eq("name", "Hibernate"), 
      like("description", "%ORM%")
  )
);

Now, certainly logical operations are binary. But they are also /associative/, and this seems to be denied by the tree approach. We would never, ever write:

( (x=2 and x=1) and y=3 ) and z=4

We always write:

x=2 and x=1 and y=3 and z=4

This is particularly relevant in the case of Criteria queries since the common case is that we compose together many conditions using conjunction. (There were objections to my use of conjunction and disjunction, but I don't know of any other word for a string of expressions composed with and/or.)

Actually, the current API /does/ already allow this alternative. We have Expression.or() and Expression.and(). But to me they seem to be much messier than add().

Carl Rosenberger, the man behind SODA and db4o writes:

In my opinion a clean object querying system is the first and foremost 
basis for any standard on object persistence. 

Enhancers/Reflection/BCEL/code calls to make objects persistent 
all this can be very quickly exchanged, if you want to switch the 
underlying system.

Queries can not be exchanged!

And I couldn't possibly agree more! This is absolutely right. He goes on to say:

Could you maybe bring this thought into JDO 2.0 ? Please ?

Besides, I am positive that a de-facto standard for object querying will 
have a much greater impact on the industry than JDO.
Java is not the only programming language on this planet. 

In fact, I've mentioned the idea of adopting a better query approach to a couple of the guys on the expert group, but didn't get much of a positive response. Besides, I'm not at all convinced that it is even possible to design a nice query language or API in a committee environment. These kind of things need a strong unified vision. Comittees are okay at standardizing mature solutions to well-understood problems, but it is my view that object-oriented querying is a far from well understood problem. Especially, it does not seem to be commonly appreciated that an ORM-oriented query language would look quite different to an object database query language!

James Strachan is pimpin' Groovy , his new JVM-compatible language (I'm not sure if its quite correct to call it a scripting language) that looks quite like Python but features one of the best things about SmallTalk: closures. (Digression: it seems to be widely believed that the JDK Collections API is one of Java's good points. But if you've ever used collections in SmallTalk, you'll know just how impoverished Java actually is when it comes to working with collections. Iterators are far, far uglier than the more functional approach available in languages with closures. If there is /anything/ that I would ask to be fixed in Java, it wouldn't be the lack of generics, the lack of enums, etc, etc - it would be the lack of closures.) Anyway, I'm interested in what James has to say, but I'm skeptical toward the notion that an object-oriented expression language is the right starting point for an ORM query language. Firstly, relational databases implement very different null value semantics to object oriented languages. In fact, SQL's ternary logic is /quite/ different to the binary logic implemented by programming languages. Secondly, equality is a much more slippery concept in the object oriented world than in the database world. For these reasons, and others, we have chosen to base HQL on SQL, not on Java-like syntax. It is my view that this was one of the best decisions we've made.

Razvan describes what (s)he calls an an associative query model (much like the query in JavaSpaces). If I'm not mistaken, this is what we usually call query by example. I'll get round to discussing Hibernate's new Example query API in a future post...

What are scalar types anyway?

Posted by    |       |    Tagged as

About two years ago, a co-worker asked me innocently: What are scalar types anyway?

I realized that I had used that term one too often and he was really asking if I can define it, not just use it.

On my way to the JavaPolis conference I had some time to write up what I understand about /scalar types/. The truth is, I had a lot of time, because my train got the wrong route (twice!), and we even had to go backwards several times.

Just to make this entry even more exciting, I'll also explain what I understand as a /variable/ and a /value/.

A type names a /set of values/. So, a type has a name, we know that. But what is this set of values? According to Chris Date, a value is an /individual constant/. Now, stop thinking in software terms, and think about information and data. A value has, by definition, no location in time and space. For example, we don't know where or when the value Hibernate is located, this question doesn't even make sense. It's a value nevertheless, just as the number 4 and the number 2.

We know that in a strongly typed language such as Java, every value has to have a type. This means that every value in our software carries its type with it. Instead of working with value literals, as I did in the previous paragraph, we assign them to variables. A variable gives a value a location in time and space. In Java, the type of a value is associated with the variable.

String projectName;
projectName = "Hibernate"

In the first line, we declare that String is the type of the variable projectName. The values that can be assigned to projectName are therefore limited to the set of values allowed for the String type, i.e., all character strings. In the next line, we assign the value Hibernate to the variable projectName. The assignment operator (=) checks both operands for compatibility: Is the given value in the set of values allowed for the variables type? Strong typing means that this check is performed for all operations, including all method (operator) calls, not only assignment.

Let's talk about types in Java. We have built-in types such as String, but also custom user-defined types, such as Project. But a Java /class/ is only the mechanism used for type declaration and implementation. Sometimes we are sloppy and say a class is a type, but strictly speaking, it is not. A type is all externally visible elements of a class, that is all operators (methods) and components (attributes) declared public. We just use the mechanism of a class to define this, and of course, to implement the actual (internal) representation. So the following class defines and implements the Project type:

public Project {

   public String projectName;

   public void makeOpenSource() {
      ...
   }

   public Team getProjectTeam() {
      ...
  }

}

The Project type has one component and two operators. But where is this set of values defined?

Consider the type Object in Java: This type implies a set with all possible values. So, in fact, the set is implicit if you create a type. In other words, if you declare a variable of type Object, you can assign whatever value you want. By creating a type (writing a class or interface), you narrow that set. For example, a type Project might imply a set of all possible projects. You can of course further restrict the allowed values by adding constraints to that type (only projects with a name shorter than 10 characters), but thats not the issue here.

Back to the initial question: A scalar type is a type that is /encapsulated/, that is, it doesn't have any user-visible components. The Project type in the example above is non-scalar, it has the user-visible component (attribute) projectName.

On the other hand, the Team returned by the select operator getProjectTeam does not reveal a component, but only gives us a part of the possible representation of a Project. We simply don't now (and shouldn't care) if the Team returned is internally a component (attribute) of the Project or something completely different. The implementation is hidden.

If we follow the Best Practices for POJOs (or JavaBeans), we automatically create scalar types. Adding a select operator such as getProjectName and removing the public visible component projectName would make the example Project type scalar, that is encapsulated or atomic.

Keep in mind that /scalar/ is not related to /complexity/ in any way. Just because we call Java primitives scalar, doesn't make all scalar types primitive.

Query Objects vs Query Languages

Posted by    |       |    Tagged as

Chris Winters doesn't like object-oriented query APIs. Since Hibernate emphasizes the query /language/ approach, I'm not the best person to disagree with him here. Criteria queries are usually noisier, no doubt about that. And the query languages I've seen tend to be more expressive. Writing arithmetic and even logical expressions is a breeze in a query lanugage, but certainly not in an object-oriented Criteria API.

However, there are a couple of advantages of the Criteria approach. First, some folks like the fact that more can be done to validate the query at compile time. This is no big deal to me because I'm very unit test oriented. Much more importantly, object-oriented query APIs are much better for building queries programmatically. String manipulations suck! Getting your parentheses and whitespace right for all combinations of criteria is a pain. I've seen some truly ugly code that builds HQL strings and it could be rewritten /much/ more neatly using the Criteria API.

Especially, the new query by example stuff could potentially reduce 20 lines of code that builds a query containing the needed properties of Person to:

session.createCriteria(Person.class)
    .add( Example.create(elvis) )
    .list();
    

Well, I suppose query by example is a bit of an extreme case, and you could perhaps implement a similar feature in a query language.

Finally, object oriented query APIs can be more user-extensible. This is what I like best.

P.S. The code example Chris gives is a bit unfair to object APIs. Hibernate's Criteria API is much less verbose than that, partly due to the support for method chaining (which is barely used in Java, so I betray the time I spent with SmallTalk).

Names, what's in 'um?

Posted by    |       |    Tagged as

Names are important in computing. Really Important. I'm not talking about calling classes sensible things like UpdateUserDetailsCommand in preference to UpdUDetsCd. I mean the names of products themselves. A great name tells us lots about a piece of software: it tells us that the creater has some imagination, a sense of style even. It tells us that this person is serious about the success of the product, that they understand that there is more to making great software than writing great code.

Java is a fantastic name for just about anything. I love the ambiguity; coffee, or the largest island of the Indonesian archipeligo? There is no way I could hear the name Java and not wonder what it is a name for. C# (pronounced cee-hash by those in the know) is twee and derivative. Its pathetic enough trying to impress girls with the fact that I am a Java developer. Imagine if I had to say I was a cee sharp or dot net programmer? Ugggh. But from this we can learn something of the mindset that created these two languages - C# /is/ actually more derivative than Java.

So, if we have eliminated C# as the next step forward in languages, what about the other two possible Java-replacements: Python and Ruby. Well, Python is great, of course. There's that ambiguity once again: funny Englishmen, or snakes. Snakes are cool. Actually, naming things after animals is /always/ cool, even Ants. Ruby grows on me. I don't /love/ it, but as an English name given by a non-native English speaker, I'm happy to give it a pass. I've noticed that non-native speakers tend to name their projects by horrible acronyms.

The Apache project gives us some great examples of both good and bad. Tapestry is a beautiful, evocative name, just perfect for a web presentation framework. Struts is a good (perhaps a little too obvious) pun on framework. Lucene and Avalon are nice enough. Ant we mentioned already. commons-lang is an abomination, being the concatenation of commons (ugh) with that incredibly romantic English word lang. Worse, the concatenation is performed with a hyphen. Names don't have hyphens in them, guys! (Well, apart from Mike's ). Commons could evoke either typical or communal or both; neither interpretation is inspiring in this age. Actually, commons seems to be Jakarta's moniker for stuff we don't have proper names for or, perhaps, stuff that doesn't really deserve to be a real project. Similarly, commons-primitives could /almost/ conjure up some kind of vision of neolithic tribal society, uncorrupted by modern notions of private property .... but it doesn't. To me this indicates something about the respective quality of the projects. Would any truly committed developer, bulding something they love and believe in, possibly call their project commons-lang? Nope. They would call it Tapestry. If they had Howard's sense of theater, that is.

In the realm of distributed computing, we have been given CORBA - a nice, easily pronouncable acronym that sounds like a real English word and even better reminds us of snakes - and the ridiculous WSDL (pronounced whizz-dull, which is an oxymoron). I guess this means that Web Services are just another dead end - surely, nothing useful could ever be named WSDL?

Being a contrarian, I named our project with a verb. Hibernate isn't a thing - it's not even a state of mind; it's something you /do/.

disclaimer: this post is meant in good humour, please don't take offense

Designing "query by criteria"

Posted by    |       |    Tagged as

One of the great improvements in Hibernate 2.1 is that we finally have a mature Criteria query API. For a very long time I let this feature languish because I just wasn't sure what it should really look like. Every QBC API I've looked at is designed differently and there is certainly nothing like a standard API to learn from. I've seen everything from this:

new Criteria(Project.class)
  .addEq("name", "Hibernate")
  .addLike("description", "%ORM%")
  .execute();

to this:

Criteria crit = new Criteria(Project.class)
crit.getProperty("name").eq("Hibernate);
crit.getProperty("description).like("%ORM%");
crit.execute();

I don't like either of these approaches because the addition of new types of criterion requires the uncontrolled growth of a single central interface (Criteria, in the first case; Property in the second).

I like the second approach even less because it is very difficult to chain method calls. What should the eq() method return? Well, it seems most reasonable that it would return the receiving object (ie. the property). But it is very unusual to apply multiple criteria to the same property! So we would really prefer it to return the Criteria if we wanted to chain method calls. Well, I don't know about you, but I think that any API that returned the receiver from two calls ago might not be considered intuitive. So we are stuck with that evil temp variable.

I'd seriously consider improving this second approach to look like this:

new Criteria(Project.class)
  .getProperty("name").eq("Hibernate)
  .and()
  .getProperty("description).like("%ORM%");
  .execute();

Which is actually very clean. Unfortunately, the interfaces themselves are quite bizzare: and() is an operation defined by .... Criterion? The and() method returns .... the Criteria? This doesn't feel like a very natural OO design. And I think it would confuse new users. I'll come back to another reason why and and or should not be operations at all.

As a variation upon the first approach, I have seen the following:

new Criteria(Project.class)
  .add( new Equals("name", "Hibernate") )
  .add( new Like("description", "%ORM%") )
  .execute();

This avoids the problem of the Criteria interface growing out of control. But I hate Java constructors almost as much as I hate temp variables! The problem with constructors in Java is that they cannot be given meaningful names. We can't call a constructor EqualsIgnoreCase() if the class is named Equals. Secondly, once we start using constructors, we pretty much permanently nail down the Criterion class hierarchy. We tie client code directly to the concrete classes. I can't change my mind later and decide that Equals and EqualsIgnoreCase should be different classes.

Eventually I ended up being most influenced by the Cayenne query API (whch I presume was in turn influenced by Apple's WebObjects). Cayenne uses a class with static factory methods to create Criterion instances. Actually, Cayenne misnames the criterion class Expression and I stupidly inherited this misnaming in our (Hibernate) factory class. So, we ended up with:

session.createCriteria(Project.class)
  .add( Expression.eq("name", "Hibernate") )
  .add( Expression.like("description", "%ORM%") )
  .list();

Notice that this code does not use any concrete classes other than the static factory class - its all interfaces!

The downside of this design is that there are more characters in add( Expression.eq()) than in add( new Eq()) or addEq(). So it is certainly more verbose. It is also noisy. What stands out in the code above is the two occurrences of Expression. But they are the least important thing in the code.

Fortunately for me, JDK1.5 will come along and give us static imports. Static imports have been very unfairly maligned in the past, so let me try to set the record straight. If I add import net.sf.hibernate.expression.Expression.*, the code example above becomes:

session.createCriteria(Project.class)
  .add( eq("name", "Hibernate") )
  .add( like("description", "%ORM%") )
  .list();

This is now less verbose and more readable than the version that used constructors. I'm halfway done.

A second problem is the logical combination of criterions. and and or are each associative, but a string of both ands and ors is certainly not associative. So it seemed critically important to me that the precedence of the logical operators is crystal clear from the structure of the code. I hate the following:

session.createCriteria(Project.class)
  .addAnd( eq("name", "Hibernate") )
  .addAnd( like("description", "%ORM%") )
  .addOr( like("description", "%object/relational%") )
  .list();

I've seen a number of APIs like this and I still don't have a clue how the previous code is intended to be read. The same problem applies to this variation:

new Criteria(Project.class)
   .getProperty("name").eq("Hibernate)
   .and()
   .getProperty("description).like("%ORM%")
   .or()
   .getProperty("description).like("%object/relational%")
   .execute();

OK, OK, I actually do know that conjunction usually has a higher precendence than disjunction - but I would never, ever write code that depended upon this. It just isn't readable. And we certainly can't always rely upon operator precedence - we do need some way to express grouping. Anyway, I think this problem would affect any API which offers and() and or() as methods. So let's not make and() and or() be operations at all.

By the way, worst of all is this:

new Criteria(Project.class)
   .getProperty("name").eq("Hibernate)
   .and( crit.getProperty("description).like("%ORM%") )
   .execute();

And is a symmetrical operation! This symmetry should be obvious.

The solution is to treat Conjunction and Disjunction in exactly the same way as atomic Criterions. Make them Criterions, not operations.

session.createCriteria(Project.class)
  .add( Expression.disjunction()
      .add( eq("name", "Hibernate") )
      .add( like("description", "%ORM%") )
  )
  .list();

Well, that's a couple too many parentheses for my taste. I'm considering supporting something like the following in Hibernate:

session.createCriteria(Project.class)
  .createDisjunction()
      .add( eq("name", "Hibernate") )
      .add( like("description", "%ORM%") )
  .list();

My big problem here is that createDisjunction() would need to return a new instance of Criteria (wrapping a Disjunction) just so that we can call list() without needing a new temp variable. I'm not sure if I like this. Currently Expression.disjunction() just returns an instance of Disjunction directly - and Disjunction implements only the Criterion interface. I guess we're still searching for perfection...

back to top