From 8c809ab97639a12d72a50d965c634a3331b54880 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Wed, 13 Oct 2010 11:36:27 +1000 Subject: [PATCH 1/4] Edits to Getting Started Guide --- .../main/docbook/en-US/content/preface.xml | 62 ++--- .../docbook/en-US/content/tutorial_native.xml | 259 +++++++++--------- 2 files changed, 165 insertions(+), 156 deletions(-) diff --git a/documentation/quickstart/src/main/docbook/en-US/content/preface.xml b/documentation/quickstart/src/main/docbook/en-US/content/preface.xml index f835e9cca1..9df3a545bc 100644 --- a/documentation/quickstart/src/main/docbook/en-US/content/preface.xml +++ b/documentation/quickstart/src/main/docbook/en-US/content/preface.xml @@ -39,49 +39,49 @@ Working with both Object-Oriented software and Relational Databases can be cumbersome and time consuming. - Development costs are significantly higher due to a paradigm mismatch between how data is represented in - objects versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments. - The term Object/Relational Mapping refers to the technique of mapping data from an object model representation - to a relational data model representation (and visa versa). See - for a good high-level discussion. + Development costs are significantly higher due to a paradigm mismatch between how data is represented in objects + versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments. The + term Object/Relational Mapping refers to the technique of mapping data between an object model representation to + a relational data model representation. See for a good high-level discussion. - - While having a strong background in SQL is not required to use Hibernate, having a basic understanding of - the concepts can greatly help you understand Hibernate more fully and quickly. Probably the single - best background is an understanding of data modeling principles. You might want to consider these resources - as a good starting point: - - - - - - - - - - - - - + + You do not need a strong background in SQL to use Hibernate, but having a basic understanding of the + concepts can help you understand Hibernate more fully and quickly. An understanding of data modeling + principles is especially important. You might want to consider these resources as a good starting point: + + + Data Modeling Resources + + + + + + + + + + + - Hibernate not only takes care of the mapping from Java classes to database tables (and from Java data types to - SQL data types), but also provides data query and retrieval facilities. It can significantly reduce - development time otherwise spent with manual data handling in SQL and JDBC. Hibernate’s design goal is to - relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for - manual, hand-crafted data processing using SQL and JDBC. However, unlike many other persistence solutions, - Hibernate does not hide the power of SQL from you and guarantees that your investment in relational technology - and knowledge is as valid as always. + Hibernate takes care of the mapping from Java classes to database tables, and from Java data types to SQL data + types. In addition, it provides data query and retrieval facilities. It can significantly reduce development + time otherwise spent with manual data handling in SQL and JDBC. Hibernate’s design goal is to relieve the + developer from 95% of common data persistence-related programming tasks by eliminating the need for manual, + hand-crafted data processing using SQL and JDBC. However, unlike many other persistence solutions, Hibernate + does not hide the power of SQL from you and guarantees that your investment in relational technology and + knowledge is as valid as always. Hibernate may not be the best solution for data-centric applications that only use stored-procedures to implement the business logic in the database, it is most useful with object-oriented domain models and business logic in the Java-based middle-tier. However, Hibernate can certainly help you to remove or encapsulate - vendor-specific SQL code and will help with the common task of result set translation from a tabular + vendor-specific SQL code and streamlines the common task of translating result sets from a tabular representation to a graph of objects. diff --git a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml index 8754648fa7..b0714781d6 100644 --- a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml +++ b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml @@ -5,20 +5,22 @@ Tutorial Using Native Hibernate APIs and <phrase>hbm.xml</phrase> Mappings - This tutorial is located within the download bundle under basic and illustrates - - - - using Hibernate mapping files (hbm.xml) to provide mapping information - - - - - using the native Hibernate APIs - - - + This tutorial is located within the download bundle under basic/. + + Objectives + + + using Hibernate mapping files (hbm.xml) to provide mapping information + + + + + using the native Hibernate APIs + + + +
The Hibernate configuration file @@ -29,44 +31,44 @@ - The connection.driver_class, connection.url, - connection.username and connection.password - property elements define JDBC connection information. These tutorials - utilize the H2 in-memory database. So these are all specific to running H2 in its in-memory mode. - connection.pool_size is used to configure Hibernate's built-in connection pool - how many connections to pool. + The connection.driver_class, connection.url, + connection.username and connection.password + property elements define JDBC connection information. These tutorials utilize the H2 + in-memory database, So the values of these properties are all specific to running H2 in its in-memory mode. + connection.pool_size is used to configure the number of connections in Hibernate's + built-in connection pool. - The built-in Hibernate connection pool is in no way intended for production use. It - lacks several features found on any decent connection pool. See the section discussion in - Hibernate Developer Guide for further information. + The built-in Hibernate connection pool is in no way intended for production use. It lacks several + features found on production-ready connection pools. See the section discussion in Hibernate Developer Guide for further information. - The dialect property specifies the particular SQL variant Hibernate with which - Hibernate will converse. + The dialect property specifies the particular SQL variant with which Hibernate will + converse. - In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if - your application targets multiple databases. This is discussed in detail in the - Hibernate Developer Guide + In most cases, Hibernate is able to properly determine which dialect to use. This is particularly useful + if your application targets multiple databases. This is discussed in detail in the Hibernate Developer Guide - The hbm2ddl.auto property turns on automatic generation of database schemas directly - into the database. + The hbm2ddl.auto property enables automatic generation of database schemas directly into + the database. - Finally, add the mapping file(s) for persistent classes to the configuration. The resource - attribute of the mapping element says to attempt to locate that mapping as a - classpath resource (via a java.lang.ClassLoader lookup). + Finally, add the mapping file(s) for persistent classes to the configuration. The + attribute of the mapping element causes Hibernate to attempt to locate that mapping as a + classpath resource, using a java.lang.ClassLoader lookup.
@@ -76,44 +78,38 @@ The entity Java class The entity class for this tutorial is org.hibernate.tutorial.hbm.Event. - - Notes About the Entity - - - This class uses standard JavaBean naming conventions - for property getter and setter methods, as well as - private visibility for the fields. Although this is - the recommended design, it is not required. - - - - - The no-argument constructor, which is also a JavaBean - convention, is a requirement for all persistent - classes. Hibernate needs to create objects for you, - using Java Reflection. The constructor can be - private. However, package or public visibility is - required for runtime proxy generation and efficient - data retrieval without bytecode instrumentation. - - - + + Notes About the Entity + + + This class uses standard JavaBean naming conventions for property getter and setter methods, as well as + private visibility for the fields. Although this is the recommended design, it is not required. + + + + + The no-argument constructor, which is also a JavaBean convention, is a + requirement for all persistent classes. Hibernate needs to create objects for you, using Java + Reflection. The constructor can be private. However, package or public visibility is required for runtime + proxy generation and efficient data retrieval without bytecode instrumentation. + + +
The mapping file - The hbm.xml mapping file for this tutorial is the classpath resource + The hbm.xml mapping file for this tutorial is the classpath resource org/hibernate/tutorial/hbm/Event.hbm.xml as we saw in - Hibernate uses the mapping metadata to find out how to load and - store objects of the persistent class. The Hibernate mapping - file is one choice for providing Hibernate with this metadata. + Hibernate uses the mapping metadata to determine how to load and store objects of the persistent class. The + Hibernate mapping file is one choice for providing Hibernate with this metadata. @@ -124,18 +120,18 @@ - Functions of the <literal>class</literal> mapping element + Functions of the <varname>class</varname> mapping element - The name attribute (combined here with the package - attribute from the containing hibernate-mapping element) names the FQN of - the class you want to define as an entity. + The attribute (combined here with the attribute from + the containing hibernate-mapping element) names the FQN of the class to be + defined as an entity. - The table attribute names the database table which contains the data for - this entity. + The attribute names the database table which contains the data for this + entity. @@ -153,30 +149,30 @@ - Hibernate uses the property named by the id element to uniquely identify rows - in the table. + Hibernate uses the property named by the id element to uniquely identify rows in the + table. - It is not strictly necessary for the id element to map to the table's actual - primary key column(s), but it is the normal convention. Tables mapped in Hibernate do not even - need to define primary keys. However, the Hibernate team strongly - recommends that all schemas define proper referential integrity. Therefore id - and primary key are used interchangeably throughout Hibernate documentation. + It is not required for the id element to map to the table's actual primary key + column(s), but it is the normal convention. Tables mapped in Hibernate do not even need to define + primary keys. However, it is strongly recommend that all schemas define proper referential + integrity. Therefore id and primary key are used interchangeably + throughout Hibernate documentation. - The id element here identifies the EVENT_ID - column as the primary key of the EVENTS table. It also identifies - the id property of the Event class as the property - containing the identifier value. + The id element here identifies the EVENT_ID column as + the primary key of the EVENTS table. It also identifies the + id property of the Event class as the property containing the + identifier value. - The generator element nested inside the id element informs - Hibernate about which strategy is used to generated primary key values for this entity. In this - example a simple incrementing count is used. + The generator element nested inside the id element informs Hibernate + about which strategy is used to generated primary key values for this entity. This example uses a simple + incrementing count. @@ -186,38 +182,37 @@ - The two property elements declare the remaining two properties of the - Event class: date andtitle. The - date property mapping includes the column attribute, but the - title does not. In the absence of a column attribute, Hibernate - uses the property name as the column name. This is appropriate for title, but since - date is a reserved keyword in most databases, you need to specify a non-reserved + The two property elements declare the remaining two properties of the + Event class: date and title. The + date property mapping includes the attribute, but the + title does not. In the absence of a attribute, Hibernate + uses the property name as the column name. This is appropriate for title, but since + date is a reserved keyword in most databases, you need to specify a non-reserved word for the column name. - The title mapping also lacks a type attribute. The types + The title mapping also lacks a attribute. The types declared and used in the mapping files are neither Java data types nor SQL database types. Instead, they are Hibernate mapping types. Hibernate mapping types are converters which translate between Java and SQL data types. Hibernate attempts to determine the correct - conversion and mapping type autonomously if the type attribute is not present in the + conversion and mapping type autonomously if the attribute is not present in the mapping, by using Java reflection to determine the Java type of the declared property and using a default mapping type for that Java type. In some cases this automatic detection might not chose the default you expect or need, as seen with the - date property. Hibernate cannot know if the property, which is of type + date property. Hibernate cannot know if the property, which is of type java.util.Date, should map to a SQL DATE, TIME, or TIMESTAMP datatype. - Full date and time information is preserved by mapping the property to a timestamp - converter (which identifies an instance of the class - org.hibernate.type.TimestampType). + Full date and time information is preserved by mapping the property to a timestamp converter, + which identifies an instance of the class org.hibernate.type.TimestampType. - Hibernate makes this mapping type determination using reflection when the mapping files are - processed. This process can take time and resources. If startup performance is important, consider + Hibernate determines the mapping type using reflection when the mapping files are processed. This + process adds overhead in terms of time and resources. If startup performance is important, consider explicitly defining the type to use. @@ -232,10 +227,10 @@ - The example code in these tutorials is done as JUnit tests mainly for ease of use. However it is - nice in that setUp and tearDown roughly illustrate - how a org.hibernate.SessionFactory would be created at the start up - of an application and closed at the end of the application lifecycle. + The examples in these tutorials are presented as JUnit tests, for ease of use. One benefit of this + approach is that setUp and tearDown roughly illustrate + how a org.hibernate.SessionFactory is created at the start-up of an + application and closed at the end of the application lifecycle. @@ -249,26 +244,42 @@ } - - The org.hibernate.cfg.Configuration class is the first thing to notice. In this - tutorial everything is simply configured via the hibernate.cfg.xml file - discussed in. - - - - The org.hibernate.cfg.Configuration is then used to create the - org.hibernate.SessionFactory which is a thread-safe object that is - instantiated once to serve the entire application. - - - - The org.hibernate.SessionFactory acts as a factory for - org.hibernate.Session instances as can be seen in the - testBasicUsage method. A org.hibernate.Session - should be thought of as a corollary to a "unit of work". + + Tutorial Workflow + + The configuration is loaded. + + The org.hibernate.cfg.Configuration class is the first thing to notice. In this + tutorial, all configuration details are located in the hibernate.cfg.xml file + discussed in . + + + + The <interfacename>org.hibernate.SessionFactory</interfacename> is created. + + The org.hibernate.cfg.Configuration then creates the + org.hibernate.SessionFactory which is a thread-safe object that is + instantiated once to serve the entire application. + + + + <interfacename>SessionFactory</interfacename> creates <classname>Session</classname> instances. + + The org.hibernate.SessionFactory acts as a factory for + org.hibernate.Session instances as can be seen in the + testBasicUsage method. - - + + + + <classname>Session</classname>s perform work. + + A org.hibernate.Session should be thought of as a corollary to a "unit of + work". + + + + Saving entities Session session = sessionFactory.openSession(); @@ -280,9 +291,9 @@ session.close(); - testBasicUsage first creates some new Event objects - and hands them over to Hibernate for "management" via the save method. At that - point, Hibernate takes responsibility to perform an INSERT on the database. + testBasicUsage first creates some new Event objects and + hands them over to Hibernate for management, using the save method. Hibernate now + takes responsibility to perform an INSERT on the database. @@ -298,19 +309,17 @@ session.close();]]> - testBasicUsage then illustrates use of the Hibernate Query Language (HQL) to - load all existing Event objects from the database. Hibernate will generate the - appropriate SELECT SQL, send it to the database and populate - Event objects with the result set data. + testBasicUsage illustrates use of the Hibernate Query Language + (HQL) to load all existing Event objects from the database and generate the + appropriate SELECT SQL, send it to the database and populate Event + objects with the result set data.
Take it further! - - Try the following exercises: - + Practice Exercises Reconfigure the examples to connect to your own persistent relational database. From 5d6317e71534beaecac0cea2c858fcd765a04146 Mon Sep 17 00:00:00 2001 From: mstanleyjones Date: Wed, 13 Oct 2010 13:35:50 +1000 Subject: [PATCH 2/4] Edit the Annotations tutorial. --- .../en-US/content/tutorial_annotations.xml | 100 +++++++++--------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml index 0cb001e683..be6e43a159 100644 --- a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml +++ b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml @@ -5,38 +5,40 @@ Tutorial Using Native Hibernate APIs and Annotation Mappings - This tutorial is located within the download bundle under basic and illustrates - - - - using annotations to provide mapping information - - - - - using the native Hibernate APIs - - - + This tutorial is located within the download bundle under basic. + + Objectives + + + Use annotations to provide mapping information + + + + + Use the native Hibernate APIs + + + +
The Hibernate configuration file - The contents are exactly the same as in . - The single difference is the mapping element at the very end naming the - annotated entity class using the class attribute. + The contents are identical to , with one important + difference. The mapping element at the very end naming the annotated entity class using + the attribute.
The annotated entity Java class - The entity class in this tutorial is org.hibernate.tutorial.annotations.Event - which is still following JavaBean conventions. In fact the class itself is exactly the same as we saw - in , the only difference being the use of - annotations to provide the metadata instead of a separate hbm.xml file. + 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 , except that annotations are used to provide the metadata, + rather than a separate hbm.xml file. @@ -49,17 +51,18 @@ public class Event { - The @javax.persistence.Entity annotation is used to mark a - class as an entity. It's function is essentially the same as the class - mapping element discussed in . - Additionally the @javax.persistence.Table annotation is - used to explicitly specify the table name (the default table name would have been - 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 . Additionally the + @javax.persistence.Table annotation explicitly specifies the table + name. Without this specification, the default table name would be EVENT). - Identifying the identifier property - @Id + Identifying the identifier property + @Id @GeneratedValue(generator="increment") @GenericGenerator(name="increment", strategy = "increment") public Long getId() { @@ -68,7 +71,7 @@ public Long getId() { - @javax.persistence.Id marks the property defining the + @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 @@ -76,8 +79,8 @@ public Long getId() { - Identifying basic properties - public String getTitle() { + Identifying basic properties + public String getTitle() { return title; } @@ -89,9 +92,8 @@ public Date getDate() { - Just as discussed in , the - date property needs special handling to account for its special naming - and its SQL type. + As in , the date property needs + special handling to account for its special naming and its SQL type.
@@ -106,23 +108,21 @@ public Date getDate() {
Take it further! - - Try the following exercises: - - - - With help of the Developer Guide, add an association to - the Event entity to model a message thread. - - - - - With help of the Developer Guide, add a callback to - receive notifications when an Event is created, updated or deleted. Try - the same with an event listener. - - + 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. + +
From e34e4641035eabbadbfeed15e7f11bd4a8481afe Mon Sep 17 00:00:00 2001 From: mstanleyjones Date: Wed, 13 Oct 2010 14:12:31 +1000 Subject: [PATCH 3/4] Edited the JPA chapter. --- .../docbook/en-US/content/tutorial_jpa.xml | 110 ++++++++++-------- 1 file changed, 63 insertions(+), 47 deletions(-) diff --git a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml index 1dd1c54645..4148c0175f 100644 --- a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml +++ b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml @@ -5,38 +5,38 @@ Tutorial Using the <firstterm><phrase>Java Persistence API (JPA)</phrase></firstterm> - This tutorial is located within the download bundle under entitymanager and illustrates - - - - using annotations to provide mapping information - - - - - using JPA - - - + This tutorial is located within the download bundle under entitymanager. + + Objectives + + + Use annotations to provide mapping information. + + + + + Use JPA. + + +
<filename>persistence.xml</filename> The previous tutorials used the Hibernate-specific - hibernate.cfg.xml configuration file. JPA, - however, defines a different bootstrap process that uses its own configuration file - named persistence.xml. How this bootstrapping works is defined - by the JPA specification. In Java SE environments the - persistence provider (Hibernate in this case) is required to locate all JPA - configuration files by classpath lookup of the META-INF/persistence.xml resource - name. + hibernate.cfg.xml configuration file. + JPA, however, defines a different bootstrap process that uses its own configuration + file named persistence.xml. This bootstrapping process is defined by the + JPA specification. In Java SE environments the persistence + provider (Hibernate in this case) is required to locate all JPA configuration files + by classpath lookup of the META-INF/persistence.xml resource name. - <filename>persistence.xml</filename> - persistence.xml + @@ -47,53 +47,52 @@ - persistence.xml files should provide a unique name for each - persistence unit. This name is how applications reference the configuration - while obtaining an javax.persistence.EntityManagerFactory reference. + persistence.xml files should provide a unique name for each persistence + unit. Applications use this name to reference the configuration when obtaining an + javax.persistence.EntityManagerFactory reference. - The settings defined in the properties element were already discussed in - . Here the javax.persistence-prefixed - varieties are used when possible. For the remaining Hibernate-specific configuration setting names notice - that they are now prefixed with hibernate.. + The settings defined in the properties element are discussed in . Here the javax.persistence-prefixed + varieties are used when possible. Notice that the remaining Hibernate-specific configuration setting names + are now prefixed with hibernate.. - Additionally, the class element functions the same as discussed in - . + Additionally, the class element functions the same as in .
The annotated entity Java class - The entity is exactly the same as that from the annotations tutorial. See - + The entity is exactly the same as in
Example code - The previous tutorials used the Hibernate APIs. This tutorial uses the JPA APIs. + The previous tutorials used the Hibernate APIs. This tutorial uses the JPA APIs. - Obtaining the <interfacename>javax.persistence.EntityManagerFactory</interfacename> - protected void setUp() throws Exception { + Obtaining the <interfacename>javax.persistence.EntityManagerFactory</interfacename> + protected void setUp() throws Exception { entityManagerFactory = Persistence.createEntityManagerFactory( "org.hibernate.tutorial.jpa" ); } - Notice again the use of org.hibernate.tutorial.jpa as the - persistence unit name, which matches from + Notice again that the persistence unit name is org.hibernate.tutorial.jpa, which matches + - Saving (persisting) entities - EntityManager entityManager = entityManagerFactory.createEntityManager(); + Saving (persisting) entities + EntityManager entityManager = entityManagerFactory.createEntityManager(); entityManager.getTransaction().begin(); entityManager.persist( new Event( "Our very first event!", new Date() ) ); entityManager.persist( new Event( "A follow up event", new Date() ) ); @@ -102,15 +101,15 @@ entityManager.close(); - The code is pretty similar to . Here - we use an javax.persistence.EntityManager as opposed to a - org.hibernate.Session. JPA calls this operation - persist instead of save. + The code is similar to . An + javax.persistence.EntityManager interface is used instead of a + org.hibernate.Session interface. JPA calls this + operation persist instead of save. - Obtaining a list of entities - Obtaining a list of entities + result = entityManager.createQuery( "from Event", Event.class ).getResultList(); for ( Event event : result ) { @@ -121,8 +120,25 @@ entityManager.close();]]> - Again, the code is pretty similar to . + Again, the code is pretty similar to .
+
+ Take it further! + + Practice Exercises + + + + + + + + + + + +
+ \ No newline at end of file From 70f53da5da607b00621bd2bd006b69c6568576fc Mon Sep 17 00:00:00 2001 From: mstanleyjones Date: Wed, 13 Oct 2010 14:27:28 +1000 Subject: [PATCH 4/4] Edited Envers chapter --- .../docbook/en-US/content/tutorial_envers.xml | 115 +++++++++++------- .../docbook/en-US/content/tutorial_jpa.xml | 17 +-- 2 files changed, 72 insertions(+), 60 deletions(-) diff --git a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_envers.xml b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_envers.xml index ee840940b7..6c7c6b3ead 100644 --- a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_envers.xml +++ b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_envers.xml @@ -5,50 +5,51 @@ Tutorial Using Envers - This tutorial is located within the download bundle under envers and illustrates - - - - configuring Envers - - - - - using the Envers APIs to look back through history - - - + This tutorial is located within the download bundle under envers. + + Objectives + + + Configure Envers. + + + + + Use the Envers APIs to view and analyze historical data. + + +
- <filename>persistence.xml</filename> - - This file was discussed in the JPA tutorial, and is largely the same here. The major - difference is the set of properties defining listeners. - Essentially this enables Envers to recieve notfications from Hibernate processing of certain - events such as an entity being saved or updated. - + <filename>persistence.xml</filename> + + This file was discussed in the JPA tutorial in , and is largely the same here. The major difference is the set + of properties defining listeners. Listeners enable Envers to receive notfications from + Hibernate processing about events such as saving or updating of entities. +
- The annotated entity Java class - - Again, the entity is largely the same as seen in the JPA tutorial. The major - difference to notice is the addition of the @org.hibernate.envers.Audited - annotation which tells Envers to automatically track changes to this entity. - + The annotated entity Java class + + Again, the entity is largely the same as in . The major + difference is the addition of the @org.hibernate.envers.Audited annotation, which + tells Envers to automatically track changes to this entity. +
- Example code - - Again, this tutorial makes use of the JPA APIs. However, the code also makes a - change to one of the entites and then uses the Envers API to pull back the initial revision (version) - as well as the updated revision. - - - Using the <interfacename>org.hibernate.envers.AuditReader</interfacename> - public void testBasicUsage() { + Example code + + Again, this tutorial makes use of the JPA APIs. However, the code also makes a change to one + of the entites, then uses the Envers API to pull back the initial revision as well as the updated + revision. A revision refers to a version of an entity. + + + Using the <interfacename>org.hibernate.envers.AuditReader</interfacename> + public void testBasicUsage() { ... AuditReader reader = AuditReaderFactory.get( entityManager ); Event firstRevision = reader.find( Event.class, 2L, 1 ); @@ -56,17 +57,41 @@ Event secondRevision = reader.find( Event.class, 2L, 2 ); ... } - - - First an org.hibernate.envers.AuditReader is obtained - from the org.hibernate.envers.AuditReaderFactory wrapping the + + + Description of Example + + + An org.hibernate.envers.AuditReader is obtained from the + org.hibernate.envers.AuditReaderFactory which wraps the javax.persistence.EntityManager. - - - Then the find method is used to retrieve specific revisions of the entity. The - first call reads "find revision number 1 of Event with id 2". The second call reads "find revision - number 2 of Event with id 2". - + + + + + Next,the find method retrieves specific revisions of the entity. The first call + reads find revision number 1 of Event with id 2. The second call reads find + revision number 2 of Event with id 2. + + + +
+ +
+ Take it further! + + Practice Exercises + + + + + + + + + + +
\ No newline at end of file diff --git a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml index 4148c0175f..ae1d08a958 100644 --- a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml +++ b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml @@ -127,18 +127,5 @@ entityManager.close();]]>
Take it further! - Practice Exercises - - - - - - - - - - - -
- - \ No newline at end of file + Practice Exercises +
\ No newline at end of file