Hibernate, like all other object/relational mapping tools, requires metadata that governs the transformation of data from one representation to the other (and vice versa). In Hibernate 2.x, mapping metadata is most of the time declared in XML text files. Another option is XDoclet, utilizing Javadoc source code annotations and a preprocessor at compile time. The same kind of annotation support is now available in the standard JDK, although more powerful and better supported by tools. IntelliJ IDEA, and Eclipse for example, support auto-completion and syntax highlighting of JDK 5.0 annotations. Annotations are compiled into the bytecode and read at runtime (in Hibernate's case on startup) using reflection, so no external XML files are needed.

The EJB3 specification recognizes the interest and the success of the transparent object/relational mapping paradigm. The EJB3 specification standardizes the basic APIs and the metadata needed for any object/relational persistence mechanism. Hibernate EntityManager implements the programming interfaces and lifecycle rules as defined by the EJB3 persistence specification. Together with Hibernate Annotations, this wrapper implements a complete (and standalone) EJB3 persistence solution on top of the mature Hibernate core. You may use a combination of all three together, annotations without EJB3 programming interfaces and lifecycle, or even pure native Hibernate, depending on the business and technical needs of your project. You can at all times fall back to Hibernate native APIs, or if required, even to native JDBC and SQL.

Please note that this documentation is based on a preview release of the Hibernate Annotations that follows the public final draft of EJB 3.0/JSR-220 persistence annotations. This work is already very close to the final concepts in the new specification. Our goal is to provide a complete set of ORM annotations, including EJB3 standard annotations as well as Hibernate3 extensions for cases not covered by the specification. Eventually you will be able to create all possible mappings with annotations. See the Appendix A, Compliance and limitations section for more information.

The EJB3 Public final draft has change some annotations, please refer to http://www.hibernate.org/371.html as a migration guide between Hibernate Annotations 3.1beta7 and 3.1beta8.