[Hibernate-devel] best practices doc

[Gavin_King/Cirrus%<CI...@ci...>]

I'd like to throw this up for discussion. Anybody disagree with any of
these points or have any new ones?

==================================================================

*Hibernate ''Best'' Practices

***use fine grained objects
Write fine-grained classes and map them using |<component>| or
|<component-element>|. Use an |Address| class to encapsulate |street|,
|suburb|, |state|, |postcode|. This encourages code reuse and simplifies
refactoring.

***declare identifier properties on persistent classes
Hibernate makes identifier properties optional. There are all sorts of
reasons why you should use them. We recommend that identifiers be
'synthetic' (generated, with no business meaning) and of a non-primitive
type. For maximum flexibility, use |java.lang.Long| or |java.lang.String|.

***place each class mapping in its own file
Don't use a single monolithic mapping document. Map |com.eg.Foo| in the
file |com/eg/Foo.hbm.xml|.

***load mappings as resources
Deploy the mappings along with the classes they map.

***consider externalising query strings
This is a good practice if your queries call non-ANSI-standard SQL
functions. Externalising the query strings will make the application more
portable.

***use bind variables
As in JDBC, _always_ replace non-constant values by "?". Never use string
manipulation to bind a non-constant value in a query!

***don''t manage your own JDBC connections
Hibernate lets the application manage JDBC connections. This approach
should be considered a last-resort. If you can't use the built-in
connections providers, consider providing your own implementation of
|cirrus.hibernate.connection.ConnectionProvider|.

***consider using a custom type
Suppose you have a Java type, say from some library, that needs to be
persisted but doesn't provide the accessors needed to map it as a
component. You should consider implementing |cirrus.hibernate.UserType|.
This approach frees the application code from implementing transformations
to/from a Hibernate type.

***use hand-coded JDBC in bottlenecks
In performance-critical areas of the system, some kinds of operations (eg.
mass update/delete) might benefit from direct JDBC. But please, wait until
you _know_ something is a bottleneck. And don''t assume that direct JDBC is
_necessarily_ faster.

If need to use direct JDBC, it might be worth opening a Hibernate |Session|
and using that SQL connection. That way you can still use the same
transaction strategy and underlying connection provider.

***in a three tiered architecture, consider using |update()|
When using a servlet / session bean architecture, you could pass persistent
objects loaded in the session bean to and from the servlet / JSP layer. Use
a new session to service each request. Use |Session.update()| to update the
persistent state of an object.

***in a two tiered architecture, consider using session disconnection
When using a servlet only, you may reuse the same session for multiple
client requests. Just remember to disconnect the session before returning
control to the client.