Overview
Documents the persistence framework.
Details
Persistence is handled by the JPA framework with a default Hibernate implementation.
The refset/translation tool includes a JPA-enabled implementation of the Domain Model objects that use annotations to define the connections, cascading, and other relationships between the various objects. For persistence interdependence, we have defined three categories of objects
- Terminology
- Application
- Workflow
Terminology objects represent data elements from the RF2 world (e.g. Concept, Description, Relationship, etc). Application objects represent those things that exist within the scope of this tool (e.g. Refset, Translation, ReleaseInfo, ReleaseArtifact, etc). Worfklow objects represent states along the trajectory of editing and reference objects from the Application and Terminology worlds (mostly TrackingRecord).
Some principles:
- Eager fetching is rarely used
- Cascading is also rarely used, only for when objects are very tightly bound (like Translations and DescriptionTypes).
- Objects are generally doubly-linked (e.g. Refset accesses ConceptRefsetMembers which each know their Refset).
- The mapped superclass join strategy is always used - there are no cases of multiple object types within the same table.
Configuration
The JPA configuration is in the standard config.properties file.
Property | Default Value | |
|---|---|---|
| hibernate.dialect | org.hibernate.dialect.MySQLDialect | The default is MySQL though simply changing this should support other hibernate-supported environments. |
| javax.persistence.jdbc.driver | com.mysql.jdbc.Driver | JDBC driver, this requires the MySQL connector to be in the classpath |
| javax.persistence.jdbc.url | jdbc:mysql://127.0.0.1:3306/refset | Default connection URL to a "refset" database |
| javax.persistence.jdbc.user | n/a | MySQL user |
| javax.persistence.jdbc.password | n/a | MySQL user's password |
| hibernate.show_sql | false | Useful debug setting, change to "true" to see all queries executed by JPA layer. |
| hibernate.format_sql | true | Formats SQL when showing queries |
| hibernate.use_sql_comments | true | Add comments when showing SQL to explain what is happening. |
| hibernate.jdbc.batch_size | 500 | Batch size for bulk operations. |
| hibernate.jdbc.default_batch_fetch_size | 500 | Batch size for fetch operations. |
Annotations Used
Annotation | Explanation |
|---|---|
| @Column | Define columns, column names, and specifications about size and nullability. |
| @ElementCollection, @CollectionTable | Used to define collections of non JPA objects (like a set of String). |
| @Entity | Used to define JPA-tracked objects. |
| @Enumerated | Used to indicate fields that have enumerated values. |
| @id @GeneratedValue | Used to managed identifier fields and ID strategy. |
| @ManyToOne, @OneToOne, @OneToMany | Used to define object relationships between different @Entity annotated classes. |
| @MappedSuperclass | Used for abstract superclasses to indicate their fields should be included in persistence of concrete subclasses. |
| @OrderColumn | Used to enforce list order for tracking record authors/reviewers |
| @Table | Used to indicate table names for objects. Default underscore-based naming convention is used. |
| @Temporal | Used for date fields. |
| @Transient | Used to avoid persistence of fields, these are typically used for DTO fields as we reuse the objects for data transfer. |
| @UniqueConstraint | Used to index columns that would otherwise not have indexes. Not actually used for uniqueness. |