Skip to content

Commit fe3d8ac

Browse files
sebersolesebersole
committed
migration guide work
1 parent 856a001 commit fe3d8ac

File tree

1 file changed

+86
-88
lines changed

1 file changed

+86
-88
lines changed

‎migration-guide.adoc

Lines changed: 86 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ For many years Hibernate has used the Hibernate Commons Annotations (HCANN) libr
4141
related to understanding the structure of an application domain model, reading annotations and weaving in XML
4242
mapping documents.
4343

44-
However, HCANN suffers from a number of limitations that continue to be problematic. And given
44+
However, HCANN suffers from a number of limitations that continued to be problematic. And given
4545
the use of HCANN across multiple projects, doing the needed refactoring was simply not possible.
4646

4747
The https://github.com/hibernate/hibernate-models[Hibernate Models] project was developed to be a better alternative
@@ -50,16 +50,16 @@ annotations. Check out its project page for complete details.
5050

5151
7.0 uses Hibernate Models in place of HCANN.
5252

53-
NOTE: Currently, the `hibernate-envers` module still uses HCANN. That will change during continued 7.0 development.
53+
NOTE: Currently, the `hibernate-envers` module still uses HCANN. That will change during continued 7.x development.
5454

5555

5656

57-
[[annotation-validation]]
58-
== Annotation Validations
57+
[[model-validation]]
58+
== Domain Model Validations
5959

6060
7.0 adds many more checks about illegal use of annotations.
6161

62-
62+
[[PersistentAttributeType]]
6363
=== PersistentAttributeType
6464

6565
As of 7.0, Hibernate applies much better validation of an attribute specifying multiple PersistentAttributeTypes.
@@ -100,9 +100,74 @@ class Book {
100100
// previously ignored, this is an error now
101101
@Column(name="category")
102102
String getType() { ... }
103+
}
104+
----
105+
106+
[[java-beans]]
107+
=== JavaBean Conventions
108+
109+
Previous versions allowed some questionable (at best) attribute naming patterns. These are no longer supported. E.g.
110+
111+
[source,java]
112+
----
113+
@Basic
114+
String isDefault();
115+
----
116+
117+
118+
119+
[[flush-persist]]
120+
== Session flush and persist
121+
122+
The removal of `CascadeType.SAVE_UPDATE` slightly changes the persist and flush behaviour to conform with Jakarta Persistence.
123+
124+
Persisting a transient entity or flushing a manged entity with an associated detached entity having the association annotated with `cascade = CascadeType.ALL` or `cascade = CascadeType.PERSIST` throws now an `jakarta.persistence.EntityExistsException` if the detached entity has not been re-associated with the Session.
125+
126+
To re-associate the detached entity with the Session the `Session#merge` method can be used.
127+
128+
Consider the following model
129+
130+
[source,java]
131+
----
132+
@Entity
133+
class Parent {
134+
...
103135
104-
...
136+
@OneToMany(cascade = CascadeType.ALL, mappedBy = "parent", orphanRemoval = true)
137+
@LazyCollection(value = LazyCollectionOption.EXTRA)
138+
private Set<Child> children = new HashSet<>();
139+
140+
public void addChild(Child child) {
141+
children.add( child );
142+
child.setParent( this );
143+
}
105144
}
145+
146+
@Entity
147+
class Child {
148+
...
149+
150+
@ManyToOne
151+
private Parent parent;
152+
}
153+
----
154+
155+
Assuming we have `c1` as a detached `Child`, the following code will now result in `jakarta.persistence.EntityExistsException` being thrown at flush time:
156+
157+
[source,java]
158+
----
159+
Parent parent = session.get( Parent.class, parentId );
160+
parent.addChild( c1 );
161+
----
162+
163+
Instead, `c1` must first be re-associated with the Session using merge:
164+
165+
166+
[source,java]
167+
----
168+
Parent parent = session.get( Parent.class, parentId );
169+
Child merged = session.merge( c1 );
170+
parent.addChild( merged );
106171
----
107172

108173

@@ -123,36 +188,6 @@ as part of schema generation. 7.0 adds the same capability for enums mapped usi
123188
by asking the converter to convert all the enum constants on start up.
124189

125190

