Table of Contents - Fast Track to Hibernate 3

Transcription

1 Table of Contents - Fast Track to Hibernate 3 Fast Track to Hibernate 1 Workshop Overview and Objectives 2 Workshop Agenda 3 Release Level 4 Typographic Conventions 5 Labs 6 Session 1: Introduction to Hibernate 7 Lesson Objectives 8 Hibernate Overview 9 The Issues with Persistence Layers 10 Object-Relational Mapping (ORM) Issues 11 Issues with JDBC Alone 12 Hibernate Overview 13 Hibernate Benefits 14 Hibernate Environments 15 Hibernate Architecture 16 More Detailed Architecture 17 More Detailed Architecture 18 Using Hibernate 19 Acquiring Hibernate 20 Using Hibernate 21 Configuring Hibernate 22 Sample hibernate.cfg.xml 23 hibernate.cfg.xml Elements 24 SessionFactory Configuration 25 SessionFactory Configuration Properties 26 Example Properties for PostgresSQL 27 The Configuration Class 28 The SessionFactory Interface 29 SessionFactory API 30 The Session Interface 31 Sessions and Transactions 32 A Basic Hibernate Program Example 33 Lab 1.1 Setting up Hibernate 34 Mapping a Simple Class 63 Persistent Entity Classes 64 Persistent Classes 65 An Example Persistent Class 66 The Event Class 67 The id Property 68 The Hibernate Mapping File 69 The <hibernate-mapping> Element 70 The <class> Element 71 The EVENTS Table 72 Mapping the id Property with <id> 73 More About Primary Keys 74 Generating the id Value 75 Mapping Properties with <property> 76 Hibernate Mapping Types 77 Copyright , LearningPatterns Inc. All rights reserved i

2 Common Hibernate Type Mappings 78 Field Access or Property Access 79 The Mapping File 80 Hibernate Sessions 81 The Session Interface 82 Retrieving Persistent Objects 83 Lab 1.2 Creating a Mapping File 84 Logging 94 hibernate.show_sql 95 Simple Logging Facade for Java - SLF4J 96 Apache Log4J 97 Hibernate log4j.properties file 98 The log4j.properties file 99 Modifying log4j.properties for Hibernate 100 Hibernate Logging Categories 101 Lab 1.3 Controlling Hibernate Logging 102 Review Questions 108 Lesson Summary 109 Lesson Summary 110 Appendix - log4j 111 Apache log4j 112 log4j Loggers 113 Logger Hierarchy 114 Logger Levels 115 Appenders 116 Appender Additivity 117 Additivity Example 118 Layout 119 log4j Configuration File 120 Sample log4j.properties Configuration File 121 Sample of Creating Output from Logger 122 PatternLayout 123 Multiple Layouts 124 Some log4j Appenders 125 Session 2: Updates and Queries 126 Lesson Objectives 127 Inserting and Updating 128 Inserting Instances 129 Inserting Instance Example 130 Modifying a Persistent Instance 131 Deleting an Instance 132 Lab 2.1 Inserting and Modifying 133 Hibernate Query Language 138 HQL Basics 139 Executing a Query 140 Executing a Query 141 Executing a Query 142 Other Common Query Methods 143 Where Clause / Restriction 144 HQL Operators and Expressions 145 Query Parameters 146 Using Query Parameters 147 Named Queries 148 Copyright , LearningPatterns Inc. All rights reserved ii

3 Projection Queries 149 Projection Queries Returning Tuples 150 Additional Query Capabilities 151 Aggregate Functions 152 Lab 2.2 Basic Querying 153 Review Questions 158 Lesson Summary 159 Lesson Summary 160 Session 3: Lifecycle 161 Lesson Objectives 162 Transaction Definition 163 Transaction Overview 164 Transaction Overview 165 Transaction Lifecycle 166 Transactions Modularize Systems 167 Transactions Clarify Systems 168 Hibernate and Transactions 169 Hibernate and Transactions 170 Hibernate Transaction Demarcation 171 Working With Transactions 172 The Hibernate Transaction API 173 Working in a Managed Environment 174 Working in a Managed Environment 175 The Persistence Lifecycle 176 The Persistence Lifecycle 177 Hibernate Object States 178 Transient and Persistent State 179 Detached and Removed State 180 Hibernate Object States and Transitions 181 The Persistence Context 182 Session / Persistence Context Lifespan 183 Session-per-request 184 Session Propagation 185 First Acquiring a SessionFactory Instance 186 Contextual Session 187 Using Contextual Sessions 188 What is the "Current" Context 189 Contextual Session Scope 190 The Persistence Context as Cache 191 Synchronization To the Database 192 Flushing the session 193 Flushing the Session 194 Persistence Context and Object Identity 195 Yes, It's Complicated 196 Lab 3.1 Using Contextual Sessions 197 Versioning and Optimistic Locking 202 Detached Objects and Optimistic Locking 203 Using a Detached Instance 204 Using a Detached Instance Example 205 Optimistic Locking and Versioning 206 Version Property in Java Class 207 Version Element in Mapping File 208 Automatic Version Maintenance 209 Copyright , LearningPatterns Inc. All rights reserved iii

4 Optimistic Locking Example 210 Updating a Detached Instance 211 Session.saveOrUpdate() 212 The unsaved-value Attribute 213 The unsaved-value Attribute 214 Locking Objects 215 Lock Modes 216 Using Session.lock() Example 217 Lab 3.2 Versioning 218 Review Questions 221 Lesson Summary 222 Session 4: Relationships 225 Lesson Objectives 226 Relationships Overview 227 Object Relationships 228 Characteristics of Relationships 229 Directionality 230 Directionality 231 Characteristics of Relationships 232 Collections of Value Objects 233 Collections of Values 234 Modeling a Set of Values 235 Mapping the Set of Values 236 Using a Set of Values 237 More on the Java Collection Type 238 Using the Java Collection Types 239 Modeling a List of Values 240 Mapping a List of Values 241 Sorted and Ordered Collections 242 Collections of Components 243 Mapping Collections of Components 244 Lab 4.1 Mapping a Value Set 245 Mapping Entity Relationships 249 Mappings Overview 250 Unidirectional Many-To-One Relationship 251 The Table Structure Many-To-One 252 Mapping the Relationship 253 Using the Relationship 254 Bidirectional One-To-Many Relationship 255 Defining the One-To-Many Relationship 256 Mapping the One-To-Many Relationship 257 More on the Inverse Side 258 Cascading Operations 259 Transitive Persistence 260 The cascade Attribute 261 Cascade Choices 262 Choosing Cascade Options 263 Lab 4.2 Relationships 264 Bidirectional One-To-One Relationship 273 Bidirectional One-To-One Relationship 274 Mapping a One-To-One Relationship 275 Many-To-Many Relationship 276 Defining Many-To-Many Relationship 277 Copyright , LearningPatterns Inc. All rights reserved iv

5 Mapping Many-To-Many Relationship 278 Mapping Many-To-Many Relationship 279 Lazy and Eager Loading 280 Queries Across Relationships 281 OUTER and FETCH JOIN 282 FETCH JOIN Example 283 Lab 4.3 Working With Relationships 284 Mapping Inheritance 289 Inheritance 290 Entity Inheritance 291 Details of Entity Inheritance 292 Single-Table Strategy 293 Class Definitions for Single-Table 294 Mapping for Single-Table 295 Sample Table Entries 296 Single-Table: Pros and Cons 297 Table per Subclass (Joined Subclass) 298 Mapping for Table per Subclass 299 Sample Table Entries 300 Joined: Pros and Cons 301 Table per Concrete Class 302 Lab 4.4 Working With Inheritance 303 Review Questions 308 Review Questions 309 Lesson Summary 310 Lesson Summary 311 Lesson Summary 312 Session 5: Additional Querying Capabilities 313 Lesson Objectives 314 More on Querying 315 Projection Queries 316 Aggregate Queries 317 Aggregate Query Examples 318 Bulk Update and Delete 319 Executing Bulk Operations 320 Native SQL Queries 321 Refining SQL Queries 322 Retrieving Entities with SQL Queries 323 Filters 324 Hibernate Filters 325 Defining and Attaching Filters 326 Using a Filter 327 Mapping a Filter to a Set 328 Collection Filters 329 Lab 5.1 Filters 330 Criteria 333 Criteria Overview 334 A Simple Criteria Example 335 Restrictions - Narrowing the Result Set 336 Restrictions Methods 337 Restrictions Example 338 Navigating Associations 339 Navigating Associations 340 Copyright , LearningPatterns Inc. All rights reserved v

