[[tutorial_annotations]]
== Tutorial Using Native Hibernate APIs and Annotation Mappings

NOTE: This tutorial is located within the download bundle under `annotations/`.

.Objectives
- [*] Bootstrap a Hibernate `SessionFactory`
- [*] Use annotations to provide mapping information
- [*] Use the Hibernate native APIs


[[hibernate-gsg-tutorial-annotations-config]]
=== The Hibernate configuration file

The contents are identical to <<hibernate-gsg-tutorial-basic-config>> with one important difference...
The `<mapping/>` element at the very end naming the annotated entity class using the `class` attribute.


[[hibernate-gsg-tutorial-annotations-entity]]
=== The annotated entity Java class

The entity class in this tutorial is `org.hibernate.tutorial.annotations.Event` which follows JavaBean conventions.
In fact the class itself is identical to the one in <<hibernate-gsg-tutorial-basic-entity>>, except that annotations
are used to provide the metadata, rather than a separate mapping file.

[[hibernate-gsg-tutorial-annotations-entity-entity]]
.Identifying the class as an entity
====
[source, JAVA]
----
@Entity
@Table( name = "EVENTS" )
public class Event {
    ...
}
----
====

The `@javax.persistence.Entity` annotation is used to mark a class as an entity.  It functions the same as the
`<class/>` mapping element discussed in <<hibernate-gsg-tutorial-basic-mapping>>.   Additionally the
`@javax.persistence.Table` annotation explicitly specifies the table name. Without this specification, the default
table name would be _EVENT_.


[[hibernate-gsg-tutorial-annotations-entity-id]]
.Identifying the identifier property
====
[source, JAVA]
----
@Id
@GeneratedValue(generator="increment")
@GenericGenerator(name="increment", strategy = "increment")
public Long getId() {
    return id;
}
----
====

`@javax.persistence.Id` marks the property which defines the entity's identifier.

`@javax.persistence.GeneratedValue` and `@org.hibernate.annotations.GenericGenerator` work in tandem
to indicate that Hibernate should use Hibernate's `increment` generation strategy for this entity's identifier values.


[[hibernate-gsg-tutorial-annotations-entity-properties]]
.Identifying basic properties
====
[source, JAVA]
----
public String getTitle() {
    return title;
}

@Temporal(TemporalType.TIMESTAMP)
@Column(name = "EVENT_DATE")
public Date getDate() {
    return date;
}
----
====

As in <<hibernate-gsg-tutorial-basic-mapping, the `date` property needs special handling to account for its special
naming and its SQL type.

Attributes of an entity are considered persistent by default when mapping with annotations, which is why we don't see
any mapping information associated with `title`.


[[hibernate-gsg-tutorial-annotations-test]]
=== Example code

`org.hibernate.tutorial.annotations.AnnotationsIllustrationTest` is essentially the same as
`org.hibernate.tutorial.hbm.NativeApiIllustrationTest` discussed in <<hibernate-gsg-tutorial-basic-test>>.


[[hibernate-gsg-tutorial-annotations-further]]
=== Take it further!

.Practice Exercises
- [ ] Add an association to the `Event` entity to model a message thread. Use the _Developer Guide_
as a guide.
- [ ] Add a callback to receive notifications when an `Event` is created, updated or deleted.  Try the same with
an event listener.  Use the _Developer Guide_ as a guide.