126-
[[java-beans]]
127-
== JavaBean Conventions
128-
129-
Previous versions allowed some questionable (at best) attribute naming patterns. These are no longer supported. E.g.
130-
131-
[source,java]
132-
----
133-
@Basic
134-
String isDefault();
135-
----
136-
137-
138-
139-
[[cleanup]]
140-
== Some Cleanup
141-
142-
* Removed `SqmQualifiedJoin`. All joins are qualified.
143-
* Removed `AdditionalJaxbMappingProducer`, deprecated in favor of `AdditionalMappingContributor`
144-
* Removed `MetadataContributor`, deprecated in favor of `AdditionalMappingContributor`
145-
* Removed `@Persister`.
146-
* Removed `hibernate.mapping.precedence` and friends
147-
* Removed `org.hibernate.Session#save(Object object)` and `org.hibernate.Session#save(String entityName, Object object)` in favor of `org.hibernate.Session#persist(Object object)` and `org.hibernate.Session#persist(String entityName, Object object)`
148-
* Removed `org.hibernate.Session#saveOrUpdate(Object object)` and `org.hibernate.Session#saveOrUpdate(String entityName, Object object)` in favor `persist` if the entity is transient or `merge` if the entity is detached.
149-
* Removed `org.hibernate.Session#update(Object object` and `org.hibernate.Session#update(String entityName, Object object)` in favor of `org.hibernate.Session.merge(T object)` and `org.hibernate.Session.merge(String entityName, T object)`
150-
* Removed `org.hibernate.annotations.CascadeType.SAVE_UPDATE` in favor of `org.hibernate.annotations.CascadeType.PERSIST` + `org.hibernate.annotations.CascadeType.MERGE`
151-
* Removed `@SelectBeforeUpdate`
152-
* Removed `org.hibernate.Session#delete(Object object)` and `org.hibernate.Session#delete(String entityName, Object object)` in favor of `org.hibernate.Session#remove(Object object)`
153-
* Removed `org.hibernate.annotations.CascadeType.DELETE` in favor of `org.hibernate.annotations.CascadeType#REMOVE`
154-
* Removed the attribute value from `@DynamicInsert` and `@DynamicUpdate`
155-
156191
[[ddl-implicit-datatype-timestamp]]
157192
== Default precision for timestamp on some databases
158193

@@ -194,61 +229,24 @@ one file at a time. This is now done across the entire set of `hbm.xml` files a
194229
While most users will never see this change, it might impact integrations which tie-in to
195230
XML processing.
196231

197-
[[flush-persist]]
198-
== Session flush and persist
199-
200-
The removal of `CascadeType.SAVE_UPDATE` slightly changes the persist and flush behaviour (not affecting application using `Entitymanager`) that now conforms with the Jakarta JPA specifications.
201-
202-
Persisting a transient entity or flushing a manged entity with an associated detached entity having the association annotated with `cascade = CascadeType.ALL` or `cascade = CascadeType.PERSIST` throws now an `jakarta.persistence.EntityExistsException` if the detached entity has not been re-associated with the the Session.
203-
204-
To re-associate the detached entity with the Session the `Session#merge` method can be used.
205-
206-
Consider the following model
207-
208-
```
209-
@Entity
210-
class Parent {
211-
212-
...
213-
214-
@OneToMany(cascade = CascadeType.ALL, mappedBy = "parent", orphanRemoval = true)
215-
@LazyCollection(value = LazyCollectionOption.EXTRA)
216-
private Set<Child> children = new HashSet<>();
217-
218-
public void addChild(Child child) {
219-
children.add( child );
220-
child.setParent( this );
221-
}
222-
}
223-
224-
@Entity
225-
class Child {
226-
227-
...
228232

229-
@Id
230-
@GeneratedValue(strategy = GenerationType.AUTO)
231-
private Long id;
232-
233-
@ManyToOne
234-
private Parent parent;
235-
}
236-
237-
```
238-
239-
Assuming we have c1 as a detached Child, the following code will now result in jakarta.persistence.EntityExistsException being thrown at flush time:
233+
[[cleanup]]
234+
== Cleanup
240235

241-
```
242-
Parent parent = session.get( Parent.class, parentId );
243-
parent.addChild( c1 );
244-
```
245-
Instead, c1 must first be re-associated with the Session using merge:
236+
* Removed `SqmQualifiedJoin`. All joins are qualified.
237+
* Removed `AdditionalJaxbMappingProducer`, deprecated in favor of `AdditionalMappingContributor`
238+
* Removed `MetadataContributor`, deprecated in favor of `AdditionalMappingContributor`
239+
* Removed `@Persister`.
240+
* Removed `hibernate.mapping.precedence` and friends
241+
* Removed `org.hibernate.Session#save` in favor of `org.hibernate.Session#persist`
242+
* Removed `org.hibernate.Session#saveOrUpdate` in favor `#persist` if the entity is transient or `#merge` if the entity is detached.
243+
* Removed `org.hibernate.Session#update` in favor of `org.hibernate.Session.merge`
244+
* Removed `org.hibernate.annotations.CascadeType.SAVE_UPDATE` in favor of `org.hibernate.annotations.CascadeType.PERSIST` + `org.hibernate.annotations.CascadeType.MERGE`
245+
* Removed `@SelectBeforeUpdate`
246+
* Removed `org.hibernate.Session#delete` in favor of `org.hibernate.Session#remove`
247+
* Removed `org.hibernate.annotations.CascadeType.DELETE` in favor of `org.hibernate.annotations.CascadeType#REMOVE`
248+
* Removed the attribute value from `@DynamicInsert` and `@DynamicUpdate`
246249

247-
```
248-
Parent parent = session.get( Parent.class, parentId );
249-
Child merged = session.merge( c1 );
250-
parent.addChild( merged );
251-
```
252250

253251
[[todo]]
254252
== Todos (dev)

0 commit comments

Comments
 (0)