6 Eager Fetching 341 Query By Example 342 Refining the Example 343 Additional Capabilities 344 Lab 5.2 Criteria Queries 345 Review Questions 348 Lesson Summary 349 Session 6: Hibernate and the Java Persistence API (JPA) 351 Lesson Objectives 352 JPA Overview 353 Java Persistence API Overview 354 Java Persistence Environments 355 Hibernate and JPA 356 Mapping a Simple Class 357 Entity Classes 358 Event Entity Mapped with JPA 359 The Entity Declaration 360 The Event Class 361 The Id Property 362 Mapping Properties 363 Basic Mapping Types 364 Lab 6.1 Mapping an Entity Class with JPA 365 Entity Manager and Persistence Context 369 The Entity Manager & Persistence Context 370 Persistence Unit 371 persistence.xml 372 persistence.xml Example 373 Acquiring an EntityManager 374 Working With Transactions 375 Retrieving Persistent Objects 376 Lab 6.2 Using an Entity Class 377 Inserts and Queries 380 Persisting a New Entity 381 Java Persistence Query Language 382 Executing a Query 383 Executing a Query 384 WHERE Clause and Query Parameters 385 Named Queries 386 Named Queries 387 Version Property in Java Class 388 Versioned Class and Detached Objects 389 Relationships 390 JPA Support for Relationships 391 Mapping the Many-To-One Relationship 392 Mapping the One-To-Many Relationship 393 Loading and Cascading 394 Queries Across Relationships 395 Inheritance 396 Entity Definitions for Single-Table 397 Entity Definitions for Joined 398 Lesson Summary 399 Copyright , LearningPatterns Inc. All rights reserved vi

7 Session 7: Advanced Topics 400 Lesson Objectives 401 Components and Multi-Table Mapping 402 Component Overview 403 Component Example 404 Mapping a Component 405 Multi-Table Mapping 406 Multi Table Mapping 407 equals() and hashcode() 408 Defining equals() and hashcode() 409 Redefining equals() 410 Example of equals() and hashcode() 411 Caching 412 Second-Level Cache 413 Data Appropriate for Caching 414 Cache Providers 415 Configuring Caching 416 Cache Configuration Example 417 Concurrency Strategies 418 Managing the Caches 419 Design Considerations 420 Overview Long Conversations Session-Per-Conversation (Extended Session) 423 Session-Per-Conversation Problems with Web Applications Open Session In View Pattern 426 Open Session In View Example Query Efficiency Techniques Beware of n+1 Select Issue 429 Prefetching Data in Batches 430 Data Access Object (DAO) 431 Hibernate Toolset 432 Hibernate Tools Overview 433 Important Note on Versions 434 Optional - Hibernate Tools 435 Install Hibernate Tools 436 Hibernate Console Configuration 437 Hibernate Console Perspective 438 Hibernate Configuration View 439 Class Diagram 440 HQL Editor 441 Query Results 442 Properties View 443 SQL Preview 444 Other Capabilities 445 Recap and Resources 446 Recap 447 What's Next 448 Some Useful Resources 449 Copyright , LearningPatterns Inc. All rights reserved vii

8 Copyright , LearningPatterns Inc. All rights reserved viii

9 Preface Fast Track to Hibernate 3 The Java Developer Education Series LearningPatterns Inc. Copyright LearningPatterns Inc. All rights reserved. 1

10 Preface Workshop Overview and Objectives This is an in-depth course covering the use of Hibernate to access data in relational databases using Java At completion you should be able to write, deploy, and test Hibernate applications, and you will: Understand the architecture of Hibernate Be able to create applications that use Hibernate to map persistent Java objects to a relational database Use Hibernate versioning and optimistic locking Map collections and associations using Hibernate Model inheritance with Hibernate Create and execute Hibernate queries Be familiar with Hibernate annotations, and know the relationship between Hibernate and the Java Persistence API Be familiar with Hibernate design principals Copyright LearningPatterns Inc. All rights reserved. 2

11 Preface Workshop Agenda Session 1: Introduction to Hibernate Session 2: Updates and Queries Session 3: Lifecycle Session 4: Relationships Session 5: Additional Querying Capabilities Session 6: Hibernate and Java Persistence API / EJB3 Session 7: Additional Topics Copyright LearningPatterns Inc. All rights reserved. 3

12 Preface Release Level This course contains instructions for running the Hibernate labs using the following platforms Hibernate 3.6 (should work with 3.5 with little difference, and with 3.3 with minor differences *) Derby Database (Open Source DB from Apache) Java 5+ Eclipse Java EE Edition (Should work with most recent Eclipse versions) All labs have been tested on Windows XP Instructions are based on the Windows operating system If you are using Unix, you will need to adjust accordingly If you are using Hibernate 3.5, the only difference from Hibernate 3.6 might be in the labs regarding the slf4j / log4j implementation jar This is given to you in the workspace\common\lib directory, and for 3.6, is named slf4j-log4j jar For Hibernate 3.5, you might need to get a different version of this jar file For Hibernate versions earlier than 3.5, the labs should still work (though you'll might still need the proper slf4j-log4j jar) There might be some differences in the jar files that you need If you get NoClassDefFound exceptions, you'll need to work to fix that Copyright LearningPatterns Inc. All rights reserved. 4

13 Preface Typographic Conventions Code that is inline in the text will appear in a fixed-width code font, such at this: JavaTeacher teacher = new JavaTeacher() Any class names, such as JavaTeacher, method names, or other code fragments will also appear in the same font If we want to emphasize a particular piece of code, we'll also bold it (and in the slide, change it's color) such as HttpServlet Filenames will be in italics, such as SearchServlet.java We sometimes denote more info in the notes with a star * Lastly, longer code examples will appear in a separate code box as shown below package com.javatunes.teach; public class JavaInstructor implements Teacher { public void teach() { System.out.println("Hibernate is way cool"); } } Copyright LearningPatterns Inc. All rights reserved. 5

14 Preface Labs Lab The workshop consists of approximately 50% discussion, 50% hands-on lab exercises, including a series of brief labs Many of the labs follow a common fictional case study - JavaTunes, an online music store The labs are contained directly in the course book, and have detailed instructions on what needs to be done The course includes setup zip files that contain skeleton code for the labs Students just need to add code for the particular capabilities that they are working with There is also a solution zip file that contains completed lab code Lab slides contain an icon like the one in the upper right corner of this slide The end of each lab is clearly marked with a stop like this one to the right STOP Copyright LearningPatterns Inc. All rights reserved. 6

15 Session 1: Introduction to Hibernate Session 1: Introduction to Hibernate Hibernate Overview Using Hibernate Mapping a Simple Class Logging Copyright LearningPatterns Inc. All rights reserved. 7

16 Session 1: Introduction to Hibernate Lesson Objectives Describe the issues of object-relational mapping Describe the overall goals of Hibernate Describe the Hibernate architecture Create a simple Hibernate application Map a simple class to a DB using Hibernate Copyright LearningPatterns Inc. All rights reserved. 8

17 Session 1: Introduction to Hibernate Hibernate Overview Hibernate Overview Using Hibernate Mapping a Simple Class Logging Copyright LearningPatterns Inc. All rights reserved. 9

