Dear Documentation Colleagues,

THE HIBERNATE INSTALLATION GUIDE ISSUES:

• Where: ⁠1.2.3.1. Hibernate Configuration Properties
  • Make some introduction, that these are system/java properties. It's not clear that it is not stored in a file. I suggest some introduction. Tables without descriptions are not newbie friendly.
• Where: Table 1.2. Properties
  • Typo - bold font. Sessions word in description of hibernate.connection.release_mode should be whole bold.
• Where: [Table 1.5. Properties - hibernate.hbm2ddl.auto - pipes,
  Table 1.2. Properties - hibernate.connection.release_mode - pipes,
  Table 1.2. Properties - hibernate.connection.isolation - commas,
  ...]
  • Unify enumerations of possible values. In some cases commas are used, in others pipes (|) are used.
• Where: Table 1.5. Properties - hibernate.bytecode.use_reflection_optimizer, hibernate.bytecode.provider
  • Typo. Description should either contain CGLIB in uppercase in both occurances (except possible value) or both in lowercase.
• Where: 1.3.3. Use JNDI to Obtain a Connection
  • Use table as in previous sections for property descriptions.
• Where: Procedure 1.1. Add Auditing Support to a JPA Entity
  • Typo. Add dot at the end of sentence in 1).
  • Point 2. not clear description. What does open in "Open the JPA entity to be audited." means? Open in editor? Open entity in a database browser? ... Suggestion: Open Java source of JPA entity in an editor.
• Where: 2. Using Hibernate
  • Chapter 2 should precede sections of Chapter 1 about Hibernate Envers and Hibernate Annotations. (1.4. Hibernate Annotations and 1.5. Envers) I suggest put them in the second chapter. The Chapter 2 contains introduction and tutorial, which should be one of the first sections of the documentation.
• Where: ⁠2.2. Hibernate Tutorial
  • Typo in Important box. Java word is written in all upper letters, which is not used in previous sentence.
  • There is not tutorial in directory tutorial/eg mentioned in Note.
• Where: 2.3.3. Create the First Class
  • Mention, which filename use for java file.
• Where: 2.3.4. The Mapping File
  • "(aka how are identifier values generated?)" Why is there a question mark?
• Where: 2.3.5. Hibernate Configuration
  • What does the note "We do this do that the data remains between runs." means?
• Where: ⁠2.3.6. Building with Maven
  • Highlight user entered command. Consider removing of directory name from shell prompt and note user to be in root of the maven project.
• Where: 2.3.8. Loading and Storing Objects
  • Typos: worjk -> work, atmoic -> atomic. Handle bold text in sentence "A new listEvents() method is also added:"
• Where: 2.3.8. Loading and Storing Objects, 3.5. Contextual Sessions
  • Chapter reference "Transactions and Concurrency" is not hyperlinked.
• Where: 2.4.3. A Unidirectional Set-based Association
  • Mention importing class java.util.Set ⁠into source (i.e. after mentioning this class in first paragraph).
• Where: [2.4.3. A Unidirectional Set-based Association, 2.4.5. Collection of Values]
  • Instead "database schema" use i.e. class/entity/table/model diagram. Schema in DB context is confusing (Oracle). Just propose - in the chapter 3 there are diagrams as pictures. Are the text diagrams ok? It looks inconsistent.
• Where: 2.5.3. Processing and Rendering
  • Create link to mentioned Hibernate Wiki.
• Where: 2.5.4. Deploying and Testing
  • Are the paths beginning with $JBOSS_HOME correct?
• Where: 3.1. Overview
  • Session - What does "navigating the object graph" means? Is referencing or relation following the meaning of this?
• Where: ⁠3.3. JMX Integration
  • Typo - AN MBean -> An MBean.
• Where: 3.4. JCA Support
  • Add reference to Hibernate website in "⁠Please see the website for more information."