Hydrate Cookbook
   Getting Started 
   API Docs 
  EJB 3.0 Support 

SourceForge.net Logo

Frequently Asked Questions (FAQ) for Hydrate Features

Q. What is Hydrate

Hydrate is a relational/object/XML mapping tool.  It is different from other open source and commercial tools that do object relational mapping or object XML mapping because its focus is in mapping existing relational and XML data into an object model of your choice as opposed to taking an obejct model and persisting it, or taking an XML schema and creating objects from it.

Q. Is Hydrate documentation available? Is Hydrate easy to Use?

A. Full documentation is available on the Hydrate website including a tutorial/feature walkthrough as well as reference material. The classes for hydrate have full javadoc information available, also online.

Q. Is Hydrate Mature?

Hydrate represents a rewrite of a commercially developed framework that has been operating in commercial production systems for 5 years. The original code was written under Java 1.1, but the current codebase is a 'from the ground up' rewrite that includes all of the features of the original, plus much more gleaned from experiences of running that project, as well as a far more comprehensive JUnit testing suite.

Q. How does Hydrate compare with O/R frameworks like EJB3 and Hibernate?

O/R mapping frameworks such as these focus on taking an object model that you have and saving it to a relational database. The starting point is the object model and the problem is 'how do I persist this object model into a relational model'. Hydrate's focus is the other way around: 'how to I take this relational data or XML data that I have been given and work with it through an object model of my choice'. That is not to say that you can't do this with other frameworks: Hibernate provides a rich toolset for mapping native SQL queries as well as reading and writing XML, however, this is not its focus, and as such you will get better performance and flexibility from Hydrate.

Q. Can I use Hydrate in an Application Server environment/outside an Application Server environment, with my favourite connection pooling and transaction management software, etc.?

You are responsible for giving the database connections to Hydrate for it to use. You can control the transactions externally on these database connections, or you can ask Hydrate to start and end a transaction as it performs a unit of work. Hydrate will always ensure that updates of a single object into multiple tables (as occurs with table per class inheritance) happens in an atomic unit. This strategy means that you have full control over the database connections that Hydrate uses to access and update data and as such over the transactional boundaries of any updates. Integration into management frameworks such as J2EE and Spring can be expected in future versions.

Q. How does Hydrate compare with O/R frameworks like JDO.

Hydrate explicitly does not try to abstract you completely away from the details of the database. Its philosophy is that relational databases are a GOOD THING and were invented for a GOOD REASON. If your primary aim in choosing a mapping framework is to completely avoid writing SQL, you should look elsewhere. If on the other hand, you value the flexibility of expression of the relational paradigm for dicing and slicing data, as well as your access to the specific features of your expensive database architecture, Hydrate should be a consideration.

Q. How does Hydrate compare with XML mapping tools like JAXB, Castor and XMLEncoder.

For Hydrate, the focus is the object model, and the XML is subservient to this. In fact, several XML schemas can be devised that take different routes through the object model and include different parts of it. JAXB and Castor, in contrast, take a more XML-centric approach where the object model is defined by the XML Schema.

The XML schema written by Hydrate is designed to be very easy to read and understand. The object model definition endows the code generator with sufficient knowledge about the types and structure of that model that it can write XML schemas that are logical, tightly typed and verifiable through a schema definition that is also written by the code generator. Contrast this with XMLEncoder that validates all documents produced by it against the same schema definition.

Q. What is Hydrate's performance like?

A. FAST. First and foremost, Hydrate uses code generation techniques which eliminate the need for unnecessary 'holder' objects for native types, as well as any on-the-fly introspection. For O/R mapping, Hydrate's ability to map and link together any number of object types from an arbitrary query frees the developer up to choose the most efficient query or queries to grab whatever data is required. The ability to easily use 'IN' clauses with object arrays, as well as caching prepared queries, also benefits performance significantly. Writing to the database also uses cached queries, prepared statements, as well as batch-mode updates in drivers that support it. For reading and writing XML, Hydrate uses SAX exclusively making this process lightning fast and avoiding the memory footprint of DOM implementations.

Q. Does Hydrate support lazy loading?

Lazy loading is a technique in reading objects from a relational database in which objects references are not fully instantiated into objects until they are actually used by the application code. Lazy loading has typically been implemented as a way of avoiding the performance problems associated with reading one-to-many mappings from databases in which a sub-query must be executed for each new object read from the database. Hydrate does not suffer from this problem and lets you choose on an attribute by attribute basis how much or how little of each object you load in a query. You can write a handler to respond to an attribute that has not been loaded being accessed, if you like, but you are almost always better off going back to the original query that populated the object and filling the attribute in there.

