Mapping native queries

You can also map a native query (ie a plain SQL query). To achieve
that, you need to describe the SQL resultset structure using
@SqlResultSetMapping. Like
@NamedQuery, a
@SqlResultSetMapping can be defined at both package
level or class level. However its scope is global to the application. As
we will see, a resultSetMapping parameter is defined
the @NamedNativeQuery, it represents the name of a
defined @SqlResultSetMapping. The resultset mapping
declares the entities retrieved by this native query. Each field of the
entity is bound to an SQL alias (or column name). All fields of the
entity including the ones of subclasses and the foreign key columns of
related entities have to be present in the SQL query. Field definitions
are optional provided that they map to the same column name as the one
declared on the class property.

你还可以映射本地化查询（也就是普通SQL查询）。
不过这需要你使用@SqlResultSetMapping注解来描述SQL的resultset的结构。
@SqlResultSetMapping和@NamedQuery,
@SqlResultSetMapping一样，可以定义在类和包一级。
但是@SqlResultSetMapping的作用域为应用级。
下面我们会看到，@NamedNativeQuery 注解中
resultSetMapping参数值为@SqlResultSetMapping的名字。
结果集映射定义了通过本地化查询返回值和实体的映射。
该实体中的每一个字段都绑定到SQL结果集中的某个字段上。
该实体的所有字段包括子类的所有字段以及
关联实体的外键字段都必须在SQL查询中有对应的定义。
如果实体中的属性和SQL查询中的字段名相同，这种情况下可以对字段映射不进行定义。

programlisting

@NamedNativeQuery(name="night&area", query="select night.id nid, night.night_duration, "
+ " night.night_date, area.id aid, night.area_id, area.name "
+ "from Night night, Area area where night.area_id = area.id", resultSetMapping="joinMapping")
@SqlResultSetMapping(name="joinMapping", entities={
@EntityResult(name="org.hibernate.test.annotations.query.Night", fields = {
@FieldResult(name="id", column="nid"),
@FieldResult(name="duration", column="night_duration"),
@FieldResult(name="date", column="night_date"),
@FieldResult(name="area", column="area_id"),
discriminatorColumn="disc"
}),
@EntityResult(name="org.hibernate.test.annotations.query.Area", fields = {
@FieldResult(name="id", column="aid"),
@FieldResult(name="name", column="name")
})
}
)

In the above example, the night&area named
query use the joinMapping result set mapping. This
mapping returns 2 entities, Night and
Area, each property is declared and associated to a
column name, actually the column name retrieved by the query. Let's now
see an implicit declaration of the property / column.

在上面这个例子中，名为night&area的查询
和joinMapping结果集映射对应。
该映射返回两个实体，分别为Night
和Area，其中每个属性都和一个字段关联，
字段名通过查询获取。下面我们看一个隐式声明属性和字段映射关系的例子。

programlisting

@Entity
@SqlResultSetMapping(name="implicit", entities=@EntityResult(name="org.hibernate.test.annotations.query.SpaceShip"))
@NamedNativeQuery(name="implicitSample", query="select * from SpaceShip", resultSetMapping="implicit")
public class SpaceShip {
private String name;
private String model;
private double speed;

@Id
public String getName() {
return name;
}

public void setName(String name) {
this.name = name;
}

@Column(name="model_txt")
public String getModel() {
return model;
}

public void setModel(String model) {
this.model = model;
}

public double getSpeed() {
return speed;
}

public void setSpeed(double speed) {
this.speed = speed;
}
}

In this example, we only describe the entity member of the result
set mapping. The property / column mappings is done using the entity
mapping values. In this case the model property is
bound to the model_txt column. If the association to
a related entity involve a composite primary key, a
@FieldResult element should be used for each foreign
key column. The @FieldResult name is composed of the
property name for the relationship, followed by a dot ("."), followed by
the name or the field or property of the primary key.

在这个例子中，我们只需要定义结果集映射中的实体成员。
属性和字段名之间的映射借助实体中包含映射信息来完成。
在这个例子中，model属性绑定到model_txt字段。
如果和相关实体的关联设计到组合主键，
那么应该使用@FieldResult注解来定义每个外键字段。
@FieldResult的名字由以下几部分组成：
定义这种关系的属性名字＋"."＋主键名或主键字段或主键属性。