18 Session 1: Introduction to Hibernate The Issues with Persistence Layers Data is a core element of many applications Data is often stored in relational databases A great deal of effort is expended writing persistence layers to store and retrieve data from the database These layers are complicated to write Often the "homegrown" persistence layer is buggy and incomplete Changes to the database schema are often expensive to propagate to the persistence layer When using an OO language, like Java, the situation is made more complicated Persistence Layers have many complex requirements including: Support of different databases, and potentially non-relational databases Full encapsulation of the underlying persistence mechanism Coordination between multiple persistent objects Support for transactions, and encapsulation of the underlying transaction mechanism Lazy loading for associations Support for multiple simultaneous database connections Support for using SQL queries when needed Copyright LearningPatterns Inc. All rights reserved. 10

19 Session 1: Introduction to Hibernate Object-Relational Mapping (ORM) Issues When using an OO language with a relational database, you are working with different models of using data OO: Interacting objects traversed via relationships Relational: Tables that are joined via foreign key relationships These are very different models Translating from one to the other requires work There are many issues to deal with Example, Inheritance: A core feature of OO models Not supported in relational model Relational Associations: only foreign key relationships Object model: 1-1, 1-N, N-N OO programming is base on software engineering concepts Relational databases are based on mathematical principles The two models are different Going back and forth between the two takes some work, a good understanding of the structure of each, and enough experience to make good choices in choosing how to do the mapping Copyright LearningPatterns Inc. All rights reserved. 11

20 Session 1: Introduction to Hibernate Issues with JDBC Alone You don't store/load objects to the database Everything has to be done with SQL For example, to persist an object of some class You need to write SQL statements to do this To load an object from the database You get result rows from the database, which must be converted into objects Copyright LearningPatterns Inc. All rights reserved. 12

21 Session 1: Introduction to Hibernate Hibernate Overview Open Source, ORM framework for Java Overall goals Relieve the developer from 95% of common data persistence related programming tasks Provide ORM capability for using a Java OO domain model to manage a relational database Provide a light-weight POJO based framework for Java persistence, including inheritance and polymorphism Provide a query language that helps remove or encapsulate vendor specific SQL code Help with translation of result-set tables to object graph Hibernate is an object/relational mapping tool for Java environments. The term object/relational mapping (ORM) refers to the technique of mapping a data representation from an object model to a relational data model with a SQL-based schema. 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 and can significantly reduce development time otherwise spent with manual data handling in SQL and JDBC. Hibernates goal is to relieve the developer from 95 percent of common data persistence related programming tasks. 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 representation to a graph of objects. [Hibernate Reference Documentation, Preface] Copyright LearningPatterns Inc. All rights reserved. 13

22 Session 1: Introduction to Hibernate Hibernate Benefits Simplicity and flexibility POJO based! ORM is completely metadata driven (annotations or XML) No need to write JDBC code Common defaults that allow metadata to be minimized Persistence API is totally separate from entity classes Can be used in Java SE environments (without app server) Completeness Supports full range of OO features Inheritance, custom object types, collections, associations Powerful query language Performance Minimizes number of database updates Lazy load on collections, disabling retrieval of associated objects Object caching Copyright LearningPatterns Inc. All rights reserved. 14

23 Session 1: Introduction to Hibernate Hibernate Environments Can be used in Java SE or Java EE programs It is packaged as a set of jar files Only minor configuration and programming differences between using it in a Java SE and Java EE environment The Java Persistence API (JPA) derived a lot of it's structure from Hibernate JPA is a required part of Java EE 5, and uses annotations to specify mapping metadata about persistent classes Hibernate supports the standard JPA annotations, in addition to defining additional ones of its own Using the JPA annotations with Hibernate gives a smooth migration path to standard Java Persistence Copyright LearningPatterns Inc. All rights reserved. 15

24 Session 1: Introduction to Hibernate Hibernate Architecture Very high-level view Hibernate uses database and configuration data to provide persistence services and objects to the application Many ways to architect this we'll show two common ways Copyright LearningPatterns Inc. All rights reserved. 16

25 Session 1: Introduction to Hibernate More Detailed Architecture In this scenario, the application manages some details itself Application manages JDBC connections and transactions Uses minimal subset of Hibernate API This can be considered Hibernate "Lite" Copyright LearningPatterns Inc. All rights reserved. 17

26 Session 1: Introduction to Hibernate More Detailed Architecture In this scenario, the app is abstracted away from JDBC/JTA Hibernate takes care of these details The application only interacts with the Hibernate API We'll shortly take a look at the different types that are used to write a Hibernate application that are picture in this diagram Copyright LearningPatterns Inc. All rights reserved. 18

27 Session 1: Introduction to Hibernate Using Hibernate Hibernate Overview Using Hibernate Mapping a Simple Class Logging Copyright LearningPatterns Inc. All rights reserved. 19

28 Session 1: Introduction to Hibernate Acquiring Hibernate Hibernate is an open source project It can be freely downloaded from Can get binary or source distributions Can also view and download documentation (included in binary) Hibernate Tools, a plugin for Eclipse is available at and includes: Mapping editor to create/manage Hibernate mapping files Console that allows you to configure DB connections, visualize classes and their relations, and execute queries interactively Reverse engineering tools that can generate domain model classes and Hibernate mapping files Wizards for creating various Hibernate artifacts ant task allowing you to run Hibernate tasks as part of your build Copyright LearningPatterns Inc. All rights reserved. 20

29 Session 1: Introduction to Hibernate Using Hibernate The Hibernate binary is a set of jar files The main Hibernate jar, (hibernate3.jar for Hibernate 3 releases), is included in the root of the hibernate distribution A set of supporting jar files, is included in the lib directory of the distribution Not all the supporting jar files are always needed to run hibernate There is a readme.txt file that tells what each jar is for and when it's needed In the labs, we give you instructions for configuring the full set of jar files you'll need to run Hibernate Copyright LearningPatterns Inc. All rights reserved. 21

30 Session 1: Introduction to Hibernate Configuring Hibernate Hibernate needs to be configured to connect to the specific database you are using It also needs to be configured for the type of database Hibernate may do things differently for different databases The configuration can be done in multiple ways Via an XML configuration file (named hibernate.cfg.xml by default) Via a properties file (named hibernate.properties by default) The properties file was used in earlier versions of Hibernate It is still supported, but most users are now using the XML file Programmatically via a Java API We'll look mainly at the hibernate.cfg.xml file Most users prefer the hibernate.cfg.xml XML file for configuration The properties file was used in earlier Hibernate versions, but has mostly been superseded by the XML configuration The programmatic configuration is useful if an application needs to dynamically configure its connection Copyright LearningPatterns Inc. All rights reserved. 22

31 Session 1: Introduction to Hibernate Sample hibernate.cfg.xml The configuration file has the structure shown below A <session-factory> element contains the configuration for the connection to the database The file needs to be on the classpath <?xml version='1.0' encoding='utf-8'?> <!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 3.0//EN" " <hibernate-configuration> <! Configuration for a SessionFactory instance --> <session-factory> </session-factory> </hibernate-configuration> Copyright LearningPatterns Inc. All rights reserved. 23

32 Session 1: Introduction to Hibernate hibernate.cfg.xml Elements <hibernate-configuration> - The root element Can contain a single <session-factory> element and an optional <security> element <session-factory> - Information for creating a SessionFactory (representing a single DB) <property> sub-elements used for much of the configuration Database information (connection info, database type ) Specification of transaction behavior Many properties look at the docs. We show some common ones <mapping> elements specify entity class mapping files <class-cache> and <collection-cache> contain cache properties <event> elements let you specify Hibernate events <security> contains security configuration information Copyright LearningPatterns Inc. All rights reserved. 24

33 Session 1: Introduction to Hibernate SessionFactory Configuration Needs to have the usual database information Database JDBC URL Database driver User name, password You may also specify a datasource name if you are using one You can also specify a database dialect This is the fully qualified classname of a class that customizes Hibernate's behavior for a specific database Other properties Many other things that can be specified in the configuration For example, caching related properties Copyright LearningPatterns Inc. All rights reserved. 25

