Setting up an annotations project

Requirements

Download and unpack the Hibernate Annotations distribution from
the Hibernate website.

首先从Hibernate官方网站下载并解压Hibernate Annotations的发布包。

This preview release requires Hibernate 3.1.1 and
above. Do not use this release of Hibernate Annotations with an older
version of Hibernate 3.x!

这个预览版要求使用Hibernate 3.1.1或更高版本。请不要和老版本的Hibernate 3.x混合起来使用。

This release is known to work on Hibernate core 3.1.1

这个版本在Hibernate core 3.1.1的基础上工作良好。

Make sure you have JDK 5.0 installed. You can of course continue
using XDoclet and get some of the benefits of annotation-based
metadata with older JDK versions. Note that this document only
describes JDK 5.0 annotations and you have to refer to the XDoclet
documentation for more information.

首先确定你已经安装了JDK 5.0。当然就算使用低版本的JDK，
你仍然可以通过使用Xdoclet获得基于注解的元数据带来的部分好处。
不过请注意本文档只描述跟JDK5.0注解有关的内容，关于Xdoclet请参考相关文档。

Configuration

First, set up your classpath (after you have created a new project
in your favorite IDE):

Copy all Hibernate3 core and required 3rd party library files
(see lib/README.txt in Hibernate).

Copy hibernate-annotations.jar and
lib/ejb3-persistence.jar from the Hibernate
Annotations distribution to your classpath as well.

To use the , add the lucene jar
file.

首先就是设置classpath(当然是在IDE中创建了一个新项目之后)。

将Hibernate3核心文件以及其依赖的第三方库文件(请参考lib/README.txt文件)加入到你的classpath里面。

将hibernate-annotations.jar
和lib/ejb3-persistence.jar加入到你的classpath 里面。

如果要使用，还需要将lucene的jar文件加入你的classpath。

We also recommend a small wrapper class to startup Hibernate in a
static initializer block, known as HibernateUtil.
You might have seen this class in various forms in other areas of the
Hibernate documentation. For Annotation support you have to enhance this
helper class as follows:

programlisting

package hello;

import org.hibernate.*;
import org.hibernate.cfg.*;
import test.*;
import test.animals.Dog;

public class HibernateUtil {

private static final SessionFactory sessionFactory;

static {
try {

sessionFactory = new AnnotationConfiguration().buildSessionFactory();
} catch (Throwable ex) {
// Log exception!
throw new ExceptionInInitializerError(ex);
}
}

public static Session getSession()
throws HibernateException {
return sessionFactory.openSession();
}
}

我们推荐在一个包装器(wrapper)类HibernateUtil
的静态初始化代码块中启动Hibernate。或许你在Hibernate文档的其他很多地方看到过这个类，
但是要在你的项目中使用注解，还需要对这个辅助(helper)类进行扩展。扩展如下:

programlisting

package hello;

import org.hibernate.*;
import org.hibernate.cfg.*;
import test.*;
import test.animals.Dog;

public class HibernateUtil {

private static final SessionFactory sessionFactory;

static {
try {

sessionFactory = new AnnotationConfiguration().buildSessionFactory();
} catch (Throwable ex) {
// Log exception!
throw new ExceptionInInitializerError(ex);
}
}

public static Session getSession()
throws HibernateException {
return sessionFactory.openSession();
}
}

Interesting here is the use of
AnnotationConfiguration. The packages and annotated
classes are declared in your regular XML configuration file (usually
hibernate.cfg.xml). Here is the equivalent of the
above declaration:
这里比较有意思的是使用到了AnnotationConfiguration类。
在XML配置文件(通常是hibernate.cfg.xml)中则定义了包和经过注解的类。下面的xml和前面的声明等价:

programlisting

Note that you can mix the hbm.xml use and the new annotation
one.
注意现在你可以混合使用hbm.xml和注解.

Alternatively, you can define the annotated classes and packages
using the programmatic API
除了上面的方式,你还可以通过编程的方式定义包括注解的类和包

programlisting

sessionFactory = new AnnotationConfiguration()
.addPackage("test.animals") //the fully qualified package name
.addAnnotatedClass(Flight.class)
.addAnnotatedClass(Sky.class)
.addAnnotatedClass(Person.class)
.addAnnotatedClass(Dog.class)
.buildSessionFactory();

You can also use the Hibernate Entity Manager which has it's own
configuration mechanism. Please refer to this project documentation for
more details.
你也可以使用Hibernate Entity Manager来完成以上功能。Hibernate Entity Manager有自己的一套配置机制，详情请参考相关文档。

There is no other difference in the way you use Hibernate APIs with
annotations, except for this startup routine change or in the
configuration file. You can use your favorite configuration method for
other properties ( hibernate.properties,
hibernate.cfg.xml, programmatic APIs, etc). You can
even mix annotated persistent classes and classic
hbm.cfg.xml declarations with the same
SessionFactory. You can however not declare a class
several times (whether annotated or through hbm.xml). You cannot mix
configuration strategies (hbm vs annotations) in a mapped entity hierarchy
either.
除了启动方式和配置文件有所改变之外，结合注解来使用Hibernate API和以前没有什么区别，
在其他方面你还是可以继续保持以前的习惯和喜好(hibernate.properties，
hibernate.cfg.xml， programmatic APIs等等)。
甚至对于同一个SessionFactory，你都可以混合带注解的持久类以及传统的bm.cfg.xml声明方式。
然而你不能多次声明同一个类(要么通过注解要么通过hbm.xml配置文件)，
而且在一个映射实体的类继承层次中，这两个配置策略不能同时使用.

To ease the migration process from hbm files to annotations, the
configuration mechanism detects the mapping duplication between
annotations and hbm files. HBM files are then prioritized over annotated
metadata on a class to class basis. You can change the priority using
hibernate.mapping.precedence property. The default is
hbm, class, changing it to class,
hbm will prioritize the annotated classes over hbm files when a
conflict occurs.
为了简化从hbm文件到注解的迁移过程，
配置机制将自动检测在注解和hbm文件中重复的映射。
默认情况下hbm文件中的声明比类中的注解元数据具有更高的优先级。
这种优先级的设定是以类为单位的。
你也可以通过hibernate.mapping.precedence修改这种优先级。
默认的值是hbm, class，
如果改为class,hbm，当发生冲突的时候，类中的注解将比hbm文件具有更高的优先级。