From 1532e22327e528d85f80ed788ff947e3533f4071 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Fri, 27 Aug 2010 21:44:03 +0000 Subject: [PATCH] HHH-5441 - Create "Getting Started Guide" - separate tutorial project for bundling git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20277 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- .../en-US/Hibernate_Getting_Started_Guide.xml | 28 +- .../en-US/content/tutorial_annotations.xml | 186 +++---- .../docbook/en-US/content/tutorial_native.xml | 458 ++++++++---------- .../quickstart/tutorials/annotations/pom.xml | 47 ++ .../AnnotationsIllustrationTest.java | 77 +++ .../hibernate/tutorial/annotations/Event.java | 83 ++++ .../src/test/resources/hibernate.cfg.xml | 59 +++ .../quickstart/tutorials/basic/pom.xml | 47 ++ .../org/hibernate/tutorial/hbm/Event.hbm.xml | 41 ++ .../org/hibernate/tutorial/hbm/Event.java | 67 +++ .../hbm/NativeApiIllustrationTest.java | 77 +++ .../src/test/resources/hibernate.cfg.xml | 58 +++ .../tutorials/entitymanager/pom.xml | 54 +++ .../em/EntityManagerIllustrationTest.java | 72 +++ .../java/org/hibernate/tutorial/em/Event.java | 83 ++++ .../test/resources/META-INF/persistence.xml | 49 ++ documentation/quickstart/tutorials/pom.xml | 102 ++++ 17 files changed, 1213 insertions(+), 375 deletions(-) create mode 100644 documentation/quickstart/tutorials/annotations/pom.xml create mode 100644 documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/AnnotationsIllustrationTest.java create mode 100644 documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/Event.java create mode 100644 documentation/quickstart/tutorials/annotations/src/test/resources/hibernate.cfg.xml create mode 100644 documentation/quickstart/tutorials/basic/pom.xml create mode 100644 documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.hbm.xml create mode 100644 documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.java create mode 100644 documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/NativeApiIllustrationTest.java create mode 100644 documentation/quickstart/tutorials/basic/src/test/resources/hibernate.cfg.xml create mode 100644 documentation/quickstart/tutorials/entitymanager/pom.xml create mode 100644 documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java create mode 100644 documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/Event.java create mode 100644 documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml create mode 100644 documentation/quickstart/tutorials/pom.xml diff --git a/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml b/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml index ada0975451..42f639bfa0 100644 --- a/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml +++ b/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml @@ -8,9 +8,29 @@ - - + + Basic Information + + + The sections in Part I present basic information you will + likely need to get started utilizing Hibernate + + + + + + + + Tutorials + + + The sections in Part II dive into illustrative examples of using Hibernate in various + ways. The referenced projects and code are available for download at + + + + + + - - \ No newline at end of file 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 28e831d196..606d7d94a0 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 @@ -4,122 +4,84 @@ Tutorial Using Native Hibernate APIs and Annotation Mappings - - Steps + + This tutorial is located within the download bundle under basic and illustrates + + + + using annotations to provide mapping information + + + + + using the native Hibernate APIs + + + + - - Create the Maven POM file - - Create a file named pom.xml in the root of your project directory, containing - the text in . - - - <filename>pom.xml</filename> - - - +
+ The Hibernate configuration file - - Create the annotated entity Java class + + 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. + +
- - Create a file named src/main/java/org/hibernate/tutorial/annotations/Event.java, - containing the text in . - +
+ The annotated entity Java class + + The entity class in this tutorial is org.hibernate.tutorial.annotations.Event + + Notes About the Entity + + + The entity class is still using 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 @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). + + + + + @javax.persistence.Id marks the property defining 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. + + + + + Just as discussed in , the + date property needs special handling to account for its special naming + and its SQL type. + + + + +
- - <filename>Entity.java</filename> - - - - - Notes About the Entity - - - The entity class is still using 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 @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 we see in . - Additionally the @javax.persistence.Table annotation is - used to explicitly specify the table name (the default table name would have been - EVENT). - - - - - @javax.persistence.Id marks the property defining the - entity's identifier. - - - - - - Just as in , the - date property needs special handling to account for its special naming - and its SQL type. - - - - - - - - Create the Hibernate configuration file - - - Create a file named src/main/resources/hibernate.cfg.xml with the following contents: - - - - <filename>hibernate.cfg.xml</filename> - - - - - Most of 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. - - - - - Do stuff - - Create a file named src/main/java/org/hibernate/tutorial/annotations/EventManager.java - containing the text in . - - - - - <filename>EventManager.java</filename> - - - - - - Refer back to for a discussion - - - - - Compile and run the code - - - Follow the directions at and - to compile and then run the code. Be sure - to reference the org.hibernate.tutorial.annotations.EventManager class - instead of the org.hibernate.tutorial.hbm.EventManager class. - - - - +
+ Example code + + org.hibernate.tutorial.annotations.AnnotationsIllustrationTest is essentially the + same as org.hibernate.tutorial.hbm.NativeApiIllustrationTest discussed in + . + +
Take it further! 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 14de6e9e89..7f7f7de404 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 @@ -1,311 +1,251 @@ - - Tutorial Using Native Hibernate APIs and <filename>hbm.xml</filename> Mappings + + 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 + + + + + +
+ The Hibernate configuration file - - This tutorial uses the standard layout described in - . + The resource file hibernate.cfg.xml defines Hibernate configuration + information. - - - The tutorials in this guide use Maven, in order to leverage its transitive dependency management - capabilities and its integration with many development environments (IDEs). You can use another build - tool, adapting the examples to fit your needs. + The first few 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. + The 'connection.pool_size' is used to configure Hibernate's built-in connection pool how many + connections + to pool. - - - Steps - - - Create the Maven POM file + - Create a file named pom.xml in the root of your project directory, containing - the text in. + 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 + JDBC Connections in the + Database Access chapter of the + Hibernate Developer Guide for further information. - - - <filename>pom.xml</filename> - - - - + - - Create the entity Java class + + The dialect option specifies the particular SQL variant Hibernate should generate. + + - Create a file named src/main/java/org/hibernate/tutorial/hbm/Event.java, - containing the text in . + In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if + your application targets multiple databases. See the section + Database Dialects in the + Database Access chapter of the + Hibernate Developer Guide for further information. + - - - <filename>Entity.java</filename> - - - - - - - - - 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 hbm2ddl.auto option turns on automatic generation of database schemas directly + into the database. + - - Create the entity mapping file + + 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). + - - Create a file named src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml, - containing the text in . - +
- - - <filename>Event.hbm.xml</filename> - - - - - 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. - - - - Functions of the <literal>class</literal> element +
+ The entity Java class + + The entity class for this tutorial is org.hibernate.tutorial.hbm.Event. + + Notes About the Entity - 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. + 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 table attribute names the database table which contains the data for - this entity. + 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. - + + +
- - Instances of the Event class are now mapped to rows in the - EVENTS table. Hibernate uses the id element to - uniquely identify rows in the table. - - + +
+ The mapping file + + 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. + + + + Functions of the <literal>class</literal> element + - 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. + 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 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 sequence-like value generation is used. - - - 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 - word for the column name. - - - The title mapping also lacks a type 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 - 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 - 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). - - - + + - 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 - explicitly defining the type to use. + The table attribute names the database table which contains the data for + this entity. - - - - - Create the Hibernate configuration file + + + + Instances of the Event class are now mapped to rows in the + EVENTS table. Hibernate uses the id element to + uniquely identify rows in the table. + + - Create a file named src/main/resources/hibernate.cfg.xml containing the text in - . + 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. + + + 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 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 + word for the column name. + + + The title mapping also lacks a type 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 + 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 + 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). + - - <filename>hibernate.cfg.xml</filename> - - - + - The first few 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. - The 'connection.pool_size' is used to configure Hibernate's built-in connection pool how many - connections - to pool. + 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 + explicitly defining the type to use. + - - - 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 "JDBC Connections" in - the "Database Access" chapter of the "Hibernate Developer Guide" for further information. - - +
+
+ Example code + + The org.hibernate.tutorial.hbm.NativeApiIllustrationTest class illustrates using + the Hibernate native API. + + - The dialect option specifies the particular SQL variant Hibernate should generate. + 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. + - - - In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if - your application targets multiple databases. See the section "Database Dialects" in the - "Database Access" chapter of the "Hibernate Developer Guide" for further information. - - + + 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 hbm2ddl.auto option turns on automatic generation of database schemas directly - into the database. - - - Finally, add the mapping file(s) for persistent classes to the configuration. - - + + 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. + - - Do stuff - - Create a file named src/main/java/org/hibernate/tutorial/hbm/EventManager.java - containing the text in . - + + 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". + + - - - <filename>EventManager.java</filename> - - - + + 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. + - - The org.hibernate.cfg.Configuration class is the first thing to notice. In this - tutorial we simply configure everything 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 - createAndStoreEvent and listEvents methods of the - EventManager class. A org.hibernate.Session - should be thought of as a corollary to a "unit of work". - - - - createAndStoreEvent creates a new Event object - and hands it over to Hibernate for "management". At that point, Hibernate takes responsibility to - perform an INSERT on the database. - - - - listEvents 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. - - - - - Compile the source - - - - - Run the code - - To perform a store (leveraging the maven exec plugin): - mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.hbm.EventManager" -Dexec.args="store" - You should see Hibernate starting up and, depending on your configuration, lots of log output. Towards - the end, the following line will be displayed: - [java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?) - This is the INSERTexecuted by Hibernate. - - - - To perform a list: - mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.hbm.EventManager"-Dexec.args="list" - - - - - Currently nothing will ever be output when performing the list because the database is recreated - every time the org.hibernate.SessionFactory is created. - - - - + + 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. + +
Take it further! diff --git a/documentation/quickstart/tutorials/annotations/pom.xml b/documentation/quickstart/tutorials/annotations/pom.xml new file mode 100644 index 0000000000..5f8c7c2392 --- /dev/null +++ b/documentation/quickstart/tutorials/annotations/pom.xml @@ -0,0 +1,47 @@ + + + + + 4.0.0 + + + org.hibernate.tutorials + hibernate-tutorials + 3.6.0-SNAPSHOT + ../pom.xml + + + hibernate-tutorial-annotations + Hibernate Annotations Tutorial + Hibernate tutorial illustrating the use of native APIs and annotations for mapping metadata + + + + true + + + diff --git a/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/AnnotationsIllustrationTest.java b/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/AnnotationsIllustrationTest.java new file mode 100644 index 0000000000..674434d220 --- /dev/null +++ b/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/AnnotationsIllustrationTest.java @@ -0,0 +1,77 @@ +/* + * Hibernate, Relational Persistence for Idiomatic Java + * + * Copyright (c) 2010, Red Hat Inc. or third-party contributors as + * indicated by the @author tags or express copyright attribution + * statements applied by the authors. All third-party contributions are + * distributed under license by Red Hat Inc. + * + * This copyrighted material is made available to anyone wishing to use, modify, + * copy, or redistribute it subject to the terms and conditions of the GNU + * Lesser General Public License, as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + * for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this distribution; if not, write to: + * Free Software Foundation, Inc. + * 51 Franklin Street, Fifth Floor + * Boston, MA 02110-1301 USA + */ +package org.hibernate.tutorial.annotations; + +import java.util.Date; +import java.util.List; + +import junit.framework.TestCase; + +import org.hibernate.Session; +import org.hibernate.SessionFactory; +import org.hibernate.cfg.Configuration; + +/** + * TODO : javadoc + * + * @author Steve Ebersole + */ +public class AnnotationsIllustrationTest extends TestCase { + private SessionFactory sessionFactory; + + @Override + protected void setUp() throws Exception { + // A SessionFactory is set up once for an application + sessionFactory = new Configuration() + .configure() // configures settings from hibernate.cfg.xml + .buildSessionFactory(); + } + + @Override + protected void tearDown() throws Exception { + if ( sessionFactory != null ) { + sessionFactory.close(); + } + } + + public void testBasicUsage() { + // create a couple of events... + Session session = sessionFactory.openSession(); + session.beginTransaction(); + session.save( new Event( "Our very first event!", new Date() ) ); + session.save( new Event( "A follow up event", new Date() ) ); + session.getTransaction().commit(); + session.close(); + + // now lets pull events from the database and list them + session = sessionFactory.openSession(); + session.beginTransaction(); + List result = session.createQuery( "from Event" ).list(); + for ( Event event : (List) result ) { + System.out.println( "Event (" + event.getDate() + ") : " + event.getTitle() ); + } + session.getTransaction().commit(); + session.close(); + } +} diff --git a/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/Event.java b/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/Event.java new file mode 100644 index 0000000000..c66349f9eb --- /dev/null +++ b/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/Event.java @@ -0,0 +1,83 @@ +/* + * Hibernate, Relational Persistence for Idiomatic Java + * + * Copyright (c) 2010, Red Hat Inc. or third-party contributors as + * indicated by the @author tags or express copyright attribution + * statements applied by the authors. All third-party contributions are + * distributed under license by Red Hat Inc. + * + * This copyrighted material is made available to anyone wishing to use, modify, + * copy, or redistribute it subject to the terms and conditions of the GNU + * Lesser General Public License, as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + * for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this distribution; if not, write to: + * Free Software Foundation, Inc. + * 51 Franklin Street, Fifth Floor + * Boston, MA 02110-1301 USA + */ +package org.hibernate.tutorial.annotations; + +import java.util.Date; +import javax.persistence.Column; +import javax.persistence.Entity; +import javax.persistence.GeneratedValue; +import javax.persistence.Id; +import javax.persistence.Table; +import javax.persistence.Temporal; +import javax.persistence.TemporalType; + +import org.hibernate.annotations.GenericGenerator; + +@Entity +@Table( name = "EVENTS" ) +public class Event { + private Long id; + + private String title; + private Date date; + + public Event() { + // this form used by Hibernate + } + + public Event(String title, Date date) { + // for application use, to create new events + this.title = title; + this.date = date; + } + + @Id + @GeneratedValue(generator="increment") + @GenericGenerator(name="increment", strategy = "increment") + public Long getId() { + return id; + } + + private void setId(Long id) { + this.id = id; + } + + @Temporal(TemporalType.TIMESTAMP) + @Column(name = "EVENT_DATE") + public Date getDate() { + return date; + } + + public void setDate(Date date) { + this.date = date; + } + + public String getTitle() { + return title; + } + + public void setTitle(String title) { + this.title = title; + } +} \ No newline at end of file diff --git a/documentation/quickstart/tutorials/annotations/src/test/resources/hibernate.cfg.xml b/documentation/quickstart/tutorials/annotations/src/test/resources/hibernate.cfg.xml new file mode 100644 index 0000000000..ac4c8c489d --- /dev/null +++ b/documentation/quickstart/tutorials/annotations/src/test/resources/hibernate.cfg.xml @@ -0,0 +1,59 @@ + + + + + + + + + + org.h2.Driver + jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE + sa + + + + 1 + + + org.hibernate.dialect.H2Dialect + + + org.hibernate.cache.NoCacheProvider + + + true + + + update + + + + + + + \ No newline at end of file diff --git a/documentation/quickstart/tutorials/basic/pom.xml b/documentation/quickstart/tutorials/basic/pom.xml new file mode 100644 index 0000000000..b727676689 --- /dev/null +++ b/documentation/quickstart/tutorials/basic/pom.xml @@ -0,0 +1,47 @@ + + + + + 4.0.0 + + + org.hibernate.tutorials + hibernate-tutorials + 3.6.0-SNAPSHOT + ../pom.xml + + + hibernate-tutorial-hbm + Hibernate hbm.xml Tutorial + Hibernate tutorial illustrating the use of native APIs and hbm.xml for mapping metadata + + + + true + + + diff --git a/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.hbm.xml b/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.hbm.xml new file mode 100644 index 0000000000..2b3de75e2d --- /dev/null +++ b/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.hbm.xml @@ -0,0 +1,41 @@ + + + + + + + + + + + + + + + + + diff --git a/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.java b/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.java new file mode 100644 index 0000000000..ae4c2dfd84 --- /dev/null +++ b/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.java @@ -0,0 +1,67 @@ +/* + * Hibernate, Relational Persistence for Idiomatic Java + * + * Copyright (c) 2010, Red Hat Inc. or third-party contributors as + * indicated by the @author tags or express copyright attribution + * statements applied by the authors. All third-party contributions are + * distributed under license by Red Hat Inc. + * + * This copyrighted material is made available to anyone wishing to use, modify, + * copy, or redistribute it subject to the terms and conditions of the GNU + * Lesser General Public License, as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + * for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this distribution; if not, write to: + * Free Software Foundation, Inc. + * 51 Franklin Street, Fifth Floor + * Boston, MA 02110-1301 USA + */ +package org.hibernate.tutorial.hbm; + +import java.util.Date; + +public class Event { + private Long id; + + private String title; + private Date date; + + public Event() { + // this form used by Hibernate + } + + public Event(String title, Date date) { + // for application use, to create new events + this.title = title; + this.date = date; + } + + public Long getId() { + return id; + } + + private void setId(Long id) { + this.id = id; + } + + public Date getDate() { + return date; + } + + public void setDate(Date date) { + this.date = date; + } + + public String getTitle() { + return title; + } + + public void setTitle(String title) { + this.title = title; + } +} \ No newline at end of file diff --git a/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/NativeApiIllustrationTest.java b/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/NativeApiIllustrationTest.java new file mode 100644 index 0000000000..9ea1cbf57b --- /dev/null +++ b/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/NativeApiIllustrationTest.java @@ -0,0 +1,77 @@ +/* + * Hibernate, Relational Persistence for Idiomatic Java + * + * Copyright (c) 2010, Red Hat Inc. or third-party contributors as + * indicated by the @author tags or express copyright attribution + * statements applied by the authors. All third-party contributions are + * distributed under license by Red Hat Inc. + * + * This copyrighted material is made available to anyone wishing to use, modify, + * copy, or redistribute it subject to the terms and conditions of the GNU + * Lesser General Public License, as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + * for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this distribution; if not, write to: + * Free Software Foundation, Inc. + * 51 Franklin Street, Fifth Floor + * Boston, MA 02110-1301 USA + */ +package org.hibernate.tutorial.hbm; + +import java.util.Date; +import java.util.List; + +import junit.framework.TestCase; + +import org.hibernate.Session; +import org.hibernate.SessionFactory; +import org.hibernate.cfg.Configuration; + +/** + * TODO : javadoc + * + * @author Steve Ebersole + */ +public class NativeApiIllustrationTest extends TestCase { + private SessionFactory sessionFactory; + + @Override + protected void setUp() throws Exception { + // A SessionFactory is set up once for an application + sessionFactory = new Configuration() + .configure() // configures settings from hibernate.cfg.xml + .buildSessionFactory(); + } + + @Override + protected void tearDown() throws Exception { + if ( sessionFactory != null ) { + sessionFactory.close(); + } + } + + public void testBasicUsage() { + // create a couple of events... + Session session = sessionFactory.openSession(); + session.beginTransaction(); + session.save( new Event( "Our very first event!", new Date() ) ); + session.save( new Event( "A follow up event", new Date() ) ); + session.getTransaction().commit(); + session.close(); + + // now lets pull events from the database and list them + session = sessionFactory.openSession(); + session.beginTransaction(); + List result = session.createQuery( "from Event" ).list(); + for ( Event event : (List) result ) { + System.out.println( "Event (" + event.getDate() + ") : " + event.getTitle() ); + } + session.getTransaction().commit(); + session.close(); + } +} diff --git a/documentation/quickstart/tutorials/basic/src/test/resources/hibernate.cfg.xml b/documentation/quickstart/tutorials/basic/src/test/resources/hibernate.cfg.xml new file mode 100644 index 0000000000..17e90c894b --- /dev/null +++ b/documentation/quickstart/tutorials/basic/src/test/resources/hibernate.cfg.xml @@ -0,0 +1,58 @@ + + + + + + + + + + org.h2.Driver + jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE + sa + + + + 1 + + + org.hibernate.dialect.H2Dialect + + + org.hibernate.cache.NoCacheProvider + + + true + + + update + + + + + + \ No newline at end of file diff --git a/documentation/quickstart/tutorials/entitymanager/pom.xml b/documentation/quickstart/tutorials/entitymanager/pom.xml new file mode 100644 index 0000000000..3cd157cb84 --- /dev/null +++ b/documentation/quickstart/tutorials/entitymanager/pom.xml @@ -0,0 +1,54 @@ + + + + + 4.0.0 + + + hibernate-tutorials + org.hibernate.tutorials + 3.6.0-SNAPSHOT + + + hibernate-tutorial-entitymanager + Hibernate JPA Tutorial + Hibernate tutorial illustrating the use of JPA APIs and annotations for mapping metadata + + + + true + + + + + org.hibernate + hibernate-entitymanager + ${project.version} + + + + \ No newline at end of file diff --git a/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java b/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java new file mode 100644 index 0000000000..c55eb0f9d6 --- /dev/null +++ b/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java @@ -0,0 +1,72 @@ +/* + * Hibernate, Relational Persistence for Idiomatic Java + * + * Copyright (c) 2010, Red Hat Inc. or third-party contributors as + * indicated by the @author tags or express copyright attribution + * statements applied by the authors. All third-party contributions are + * distributed under license by Red Hat Inc. + * + * This copyrighted material is made available to anyone wishing to use, modify, + * copy, or redistribute it subject to the terms and conditions of the GNU + * Lesser General Public License, as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + * for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this distribution; if not, write to: + * Free Software Foundation, Inc. + * 51 Franklin Street, Fifth Floor + * Boston, MA 02110-1301 USA + */ +package org.hibernate.tutorial.em; + +import java.util.Date; +import java.util.List; +import javax.persistence.EntityManager; +import javax.persistence.EntityManagerFactory; +import javax.persistence.Persistence; + +import junit.framework.TestCase; + +/** + * TODO : javadoc + * + * @author Steve Ebersole + */ +public class EntityManagerIllustrationTest extends TestCase { + private EntityManagerFactory entityManagerFactory; + + @Override + protected void setUp() throws Exception { + // like discussed with regards to SessionFactory, an EntityManagerFactory is set up once for an application + entityManagerFactory = Persistence.createEntityManagerFactory( "hibernate-jpa-tutorial" ); + } + + @Override + protected void tearDown() throws Exception { + entityManagerFactory.close(); + } + + public void testBasicUsage() { + // create a couple of events... + 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() ) ); + entityManager.getTransaction().commit(); + entityManager.close(); + + // now lets pull events from the database and list them + entityManager = entityManagerFactory.createEntityManager(); + entityManager.getTransaction().begin(); + List result = entityManager.createQuery( "from Event", Event.class ).getResultList(); + for ( Event event : result ) { + System.out.println( "Event (" + event.getDate() + ") : " + event.getTitle() ); + } + entityManager.getTransaction().commit(); + entityManager.close(); + } +} diff --git a/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/Event.java b/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/Event.java new file mode 100644 index 0000000000..90fe4144f3 --- /dev/null +++ b/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/Event.java @@ -0,0 +1,83 @@ +/* + * Hibernate, Relational Persistence for Idiomatic Java + * + * Copyright (c) 2010, Red Hat Inc. or third-party contributors as + * indicated by the @author tags or express copyright attribution + * statements applied by the authors. All third-party contributions are + * distributed under license by Red Hat Inc. + * + * This copyrighted material is made available to anyone wishing to use, modify, + * copy, or redistribute it subject to the terms and conditions of the GNU + * Lesser General Public License, as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + * for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this distribution; if not, write to: + * Free Software Foundation, Inc. + * 51 Franklin Street, Fifth Floor + * Boston, MA 02110-1301 USA + */ +package org.hibernate.tutorial.em; + +import java.util.Date; +import javax.persistence.Column; +import javax.persistence.Entity; +import javax.persistence.GeneratedValue; +import javax.persistence.Id; +import javax.persistence.Table; +import javax.persistence.Temporal; +import javax.persistence.TemporalType; + +import org.hibernate.annotations.GenericGenerator; + +@Entity +@Table( name = "EVENTS" ) +public class Event { + private Long id; + + private String title; + private Date date; + + public Event() { + // this form used by Hibernate + } + + public Event(String title, Date date) { + // for application use, to create new events + this.title = title; + this.date = date; + } + + @Id + @GeneratedValue(generator="increment") + @GenericGenerator(name="increment", strategy = "increment") + public Long getId() { + return id; + } + + private void setId(Long id) { + this.id = id; + } + + @Temporal(TemporalType.TIMESTAMP) + @Column(name = "EVENT_DATE") + public Date getDate() { + return date; + } + + public void setDate(Date date) { + this.date = date; + } + + public String getTitle() { + return title; + } + + public void setTitle(String title) { + this.title = title; + } +} \ No newline at end of file diff --git a/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml b/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml new file mode 100644 index 0000000000..fe0d665d84 --- /dev/null +++ b/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml @@ -0,0 +1,49 @@ + + + + + + Persistence unit for the JPA tutorial of the Hibernate Getting Started Guide + + + org.hibernate.tutorial.em.Event + + + + + + + + + + + + + + + diff --git a/documentation/quickstart/tutorials/pom.xml b/documentation/quickstart/tutorials/pom.xml new file mode 100644 index 0000000000..aece17af93 --- /dev/null +++ b/documentation/quickstart/tutorials/pom.xml @@ -0,0 +1,102 @@ + + + + + 4.0.0 + + org.hibernate.tutorials + hibernate-tutorials + 3.6.0-SNAPSHOT + pom + + Hibernate Getting Started Guide Tutorials + Aggregator for the Hibernate tutorials presented in the Getting Started Guide + + + + true + + + + basic + annotations + entitymanager + + + + + org.hibernate + hibernate-core + ${project.version} + + + + + org.slf4j + slf4j-simple + 1.6.1 + + + + + javassist + javassist + 3.12.0.GA + + + + + junit + junit + 4.8.1 + + + + + com.h2database + h2 + 1.2.140 + + + + + + + false + src/main/java + + **/*.xml + + + + true + src/test/resources + + + + +