34 Session 1: Introduction to Hibernate SessionFactory Configuration Properties There are many properties available We show some of the important ones here see the docs! There are many properties to tune the connection, caching, transaction JDBC Connection Properties hibernate.connection.driver_class: jdbc driver class hibernate.connection.url: jdbc URL hibernate.connection.username: database user hibernate.connection.password: database user password hibernate.connection.pool_size: max pooled connections DataSource Connection Properties hibernate.connection.datasource: datasource JNDI name hibernate.jndi.url, hibernate.jndi.class: JNDI Properties Optional Configuration Properties hibernate.dialect: Classname of a Hibernate Dialect hibernate.show_sql: Write all SQL statements to console hibernate.cache.provider_class: Classname of custom cache provider There are way to many properties to cover in this course manual See the Hibernate Reference Documentation Chapter 3 For example there are properties for JDBC Tuning hibernate.jdbc.fetch_size, hibernate.jdbc.batch_size, hibernate.jdbc.use_scrollable_resultset, hibernate.connection.provider_class, hibernate.connection.isolation, hibernate.connection.autocommit, hibernate.connection.<propertyname>, hibernate.jndi.<propertyname> Hibernate Cache Properties hibernate.cache.provider_class, hibernate.cache.use_query_cache, hibernate.cache.use_second_level_cache, and more Hibernate Transaction Properties hibernate.transaction.factory_class, jta.usertransaction, hibernate.transaction.manager_lookup_class, hibernate.transaction.flush_before_completion, hibernate.transaction.auto_close_session hibernate.hbm2ddl.auto : Automatically validate or export schema DDL to the database when the SessionFactory is created. (validate update create create-drop) Copyright LearningPatterns Inc. All rights reserved. 26

35 Session 1: Introduction to Hibernate Example Properties for PostgresSQL The example below shows properties that would be suitable if you were using the open-source PostgresSQL database <!-- Other detail omitted --> <session-factory> <!-- Database Connection Settings --> <property name="hibernate.connection.username">guest</property> <property name="hibernate.connection.password">password</property> <property name="hibernate.connection.url"> jdbc:postgres://localhost/db</property> <property name="hibernate.connection.driver_class"> org.postgresql.driver</property> <!-- SQL Dialect --> <property name="hibernate.dialect"> org.hibernate.dialect.postgresqldialect</property> <!-- Connection Pool Settings (uses built-in connection pool) --> <property name="hibernate.connection.pool_size">1</property> </session-factory> The first four property elements contain the necessary configuration for the JDBC connection The dialect property element specifies the particular SQL variant Hibernate generates. If you're working in a J2EE environment, there are properties that allow you to specify a datasource JNDI name (hibernate.connection.datasource) Hibernate is the layer in your application which connects to this database, so it needs connection information The connections are made through a JDBC connection pool, which we also have to configure The Hibernate distribution contains several open source JDBC connection pooling tools, but this example uses the Hibernate built-in connection pool. Note that you have to copy the required library into your classpath and use different connection pooling settings if you want to use a production-quality third party JDBC pooling software [Hibernate Reference Documentation, Section 1.2.3] Copyright LearningPatterns Inc. All rights reserved. 27

36 Session 1: Introduction to Hibernate The Configuration Class A Configuration instance is used to specify the configuration files that are read to configure Hibernate You usually create one instance of Configuration, and one instance of SessionFactory per application, usually via the following Configuration methods: A constructor configuring Hibernate via hibernate.properties configure() configuring Hibernate via hibernate.cfg.xml There are also versions of configure that allow you to specify the configuration file name and location buildsessionfactory() creating a SessionFactory You can also configure Hibernate programmatically with a Configuration instance See the javadoc! The Configuration instance is intended as a startup-time object, to be discarded once a SessionFactory is created. You can think of the Configuration instance as the in-memory Java representation of the configuration information When you create a Configuration instance with its no-arg constructor, it will by default look for a hibernate.properties file in the root of the classpath If it finds hibernate.properties, it will load all the hibernate.* properties in this file, and add it to the instance If you call configure() on this instance (not required), hibernate searches for a file named hibernate.cfg.xml in the root of the classpath, and an exception is thrown if the file isn't found If it finds hibernate.cfg.xml, it reads the properties in the file, and adds them to the instance overriding any already existing properties in the instance We don't cover programmatic configuration, but the Configuration interface has methods that allow you to do the same things you can do with a configuration file Copyright LearningPatterns Inc. All rights reserved. 28

37 Session 1: Introduction to Hibernate The SessionFactory Interface A SessionFactory creates sessions Its behavior is controlled by configuration properties Usually an application has a single SessionFactory A SessionFactory is immutable It is an expensive-to-create, threadsafe object intended to be shared by all application threads It is created once, usually on application startup, from a Configuration instance. It is a global factory responsible for a particular database Configured by the hibernate.cfg.xml configuration file This configuration defines the set of entities that can be managed by a given Session instance It defines the types that can be managed It defines the database they are persisted to Startup of a Hibernate application often includes building a global SessionFactory object and storing it somewhere for easy access in application code A SessionFactory can open up new Session's A Session represents a single-threaded unit of work, the SessionFactory is a thread-safe global object, instantiated once. Hibernate supplies a sample HibernateUtil helper class which takes care of startup and makes accessing a SessionFactory convenient We'll look at this later Copyright LearningPatterns Inc. All rights reserved. 29

38 Session 1: Introduction to Hibernate SessionFactory API Here are some common methods of SessionFactory void close(): Destroy this SessionFactory and release all its resources (caches, connection pools, etc). Session opensession() - Create a database connection and open a Session on it public Session opensession(connection connection): Open a Session on the given connection For applications that manage JDBC connections themselves Session getcurrentsession() Get the current session We'll look later at the definition of what "current session" means Many more methods see the documentation It is the responsibility of the application to ensure that there are no open sessions before calling close() on the SessionFactory The API includes methods to: Evict objects and collections from the second level cache (covered later) Get metadata about entities managed by the factory Copyright LearningPatterns Inc. All rights reserved. 30

39 Session 1: Introduction to Hibernate The Session Interface Session is the main runtime interface used with Hibernate Abstracts the notion of a persistence service Inexpensive, non-threadsafe object that should be used once, for a single request, or single unit of work, and then discarded Won't obtain a JDBC Connection (or a Datasource) unless it is needed, hence consumes no resources until used Generally, you keep the session around for the duration of a logical transaction Session has a number of capabilities Saving: persisting objects to persistent storage Deleting: removing objects from persistent storage Updating: updating the persistent data of an entity Loading: Retrieving an instance from persistent storage We'll look at this interface in more detail later The lifecycle of a Session is bounded by the beginning and end of a logical transaction Long transactions might span several database transactions. The main function of the Session is to offer create, read and delete operations for instances of mapped entity classes Copyright LearningPatterns Inc. All rights reserved. 31

40 Session 1: Introduction to Hibernate Sessions and Transactions By default, work done with a session is not persisted to the database until the associated transaction commits Objects that are saved or updated are written to a transaction cache for that session When the transaction commits, the objects are written to the DB You can work with transactions through the Hibernate API We'll cover this in more detail later You start a transaction and obtain an org.hibernate.transaction object from a session Transaction tx = s.begintransaction(); You can commit or rollback via the transaction object tx.commit(); // Commit the transaction Copyright LearningPatterns Inc. All rights reserved. 32