Q. If Hydrate is about laying an object model over an existing database, why are there no tools to convert a relational schema into objects?

There are many commercial and open source tools that enable you to generate an object model from a relational schema. The problem with a schema generated in this way is that it shows its heredity. The data in a relational schema has generally been forced against its will into what, let's face it, is a somewhat unnatural representation, in order to reap the benefits from the relational engine.  Also, a typical relational schema that has been around for more than one system enhancement will often be less than ideal in structure.  The decisions about how much to normalize, what primary and foreign keys are used, etc. is generally driven more by performance, resource needs and history, that by data modelling purity. Unless you are very lucky with your relational database schema, an object model generated from will always look like an object model generated from a relational schema.

In summary, tools that write your object model from a database are impressive at first, because you make a lot of apparent progress very quickly, but the models generated this way often end up costing you more effort in the long run.  Hydrate encourages you to think about the object model you would like to work with and then to write it down, even in the absence of you actual data model.  You can then take whatever obtuse data model you have been landed with an map it into the object model you want to work with.

Q. Does Hydrate support caching?

Yes, and no. One man's cache is another man's crock, so we have to be careful to define what we mean here. Hydrate currently prefers to promote a paradigm in which objects are read from the database each time a request is made, thus in effect, handing the responsibility for caching down to the database engine (many of which do a pretty good job). Hydrate works with the database drivers to permit them to cache queries and result sets.  Once the objects have been read into memory, you are also free to decide which of them you keep in memory between requests, and which you discard from memory.

Q. Does Hydrate have a GUI?

Yes, Hydrate has a simple, but effective GUI that is used for visualizing an object graph once written, as well as writing and mapping queries from your data sources. Full editing features for the GUI are under development.

Q. Does Hydrate support polymorphism?

A. Yes, Hydrate has tremendous flexibility in how to decide which concrete class of a class hierarchy to create when loading data. The simplest approach uses a discriminator column, but you can always kick down to discriminator code to decide which object will be built. Finally real-time specialization is in development where objects can be loaded as a (possibly abstract) base class and specialized into their 'true' concrete classes when more information is available.

In the default generated database, Hydrate uses table-per-class polymorphism, though you can tweak this if required by customizing the schema and queries.

Q. Does Hydrate cache queries and use prepared statements

Yes, Hydrate has a query cache that reuses the default read/write queries. Also, the SQL produced by Hydrate dynamic queries uses prepared statements that are stored for reuse. Performing a query that does 10000 individual inserts into a database will generate the insert statement once as a prepared statement and then reuse this statement for the other 9999 inserts. By setting batch mode, you could batch up these inserts (say into groups of 100) and this can have significant effects on performance for JDBC drivers that support it.

Q. Does Hydrate permit composite keys to be used on objects?

Yes. Hydrate supports surrogate keys, single valued keys and multiple valued (composite) keys. It also supports keys one or all of whose members is a reference to another object (which itself can contain key members that are references, and so on ad infinitum).  Finally Hydrate supports alternate keys for all objects, a feature that is indispensable in merging data from different data stores.

Q. Does Hydrate support (insert required mapping cardinality and navigability here)?

Hydrate supports one-to-one, one-to-many and many-to-many mappings, navigable in either or both directions.

Q. Can I map data from legacy data sources?

If this is your aim then you have come to the right place. Hydrate was designed as a way to efficiently map legacy data sources into your own domain model. You can merge information from multiple sources on different physical machines and using different underlying database architectures.

Q. How does Hydrate handle batch data?

Hydrate has a number of features that make it ideally suited to the handling of batch data. It is very fast and efficient, allows you to simultaneously build out your entire object graph from a single denormalized stream of data, and lets you perform operations on the objects as soon as they have been instantiated, rather than waiting for an entire feed file, batch of data or other large unit of data to be loaded.

Q. Does Hydrate support a persistence standard?

The current release of Hydrate does not support any persistence standard, though its use of Javabean style interfaces makes it compatible with other O/R solutions. In the next release we are working toward supporting the EJB 3.0 persistence specification (a pre-alpha preview is available in the current release)

Last updated: 4-Jun-2006