programlisting

@Entity
@SqlResultSetMapping(name="compositekey",
entities=@EntityResult(name="org.hibernate.test.annotations.query.SpaceShip",
fields = {
@FieldResult(name="name", column = "name"),
@FieldResult(name="model", column = "model"),
@FieldResult(name="speed", column = "speed"),
@FieldResult(name="captain.firstname", column = "firstn"),
@FieldResult(name="captain.lastname", column = "lastn"),
@FieldResult(name="dimensions.length", column = "length"),
@FieldResult(name="dimensions.width", column = "width")
}),
columns = { @ColumnResult(name = "surface"),
@ColumnResult(name = "volume") } )

@NamedNativeQuery(name="compositekey",
query="select name, model, speed, lname as lastn, fname as firstn, length, width, length * width as surface from SpaceShip",
resultSetMapping="compositekey")
} )
//we're missins @SqlREsultSetMappings so look at Captain
public class SpaceShip {
private String name;
private String model;
private double speed;
private Captain captain;
private Dimensions dimensions;

@Id
public String getName() {
return name;
}

public void setName(String name) {
this.name = name;
}

@ManyToOne(fetch= FetchType.LAZY)
@JoinColumns( {
@JoinColumn(name="fname", referencedColumnName = "firstname"),
@JoinColumn(name="lname", referencedColumnName = "lastname")
} )
public Captain getCaptain() {
return captain;
}

public void setCaptain(Captain captain) {
this.captain = captain;
}

public String getModel() {
return model;
}

public void setModel(String model) {
this.model = model;
}

public double getSpeed() {
return speed;
}

public void setSpeed(double speed) {
this.speed = speed;
}

public Dimensions getDimensions() {
return dimensions;
}

public void setDimensions(Dimensions dimensions) {
this.dimensions = dimensions;
}
}

@Entity
@IdClass(Identity.class)
public class Captain implements Serializable {
private String firstname;
private String lastname;

@Id
public String getFirstname() {
return firstname;
}

public void setFirstname(String firstname) {
this.firstname = firstname;
}

@Id
public String getLastname() {
return lastname;
}

public void setLastname(String lastname) {
this.lastname = lastname;
}
}

note

If you look at the dimension property, you'll see that Hibernate
supports the dotted notation for embedded objects (you can even have
nested embedded objects). EJB3 implementations do not have to support
this feature, we do :-)

观察dimension属性你会发现Hibernate支持用"."符号来表示嵌入式对象。
EJB3实现不必支持这个特征，但是我们做到了:-)

If you retrieve a single entity and if you use the default
mapping, you can use the resultClass attribute
instead of resultSetMapping:

如果查询返回的是单个实体，或者你打算使用系统默认的映射，
这种情况下可以不使用resultSetMapping
而是使用resultClass属性:

programlisting

@NamedNativeQuery(name="implicitSample", query="select * from SpaceShip",
resultClass=SpaceShip.class)
public class SpaceShip {

In some of your native queries, you'll have to return scalar
values, for example when building report queries. You can map them in
the @SqlResultsetMapping through
@ColumnResult. You actually can even mix, entities
and scalar returns in the same native query (this is probably not that
common though).

某些本地查询返回的是scalar值，例如报表查询。
你可以通过@ColumnResult将其映射到
@SqlResultsetMapping上。
甚至还可以在同一个本地查询的结果中混合实体和scalar类型（不过这种情况比较少见）。

programlisting

@SqlResultSetMapping(name="scalar", columns=@ColumnResult(name="dimension"))
@NamedNativeQuery(name="scalar", query="select length*width as dimension from SpaceShip", resultSetMapping="scalar")

An other query hint specific to native queries has been
introduced: org.hibernate.callable which can be true
or false depending on whether the query is a stored procedure or
not.

本地查询中还有另外一个hint属性：
org.hibernate.callable
的布尔变量值表明这个查询是否是一个存储过程。