41 Session 1: Introduction to Hibernate A Basic Hibernate Program Example We start simply, and we'll cover more of the details later The example just reads the configuration and connects to the DB import org.hibernate.hibernateexception; import org.hibernate.session; import org.hibernate.sessionfactory; import org.hibernate.cfg.configuration; public class TestHibernate { public static void main(string[] args) { SessionFactory sf; Session s; } } try { sf = new Configuration().configure().buildSessionFactory(); s = sf.opensession(); s.begintransaction(); System.out.println("Session connect status: " + s.isconnected()); s.gettransaction().commit(); s.close(); sf.close(); } catch (HibernateException e) { e.printstacktrace(); } This is the most common way of configuring and starting Hibernate in a Java SE Environment The configuration will be looked for in the default hibernate.properties, and hibernate.cfg.xml files (which must be in the classpath) Note that Hibernate 3.x package names start with org.hibernate Previous releases of Hibernate used the package prefix net.sf Note the handling of the HibernateException Many Hibernate methods throw this exception It represents any exception that occurs inside the persistence layer or JDBC driver SQLExceptions are always wrapped by instances of JDBCException There are many, more specific, subclasses of HibernateException Copyright LearningPatterns Inc. All rights reserved. 33

42 Lab 1.1: Setting up Hibernate Lab 1.1 Setting up Hibernate Copyright LearningPatterns Inc. All rights reserved. 34

43 Lab 1.1: Setting up Hibernate A Hibernate Application Lab Overview: In this lab you will become familiar with and set up your environment, and create a simple Hibernate application The environment consists of the open source Derby database, and the Eclipse Development environment Objectives: Set up a database (the open source Derby database) Create an Eclipse project that has all the needed libraries (Hibernate and JDBC driver) Configure hibernate and write a simple hibernate application Builds on previous labs: None Approximate Time: minutes Copyright LearningPatterns Inc. All rights reserved. 35

44 Lab 1.1: Setting up Hibernate Information Content and Task Content Lab Within a lab, information only content is presented in the normal way the same as in the student manual pages Like these bullets at the top of the page Tasks that the student needs to perform are in a box with a slightly different look to help you identify them An example appears below Tasks to Perform Look at these instructions, and notice the different look of the box as compared to that above Make a note of how it looks, as future labs will use this format OK we're ready to start working Copyright LearningPatterns Inc. All rights reserved. 36

45 Lab 1.1: Setting up Hibernate Setup the Environment Lab Tasks to Perform Make sure that you have Java 5 or 6 installed Java 5 standard installation directory is C:\Program Files\Java\jdk1.5.0_nn Java 6 standard installation directory is C:\Program Files\Java\jdk1.6.0_nn Make sure that you have Eclipse installed Standard location is in c:\eclipse If not installed, downloadable from Make sure that you have Hibernate 3.6 * installed Likely in a directory like c:\hibernate-distribution final If not installed, downloadable from To download Eclipse, download the zip file for it, and unzip it to C:\ That's all that's needed for installation, though you can copy a shortcut from C:\eclipse\eclipse.exe to your desktop to make starting Eclipse easier The instructions in the labs assume Hibernate 3.6, and Eclipse 3.6 If you use a different platform, you'll need to modify the lab instructions somewhat Most recent versions of either should work Copyright LearningPatterns Inc. All rights reserved. 37

46 Lab 1.1: Setting up Hibernate Extract the Lab Setup Zip File Lab To set up the labs, you'll need the lab setup file * The file name is something like: Hibernate_LabSetup_.zip Our base working directory for this course will be C:\StudentWork\Hibernate The C:\StudentWork\Hibernate\Derby directory contains database files and various command scripts we will use All instructions assume that this zip file is extracted to C:\. If you choose a different directory, please adjust accordingly Tasks to Perform Unzip the lab setup file to C:\ This will create the directory structure, shown on the next slide, containing files you'll need for doing the labs The setup zip will either be given to you on a CD, be present on your machines or supplied by your instructor If you have a CD, it may also contain additional folders with extra content InstallFiles: Extra software install files (e.g. simple editor) Resources: Documentation, specifications, etc. Which extra files are supplied will vary based on space limitations Copyright LearningPatterns Inc. All rights reserved. 38

47 Lab 1.1: Setting up Hibernate Lab Directory Structure Lab StudentWork\Hibernate contains Derby: Database files Resources : Extra files (e.g. docs) Setup: files needed for lab work LabNN: directory for any lab with additional setup files workspace: Lab directories StudentWork\Hibernate\workspace will contain the following folders: common: shared files LabNN : Directory for Lab NN LabNN/bin/ : compiled code (we use this to be Eclipse compatible) LabNN/src/ : Java source To make it easier to open command windows in the lab dirs, we've included a utility in the setup that allows you to right click on a folder to open a command prompt in it To install this: Go to the StudentWork\Hibernate\Utilities\CommandPromptHere folder Right click on the.reg file there, and select Merge Once you've done that, right clicking on a folder will show a Command Prompt Here selection in the context menu - Select that to open a command prompt in the directory Copyright LearningPatterns Inc. All rights reserved. 39

