Hydrate Cookbook
   Getting Started 
   API Docs 
  EJB 3.0 Support 

SourceForge.net Logo

What is Hydrate?

Hydrate is a Java tool that provides for fast efficient and error-free transformation of data between three different representations: relational databases, objects in an object-oriented programming language and extended markup language (XML). Each of these representations has its strengths and weaknesses as shown in the diagram below; but which should you use as a basis for your application design?


Hydrate relaxes some of the pressure on this decision by providing tools for moving data from one representation to another, guided by a master UML class representation of that data.

When Should I Use Hydrate?

Here are few example situations in which Hydrate will significantly reduce the amount of development effort required to create a solution:

  • You want to lay a domain object model view over an existing database or set of databases. Hydrate gives you the tools to design that model in UML and map your existing data to that model. Once in the object space, you can perform complex manipulations on the objects, calculate results and save information back to a relational cache for searching or reloading, as well as converting the results to XML for sending to downstream systems or transforming to a readable format for display.

  • Your project involves taking various data files fed from external systems that you want to pull into an object model on your server before writing the results down to a fully relational database. You can now respond to requests from external systems by rehydrating the data from its relational form and sending it out as XML documents or transforming those documents to a readable format for display.

  • You are building a data warehouse in which you have the broad specifications for the model, but want to provide for flexibility and adaptability for future unpredicted requests. Based on a core data model, Hydrate gives you the tools to create you database schema, and write information to it, but more significantly to subsequently lay a completely different object model perhaps aggregating some of the data over the top of that schema to process it in unforeseen ways.

  • You need to integrate data from many different data sources in a highly performant manner. SQL permits you to read a huge data set a row at a time and perform running calculations and filtering on that data. But the performance pressures can lead to code that is highly coupled with the database and what do you do if you need to integrate data from elsewhere in order to complete your calculations? Hydrate permits you to operate in the object space and integrate information from other sources on-the-fly.

When Should I Not Use Hydrate?

Object/Relational and Object/XML mappings are both fields with a lot of interest and support and Hydrate does not pretend to be the best solution for all applications. Here we highlight where you might be better off looking at other solutions:

  • Hydrate is designed for flexibility in mapping arbitrary relational schemas to your chosen domain object model. If you are working on a green-field application where you have plain old Java objects (POJOs) that you need to make into persistent objects, Hydrate is probably not for you as these goals correspond more closely to EJB 3, Hibernate, and other projects.

  • If you are looking for a straight in-memory object cache for an underlying database, there are better solutions in the market.

  • If you want complete abstraction from your persistence mechanism, and are looking for a tool that completely isolates you from the data storage mechanism, this is not part of the goal of Hydrate. JDO may be a better solution in this case.

  • If you have an XML document, particularly if it has an XML schema, and you are trying to map this to and from Java objects, while not caring about any other persistent representation then you are more aligned to JAXB, Castor and others.

What are Hydrate's Key Features?

  • To integrate legacy and other data schemas over which you have little control. Map data from many different data sources into a single self-consistent in-memory model. Different parts of the same object, as well as different sub-populations of the same object type can be drawn from different data sources, different schemas and even different database architectures.

  • Load, populate and connect up multiple object types from a single query. There is no limit to the number of object types that can be loaded from a single query, or to the complexity of the relationships that can be resolved between them. Objects read from a query are automatically merged into objects already in memory.

  • Full control over the SQL that runs against the database (if you need it). Any SQL queries simultaneously from multiple JDBC drivers, even using database specific optimizations, as long as they returns a result set.

  • Access and manipulate the same data through the rich and powerful XML toolset. Use the same meta data that describes your objects to easily read from, write to and validate any consistent XML schema. Use XML for display, data transmission or XSLT transformation. Load XML data back into objects.

  • Highly optimized performance for reading and writing SQL and XML. Since native types are used and SQL chatter is non-existent, database performance is comparable with doing the mapping by hand. XML reading and writing uses SAX exclusively.

What Are Hydrate's Innovations?

