[hibernate-issues] [Hibernate-JIRA] Created: (HHH-2092) Programmatic config and XML config react differently to the same propety names (when not prefaced with "hibernate")

[John Kaplan (JIRA)]

Programmatic config and XML config react differently to the same propety names (when not prefaced with "hibernate")
-------------------------------------------------------------------------------------------------------------------

         Key: HHH-2092
         URL: http://opensource.atlassian.com/projects/hibernate/browse/HHH-2092
     Project: Hibernate3
        Type: Bug

  Components: core  
    Versions: 3.2.0.cr4    
 Environment: all
    Reporter: John Kaplan
    Priority: Minor


This is a usability problem with the Configuration api that surfaces when a user is trying programmatic configuration after using XML configuration. It is common usage that property names for XML configuration are not prefaced with "hibernate" (e.g. in the "getting started" tutorial). But for programmatic configuration, they are required to be prefaced. This violates a reasonable user expectation that similar interfaces should exhibit similar behavior when passed the same data.

If you try to use the property names from an XML config file in programmatic config, a variety of errors occur during session and transaction creation. These errors are difficult to troubleshoot for beginners, and it looks like programmatic config just doesn't work. Worse, if a user explicilty sets a hibernate property to its default through programmatic config (again following examples in "getting started") Hibernate behaves as expected, even though the user's intention failed and the hibernate property wasn't actually set. This sets a trap for the future failure of a change of that parameter's value which will be even harder to troubleshoot.

There is benefit to Hibernate support in fixing this, as users will no longer ask about errors rooted in this problem, and it will in a small way make Hibernate easier to learn.

The problem is a 2-line "if" block that was added to Configuration.addProperties() that is not reused in Configuration.setProperty(). The conditional of this statement checks if a property starts with "hibernate." and if it does not, it adds a copy of the parameter with the original name, and an extra copy of the parameter with the name prefaced with "hibernate.".

This is technically a snap to fix, but deciding on the right fix is the non-trivial part.

The most obvious fix is to move the 2-line "if" block to the Configuration.setProperty() method, and call that as a subroutine from its current place in Configuration.addProperties(). There are two upsides to this. First, the user's expectation of similar interfaces behaving the same is fuliflled in the most direct way, so the problem simply goes away with no explanations needed. Second, since this change is an addition, it should be completely backward-compatible for all but the most implementation-brittle tests. 

The downside to this solution is that though it is a backward-compatible behavior change, it still is a behavior change. Anyone aware of the current implementation of Configuration.setProperty() that is taking advantage of the fact that it WON'T add an additional hibernate-rooted property loses that differentiation. However, it is hard to conceive that anyone would want to make sure programmatic configuration did NOT add an extra "hibernate"-rooted parameter knowing that's exactly what XML configuration WILL do. This means someone created a parameter with a similar name to a Hibernate parameter, and they know they can only set it programmatically, and are OK with the idea that anyone who tries to set it with XML will screw it up.

Next possible fix is to create a new Configuration.setHibernateProperty() method that acts the same as Configuration.addProperties(), and keep Configuration.setProperty() the way it is. This makes sure there is no behavior change of current Hibernate code whatsoever. Another upside is that even the most rudimentary javadoc of the two versions of setProperty() is sure to make the behavior obvious to users, and so much reduces the chance of any further misunderstanding (at least among the subset of users who read the javadoc). The downside is that this adds another API method. If the API is frozen by a standards body or in some similar process, this is likely a pain - you know more than I.

Next down the line is keep the behavior the same but doc it. When I ran into this, I checked the javadoc and the chapter in the online doc about programmatic config. It would have saved me frustration and time hacking if something had said explicitly, "When you use programmatic config, you have to preface properties with 'hibernate.'. This is different than XML config where you don't." I think this is more of a band-aid over the interface design problem, but it's better than nothing.

Discussion of this issue, with me complaining and offering fixes, and the wily Max gallantly defending the status quo is at: 
http://forum.hibernate.org/viewtopic.php?p=2322023#2322023

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
   http://opensource.atlassian.com/projects/hibernate/secure/Administrators.jspa
-
For more information on JIRA, see:
   http://www.atlassian.com/software/jira