48 Lab 1.1: Setting up Hibernate Start the Database Lab We are using the open source Derby database for the labs We will set up and run this database using a number of scripts supplied in the setup in C:\StudentWork\Hibernate\Derby Tasks to Perform Open the StudentWork\Hibernate\Derby\dbSetenv.cmd file Look at how DB_NAME is set (you don't need to change this): set DB_NAME=jdbc:derby://localhost:1527/JavaTunesDB This sets the server that our tools will talk to The server on localhost listening on the standard Derby server port Using the database with the name JavaTunesDB Start the Derby database server Execute dbstart.cmd (you can double-click on it) This starts a standalone Derby server that can accept network connections to the database Derby is an open source all-java database environment that was originally developed as the Cloudscape database It was contributed by IBM to the Apache Software Foundation See Provides developers with a database for use in developing enterprise applications, using J2EE technologies You shouldn't need to change anything in dbsetenv.cmd We have you look at it so you understand how the scripts are set up If you have trouble running the scripts, try opening a command window in the Derby folder, and then running them This way the window stays around long enough to read the error messages Copyright LearningPatterns Inc. All rights reserved. 40

49 Lab 1.1: Setting up Hibernate Creating and Browsing the Database Lab Create the database ij> select * from item;... Lots of output... ij> exit; Tasks to Perform Execute dbcreate.cmd (you can double-click on it) This creates the JavaTunesDB database You can ignore a DROP TABLE error, if you see it Execute dbsql.cmd to run ij (you can double-click on it) This command file is set up to connect to the correct database Using ij, browse the DB to check the setup (sample SQL below) ij is Derby's SQL command line tool It allows us to create database objects and view and manipulate database data, without having to write code to do so Most database packages provide such a tool dbcreate.cmd generates a DROP TABLE error the first time it is run, because it drops the Item table, which doesn't exist the first time, then creates it. The database for this course consists only of the Item table. If you ever want a "fresh" database, simply rerun dbcreate.cmd. dbsql.cmd launches the ij program, a command line SQL tool. All commands in ij are terminated with a semicolon (;). For help, type help;. To exit, type exit;. To stop the database server, run the dbstop.cmd program But leave it running for now Some classrooms use a single central database server In this case, each student should append a unique number to the name of the database e.g. JavaTunesDB1 for the 1 st student, JavaTunesDB2 for the 2 nd, etc. This will give each student their own database to work with Copyright LearningPatterns Inc. All rights reserved. 41

50 Lab 1.1: Setting up Hibernate General Instructions Lab The root lab directory where you will do your work for this lab is: C:\StudentWork\Hibernate\workspace\Lab01.1 This directory already exists in your workspace you'll need to edit files under this directory, and build the application from within this directory In general, all the files you will work on for a lab will be under the root directory (and instructions are given relative to this directory) Detailed instructions are included in this lab They include complete instructions for working in the Eclipse environment, as well as details about the lab requirements Subsequent labs require you to do the same thing as this lab to build/run, so they don't include detailed instructions on how to do so Copyright LearningPatterns Inc. All rights reserved. 42

51 Lab 1.1: Setting up Hibernate The Eclipse Development Environment Lab We will use Eclipse, an open source platform for building IDEs, for programming our labs Used mainly for Java development Can be extended via plugins to create applications useful in many areas (e.g. C# programming) is the main website The remainder of this lab includes detailed instructions on using Eclipse to run the labs Starting it, creating and configuring projects, etc. The other labs in the course include fewer specific details regarding Eclipse they just say build/run as previously For these labs, you should use the same procedures to build/run as in this lab Refer back to these lab instructions as needed The Eclipse source base was originally developed by IBM It was released by IBM into open source IBM's RAD (and previously its WSAD) environment is built on top of Eclipse Copyright LearningPatterns Inc. All rights reserved. 43

52 Lab 1.1: Setting up Hibernate Launch Eclipse Lab Tasks to Perform Launch Eclipse if you haven t already Go to c:\eclipse and run eclipse.exe A dialog box should appear prompting for a workbench location Set the workbench location to C:\StudentWork\Hibernate\workspace If a different default Workbench location is set, change it If you've already opened to another workspace, you can go to File -> Switch Workspace to open the correct one You can put a shortcut to eclipse.exe on your desktop for convenience If Eclipse was installed elsewhere, then adjust the above directions accordingly If Eclipse was not installed, the setup zip file is available on the CD under the InstallFiles folder Copyright LearningPatterns Inc. All rights reserved. 44

53 Lab 1.1: Setting up Hibernate Workbench and Java Perspective Lab Tasks to Perform Close the Welcome screen (click the X on its tab see notes) You should be in a Java EE perspective - depending on which Eclipse version you use If in a Java perspective, that's fine - there is nothing else to do If in a Java EE perspective, open a Java one by clicking the Perspective icon at the top right of the Workbench, and select Java (as shown below left) Close the Java EE perspective by right clicking its icon, and selecting close (as shown below right) To close welcome screen, click the X in the tab in the upper left corner, as shown at bottom The Eclipse Java EE version opens in the Java EE perspective by default The Basic version, opens in the Java perspective, and you won't need to switch if using it Copyright LearningPatterns Inc. All rights reserved. 45

54 Lab 1.1: Setting up Hibernate Unclutter the Workbench Lab Tasks to Perform Let's unclutter the Java Perspective by closing some views Close the Task List, Outline and Hierarchy views (click on the X) Open the Navigator View (Window Show View Navigator) You can save this as the default if you want (see note) To save the perspective as the default Java perspective go to Window Save Perspective As Java You can reset the perspective to it's defaults via Window Reset Perspective Copyright LearningPatterns Inc. All rights reserved. 46

55 Lab 1.1: Setting up Hibernate Create User Libraries Lab We need to include many Hibernate jars in our classpath We'll set these up as a user library, to make it easy to set up the classpath each time we create a new project Tasks to Perform Go to Window Preferences Java Build Path User Libraries Click New In the next dialog, call the library Hibernate, and press OK Click the Add JARs button, browse to <hibernate> *, select hibernate3.jar and select Open* You will need to add in all the jars listed on the following page Each time you want to add jars, you'll need to select the Hibernate library in the User Libraries dialog, click the Add JARs button, browse to the appropriate directory, select the jars needed and click OK <hibernate> stands for the directory that Hibernate is installed in For example, C:\hibernate-distribution SP1 hibernate3.jar contains the complete Hibernate distribution, and you need to include that on your classpath The other jars in the lib directory are libraries that Hibernate depends on We don't really need all of them, but in this situation, it's the easiest way to add them You can select multiple files in the dialog by using holding down the Control key as you select each file Copyright LearningPatterns Inc. All rights reserved. 47

56 Lab 1.1: Setting up Hibernate Create User Libraries Lab Tasks to Perform Select the Hibernate library again, click Add JARs and browse to <hibernate>\lib\required Select all the files in this directory * Click Open to add in all the selected jars Similarly, browse to <hibernate>\lib\jpa and add in all the jars in that directory (JPA classes are used internally in Hibernate) Similarly, browse to C:\StudentWork\workspace\common\lib and add in all the jars in that directory (we'll explain these later) Similarly, add in derbyclient.jar in the directory: C:\StudentWork\Hibernate\Derby\lib Click OK to finish creating the library You can type Ctrl-a (Hold down the Control and "a" key at the same time) in the file selector window to select all the files For Hibernate 3.2, add in the Hibernate jars as follows: Browse to <hibernate>\lib Type Ctrl-a to select all the jars in the lib directory Still holding down the Ctrl key, click xerces jar to deselect it (not needed for JDK 1.4+) Click Open to add in all the selected jars You don't need to add in the jars in workspace\common\lib derbyclient.jar is needed to run the database access labs that use the Derby database If you haven't installed the student files in the standard C:\ location, then adjust any paths appropriately Copyright LearningPatterns Inc. All rights reserved. 48

57 Lab 1.1: Setting up Hibernate Create a Project for our Application Lab Tasks to Perform Close any open welcome screens Create a Java Project * Call the project Lab01.1 Eclipse will then automatically set the project directory to Lab01.1 We supply an existing Lab01.1 directory, and Eclipse will configure the project based on the source in that directory Click Next This will bring you to a dialog where you can set the Java Settings for the project To create a new Java Project, use the menu item File New Project Java Java Project There are many other ways to create a project You can use the new icon on the left hand side of the toolbar, as shown above You will need to create a new Java project in Eclipse each time the lab instructions tell you to use a new Lab directory This happens several times in the course, and you'll need to create a new project each time Copyright LearningPatterns Inc. All rights reserved. 49

58 Lab 1.1: Setting up Hibernate Add the Hibernate Library to ClassPath Lab Tasks to Perform In the Java Settings dialog, click the Libraries tab * Click the Add Library button, and in the dialog that comes up, select User Library then click Next Check off Hibernate, then click Finish in all open dialogs * If you forget to add the library in this step, you can always add it later as follows Right click on the project, select Properties, then select Java Build Path Go to the Libraries tab, and add in the Hibernate library as described above When the project is created, Eclipse will attempt to compile all the Java source This will lead to warnings about unused imports, variables, etc. You can just ignore these most of them are because the files we give you are just skeletons, and not complete. If you want, you can shut these warnings off as follows: Window Preferences Java Compiler Errors/Warnings Go to the "Unnecessary Code" section, and change the settings for "Unused import", "Unused local or private member", and "Local variable is never read" to "Ignore" Copyright LearningPatterns Inc. All rights reserved. 50

59 Lab 1.1: Setting up Hibernate Finish hibernate.cfg.xml Lab Tasks to Perform In your Lab01.1 project, open src/hibernate.cfg.xml It contains a skeleton configuration file Fill in any required properties, with the info below (look for the TODO) Look at the examples in the course manual User: guest Password: password DB URL: jdbc:derby://localhost:1527/javatunesdb This property is supplied for you in the config file DB Driver: org.apache.derby.jdbc.clientdriver Dialect: org.hibernate.dialect.derbydialect Connection Pool Size: 1 We include a few additional properties in the supplied configuration file One property echoes all of the executed SQL to stdout <property name="show_sql">true</property> Copyright LearningPatterns Inc. All rights reserved. 51

60 Lab 1.1: Setting up Hibernate Create a TestClass Lab Tasks to Perform Test the configuration using a test class Open the classtesthibernate which is in the default package In the main method, create a Configuration, a SessionFactory, and then a Session Print out a message that tells whether or not the Session is connected Look at the examples in the course manual Don't forget to import the classes you need (see next slide) The test class should compile cleanly We are using Hibernate classes, but we have the Hibernate jars on the Java build path for the Hibernate project in Eclipse We use the jars that come with the Hibernate distribution for the labs The hibernate3.jar file is the main jar file, and is in the hibernate home directory There are dependency jars in the lib directory under hibernate home These are libraries that Hibernate uses Copyright LearningPatterns Inc. All rights reserved. 52

61 Lab 1.1: Setting up Hibernate Eclipse Hint - Importing Lab One of the nicest features of Eclipse is its auto-import feature To try it out, in your TestHibernate.java file, remove the import for Session if you've already put it in (if you haven't imported it, then just continue below) in your TestHibernate.main() method, type Session, then type Ctrl-Space Select the org.hibernate entry and hit return An import org.hibernate.session statement will very conveniently be added at the top of your source file Eclipse can help you with importing classes that you need When you use a class, and it's not properly imported, Eclipse notices, and marks if for you If you move your cursor into or at the end of the class name, and type Control-space, it will bring up a window with possible classes to import You can select the class you want, and Eclipse will automatically add in the import for you Copyright LearningPatterns Inc. All rights reserved. 53

62 Lab 1.1: Setting up Hibernate Running Your Application Lab Tasks to Perform After a clean build (one that is error-free, but not necessarily warning-free), test the application In the Package Explorer pane, right click on the TestHibernate.java file Select: Run As -> Java Application This will automatically find the main method in TestHibernate and run it for you Copyright LearningPatterns Inc. All rights reserved. 54

63 Lab 1.1: Setting up Hibernate Testing your Application Lab If everything is set up correctly, the program should run You will see the results in the console view (bottom panel by default) Ignore any output related to logging - we will cover this later Copyright LearningPatterns Inc. All rights reserved. 55

64 Lab 1.1: Setting up Hibernate Debugging Problems Lab Tasks to Perform If you fail to connect to the database do the following Look at the error messages Check to see that the database server is running Make sure that the database URL is correct Did you create the database? Try using the dbsql command to connect to the database Ask for help from the instructor if you still can't connect Note, that when you want to run the application again, you can click the run button arrow on the task bar This brings up a list of all the run configurations you've recently used Copyright LearningPatterns Inc. All rights reserved. 56

65 Lab 1.1: Setting up Hibernate Important Notes for Using Eclipse Eclipse Each lab that has a separate lab directory will require you to create a new Eclipse project Sometimes several labs are done one directory, in which case you will use the same project for all of them Each time you create a new project, you'll need to add the Hibernate library to the project build path to compile and run Anytime you COPY files into a project (e.g. from setup) you need to Refresh it (Right click on the project, select Refresh) For anyone not familiar with Eclipse, the next few slides give a (very) brief overview of how Eclipse is structured There is nothing you need to do in those slides they are for information purposes only Take note of the Lab instructions Any lab that starts out saying that it will be done in a new directory will require you to create a new Java project You'll create the project with the name of the directory specified in the lab You'll do it in the same way as you created this one There will be some instructions, and you can also come back to this lab Any lab that has you copy files from the setup to your working directory will require you to refresh the project as described above This allows Eclipse to become aware of the new files. Copyright LearningPatterns Inc. All rights reserved. 57

66 Lab 1.1: Setting up Hibernate The Eclipse Paradigm Eclipse Eclipse products have two fundamental layers The Workspace files, packages, projects, resource connections, configuration properties The Workbench editors, views, and perspectives The Workbench sits on top of the Workspace and provides visual artifacts that allow you to access and manipulate various aspects of the underlying resources, such as: Editor A component that allows a developer to interact with and modify the contents of a file. View A component that exposes meta-data about the currently selected resource. Perspective A grouping of related editors and views that are relevant to a particular task and/or role. You can have multiple perspectives open to provide access to different aspects of the underlying resources The physical directory structure for the Workspace can be found in the workspace directory The default location is directly under the Eclipse home directory You can specify a different workspace location when you start Eclipse It is even possible to set up multiple workspaces (with corresponding Workbenchs). Simply create a folder to house the additional workspace, and write a script that uses the Eclipse executable file and supplies the data argument with the location of the workspace directory to load: c:\eclipse\eclipse.exe -data other_workspace_folder A Perspective is basically a collection of views that are focused on a given task They provide different tools to work with the resources For example, the debugging perspective has views open for debugging, such as: Active Threads, Variables, Breakpoints, etc. There are perspectives for Java development (Java Perspective), and so on What perspectives are available depends on what version of Eclipse you have, and what plugins you have installed Copyright LearningPatterns Inc. All rights reserved. 58

67 Lab 1.1: Setting up Hibernate Workbench and Workspace Eclipse Workspace (Model) Workbench (View) We use the terms Model and View here in the same sense as when talking about Model-View-Controller (MVC) The Model is the actual data (the files) The View is the Eclipse Workbench Copyright LearningPatterns Inc. All rights reserved. 59

68 Lab 1.1: Setting up Hibernate Navigator View Eclipse Shows how different resources are structured There are three kinds of resources: Files Correspond to files on the file system Folders Like directories on the file system Projects Used to organize all your resources and for version control. When you create a new project, you assign a physical location for it on the file system. A third-party SCM (Source Control Manager) may be used to properly share project files amongst developers. The Navigator view is one of the most commonly used views. It provides a file-based organization of the various resources. There are other views that give application-based, and project-based organization of data Copyright LearningPatterns Inc. All rights reserved. 60

69 Lab 1.1: Setting up Hibernate Package Explorer Eclipse The Package Explorer view, is shown by default in the Java perspective It shows the Java element hierarchy of the Java projects in your workbench It provides a Java-specific view of the resources shown in the Navigator It also makes it easy to work with Java resources for example to create a new class, just click on the package you want and select New Class * Copyright LearningPatterns Inc. All rights reserved. 61

70 Lab 1.1: Setting up Hibernate Editors Eclipse There is a source editor (like this one for a.java file) for all character files. (.java,.jsp,.html, etc.) STOP Copyright LearningPatterns Inc. All rights reserved. 62

71 Session 1: Introduction to Hibernate Mapping a Simple Class Hibernate Overview Using Hibernate Mapping a Simple Class Logging Copyright LearningPatterns Inc. All rights reserved. 63

72 Session 1: Introduction to Hibernate Persistent Entity Classes A persistent entity class is a lightweight persistent domain object They are fine-grained objects representing state stored in a DB Entity classes are one of the primary programming artifacts of Hibernate Entity classes Must be persistable i.e. have a database representation Have a persistent identity basically the primary key in the DB Are normally created/updated/deleted within a transaction Metadata describes the mapping to the data store Can be done with XML or annotations (new in Hibernate 3) The metadata required is minimized through the use of intelligent defaults Hibernate supports annotations that are compatible with the Java Persistence API It is likely that these annotations will eventually become the preferred way of specifying metatdata for persistent classes Hibernate originally used the name "persistent class" to describe a class that was mapped to the database The Java Persistence API introduced the term "entity class" They are usually used interchangeably in Hibernate literature today We will use both terms to mean the same thing Copyright LearningPatterns Inc. All rights reserved. 64

73 Session 1: Introduction to Hibernate Persistent Classes Persistent classes work best if they follow a few simple rules Implement a no argument constructor for Hibernate to instantiate instances through reflection (required) Declare getter/setter methods for all persistent fields (optional) Provide an identifier property (usually called id) (optional) Maps to primary key column of database Primitive type, or primitive wrapper, String, Date, composite key Theoretically optional, but required for use of the full feature set of Hibernate Implement equals() and hashcode() (optional) Necessary if you mix instances created in different sessions If instances will be passed as a detached object through a remote interface, the class must implement Serializable Copyright LearningPatterns Inc. All rights reserved. 65

74 Session 1: Introduction to Hibernate An Example Persistent Class package com.javatunes; import java.util.date; public class Event { private Long id; private String title; private Date date; // Property for database id Event() {} public Event(Long id) { setid(id); } 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; } Copyright LearningPatterns Inc. All rights reserved. 66

75 Session 1: Introduction to Hibernate The Event Class The event class has three properties id (Long), date (java.sql.date), title (String) The id property holds a unique identifier for each event The class has JavaBean style get/set methods for all the properties The class also has no-argument constructor By default, no properties are persistent That is, they are not stored in the database A mapping file is used to specify persistent fields Note that the setter for id is private Programs will not be allowed to change this value Copyright LearningPatterns Inc. All rights reserved. 67

76 Session 1: Introduction to Hibernate The id Property The id property will hold the primary key of the entity A class must have a primary key, and it is highly recommended that you define a property to hold it A non-composite primary key must correspond to a single field in an entity (e.g. the id field in the Event class) A simple primary key must be one of the following: Java primitive or wrapper class (integral types most common) java.lang.string, java.util.date, java.sql.date Generated primary keys are supported Only integral types will be portable Composite primary keys are also possible These use a primary key class The identifier property is strictly optional. You can leave them off and let Hibernate keep track of object identifiers internally. We do not recommend this, however. In fact, some functionality is available only to classes which declare an identifier property: Transitive reattachment for detached objects (cascade update or cascade merge) Session.saveOrUpdate() Session.merge() We recommend you declare consistently-named identifier properties on persistent classes. We further recommend that you use a nullable (ie. non-primitive) type. [Hibernate Reference Documentation, Section 4.1.2] A composite primary key must correspond to either a single persistent field or property or to a set of such fields or properties A primary key class must be defined to represent a composite primary key Composite primary keys typically arise when mapping from legacy databases when the database key is comprised of several are used to denote composite primary keys Copyright LearningPatterns Inc. All rights reserved. 68

77 Session 1: Introduction to Hibernate The Hibernate Mapping File Specifies the mapping of your entity classes to the DB Here is the top-level structure of the mapping file This declares this to be a mapping for the Event class, with a mapping to the EVENTS table The name of the mapping file is generally named after the class (e.g. Event.hbm.xml for the Event class) <?xml version="1.0"?> <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 3.0//EN" " <hibernate-mapping> <class name="com.javatunes.event" table="events"> <!-- Property Mappings --> </class> </hibernate-mapping> Note that the Hibernate DTD is very sophisticated. You can use it for auto-completion of XML mapping elements and attributes in your editor or IDE. You also should open up the DTD file in your text editor - it's the easiest way to get an overview of all elements and attributes and to see the defaults, as well as some comments. Note that Hibernate will not load the DTD file from the web, but first look it up from the classpath of the application. The DTD file is included in hibernate3.jar as well as in the src/ directory of the Hibernate distribution. [Hibernate Reference Documentation] Copyright LearningPatterns Inc. All rights reserved. 69

78 Session 1: Introduction to Hibernate The <hibernate-mapping> Element Root element of the mapping file Usually contains a single <class> element mapping one class Legal to have multiple <class> elements, but not recommended Has optional attributes that affect all mappings in the file schema: The name of a database schema. catalog: The name of a database catalog. default-cascade (default=none): Default cascade style. default-access (default=property): The strategy Hibernate should use for accessing all properties default-lazy (default=true): The default value for unspecified lazy attributes of class and collection mappings. auto-import (default=true): Can we use unqualified class names (of classes in this mapping) in the query language. package: Package prefix for unqualified class names in mapping Copyright LearningPatterns Inc. All rights reserved. 70

79 Session 1: Introduction to Hibernate The <class> Element Declares a persistent class Contains sub-elements that declare the persistent properties of the class Has a large number of optional attributes affecting the mapping of the persistent class We show some of the more common ones here see the docs name: Fully qualified Java class name of the persistent class table (default=unqualified class name): name of its DB table mutable (default=true): Specifies if instances are (not) mutable entity-name (default= class name): Name of this entity as used in queries, other mappings If you use the package attribute in the <hibernate-mapping> element, and the class is in the same package, then you don't need to fully qualify it in the name attribute <hibernate-mapping package="com.javatunes"> <class name="event" table="events"> <!-- Property Mappings --> </class> </hibernate-mapping> Hibernate3 allows a class to be mapped multiple times (to different tables, potentially), and allows entity mappings that are represented by Maps or XML at the Java level. In these cases, you should provide an explicit arbitrary name for the entity with the entity-name attribute Copyright LearningPatterns Inc. All rights reserved. 71

80 Session 1: Introduction to Hibernate The EVENTS Table Let's assume that the EVENTS table is declared as below Assume you are using a generated primary key A very common situation The SQL shown is for the open source Derby database using an Identity column Let's look at how to map our Event class CREATE TABLE EVENTS ( EVENT_ID BIGINT NOT NULL GENERATED ALWAYS AS IDENTITY (START WITH 1, INCREMENT BY 1), EVENT_DATE DATE, TITLE VARCHAR(80), CONSTRAINT PK_EVENTS PRIMARY KEY(EVENT_ID) ); Copyright LearningPatterns Inc. All rights reserved. 72

81 Session 1: Introduction to Hibernate Mapping the id Property with <id> The <id> element declares the primary key in the database The name attribute specifies the property it is mapped to (id) The column attribute maps this to the EVENTS table's primary key column (EVENT_ID) We also configure Hibernate to automatically generate the primary key value for us <hibernate-mapping> <class name="com.javatunes.event" table="events"> <id name="id" column="event_id"> <generator class="identity"/> </id> </class> </hibernate-mapping> Mapped classes must declare the primary key column of the database table. Most classes will also have a JavaBeans-style property holding the unique identifier of an instance. The <id> element defines the mapping from that property to the primary key column. [Hibernate Reference Documentation, Section 5.1.4] The id property can have any name It is customary to call it id Copyright LearningPatterns Inc. All rights reserved. 73

82 Session 1: Introduction to Hibernate More About Primary Keys Hibernate requires that every entity have a primary key Just as every row in a database needs a primary key In modern database schemas, primary keys are usually surrogate, artificially generated keys Though legacy databases might have so called "natural" keys which represent some combination of business data Natural keys are sub-optimal for many reasons Hibernate primary key requirements are basically the same as for relational tables in general Primary key must be non-null, unique, and immutable Hibernate also needs to know how the key is created, since the primary key can be auto-generated in different ways Hibernate has extensive support for dealing with primary keys For surrogate, generated keys, and for natural keys Copyright LearningPatterns Inc. All rights reserved. 74

83 Session 1: Introduction to Hibernate Generating the id Value The <generator> element specifies a generated key It declares a class used to generate the id value There are many options to deal with generating this primary key, including letting the database or Hibernate generate it The following generators create keys of type long, short or int increment: Identities unique only when no other process is inserting into the table (not for cluster) identity: Uses identity columns for databases supporting it sequence: Uses a sequence for databases supporting it hilo: Uses a hi/lo algorithm to efficiently generate identifiers assigned: lets application assign value before a save() Often used for natural keys More are available See the documentation Copyright LearningPatterns Inc. All rights reserved. 75

84 Session 6: Hibernate and the JPA Lesson Summary JPA standardizes ORM and supports most of the capabilities that Hibernate supports It also integrates with Java EE very cleanly If you know Hibernate, it's not a bit jump to use JPA The main difference is the use of annotations, rather than XML mapping files You can still use XML mapping files JPA has their own specification for this also, though we didn't cover it In general, the annotation based mapping is more generally used with JPA it's simpler and seems to be easier for developers The exception is with certain things where it is still useful to externalize them to an XML file for instance named queries All in all, the standardization of Java ORM should give a big push to its use Copyright LearningPatterns Inc. All rights reserved. 399

85 Session 7: Additional Topics Session 7: Additional Topics Components and Multi-Table Mapping equals() and hashcode() Caching Design Considerations Hibernate Toolset Resources Copyright LearningPatterns Inc. All rights reserved. 400

86 Session 7: Additional Topics Lesson Objectives Explore several advanced topics in Hibernate, including: Embedded components Multi-table mappings Issues around the equals() and hashcode methods Caching, including using a second-level cache Design Considerations Using the Hibernate Toolset Copyright LearningPatterns Inc. All rights reserved. 401

87 Session 7: Additional Topics Components and Multi-Table Mapping Components and Multi-Table Mapping equals() and hashcode() Caching Design Considerations Hibernate Toolset Resources Copyright LearningPatterns Inc. All rights reserved. 402