These are the techincal innovations in Hydrate that are found in very few other products in the Object/Relational mapping and SQL Mapping space.

  1. Multiple object types and their relationships loaded from a single query.
  2. Order independent merging of queries and XML data into memory.
  3. All or part of any object can be not set or not loaded.
  4. Multiple candidate keys supported and automatically reindexed.
  5. Composite keys may recursively include foreign key references.
  6. Automatic reverse reference fixup.
  7. XML schema(s) tightly integrated with object model.

Multiple object types and relationships loaded from a single query.

You can simultaneously map any number of object types from your query and link them up according to your declared relationships (one-to-many, many-to-many, etc.), all in a single operation.  Hydrate automatically takes care of resolving repeated object data from the query to a single object.  This powerful feature

Order independent mapping of queries and XML data.

You have a huge amount of flexibility in mapping from queries/XML to your object model.  You can run as many or as few queries as you need to pull into memory the data that you need for a particular calculation or report.  You can go to multiple data sources and/or read data from mutliple XML schemas.  You are free to execute these queries or XML parses in any order.  For example loading 'child' objects first then 'parent' objects works equally as well as loading 'parent' then 'child'.  The decision about which to use can be made based on your particular situation, for best possible clarity and performance.

All or part of an object can be 'not set'.

All commercial relational databases have a special value for eligible columns of 'null'.  This indicates that there is no value appropriate for a particular column, and, notwithstanding the debate about how exactly null should be used, or how many different types of 'null' there are, it is generally found to be useful in database design.  Object models tend to be quite poor in representing 'nulls' in code.  They are either ignored or mapped as object types which is very costly for an attribute that would otherwise be a native type.  Hydrate adopts conventions so that all optional fields (other than boolean) can have a value of not set, equivalent to 'null' in the database.

All or part of an object can be 'not loaded'.

In Hydrate, each column (including booleans) can have another special value of 'not loaded'.  This means that the value has not yet been read from any data source (query or XML).  This simple feature is incredibly powerful since it allows us to partially populate any part of an object, populate different parts of the same object from different data sources, or lazily load all or parts of an object.  Hydrate continues to use native types reference and store attributes.

Multiple candidate keys supported and automatically reindexed.

Each object can have multiple candidate keys, both simple and composite.  This means that you can load different information about the same object from different data sources that have a different way of keying your object.  Indexes are automatically maintained to permit fast look-up by key, and these are automatically rehashed when any part of the composite key changes.

Composite keys may recursively include foreign key fields.

For object models that do not use surrogate keys, part or all of the primary key of an object is often a reference to another object.  If that object's primary key also includes a foreign key reference, you end up with some quite complex naming and mapping problems.  However, this model is often very useful particularly if you are using your default relational schema as a place to cache results, since it avoids unneccessary joins when retrieving data.  Hydrate supports any level of recursion for foreign key fields in primary keys.

Automatic reverse reference fixup.

Bidirectional references create a relationship between the corresponding bean properties in the two objects that refer to one another.  Take the simple case of a bidirectional one-to-one relationship: person to spouse.  If we establish this link between Alice and Bob by invoking alice.setSpouse(bob), then in order to keep the model consistent, we must also call bob.setSpouse(alice).  However, before doing this we need to disentangle both Bob and Alice from any existing relationships by invoking bob.getSpouse().setSpouse(null) and alice.getSpouse().setSpouse(null).  The exact sequence of operations that needs to be performed to ensure that these relationships remain consistent depends on the relationship type (one-to-one, one-to-many, or many-to-many) and whether the to-one relationships are optional or mandatory.  This is error prone if left up to developers and can lead to problems that are very hard to track down.  Hydrate writes all of this code for you automatically.

XML Schemas tightly integrated with the object model.

An XML schema is a hierarchical representation of a data model.  Given any non-trivial UML object model there are any number of hierarchies that you could draw through it moving along the navigable relationships of the object model.  Hydrate's knowledge of the structure and relationships between objects makes it very simple to declare one or more such hierarchies and Hydrate will then generate a full typed XSD schema and the code to write and read XML compatible with that schema from a set of objects in memory.  This turns out to be very useful in passing object models over a serialized connection, saving cached versions of object model and reporting or displaying data through XSLT.

Where Can I Download A Copy?

The latest release of Hydrate can be found here.

Last updated: 4-Jun-2006