Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-11186 - Add examples for all Hibernate annotations 

Document more annotations:

- @CollectionType
This commit is contained in:
Vlad Mihalcea 2016-11-14 13:35:29 +02:00
parent b14e69089f
commit 6a6e0f2f6d
5 changed files with 336 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc
View File

@ -663,6 +663,8 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
The collection can also name a <<annotations-hibernate-type>>, which defines the Hibernate Type of the collection elements.
See the <<chapters/domain/collections.adoc#collections-custom,Custom collection types>> chapter for more info.
[[annotations-hibernate-columndefault]]
==== `@ColumnDefault`

43
documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc
View File

@ -626,3 +626,46 @@ include::{extrasdir}/collections-comma-delimited-collection-lifecycle-example.sq
====
See the Hibernate Integrations Guide for more details on developing custom value type mappings.
[[collections-custom]]
==== Custom collection types
If you wish to use other collection types than `List`, `Set` or ``Map`, like `Queue` for instance,
you have to use a custom collection type, as illustrated by the following example:
[[collections-custom-collection-mapping-example]]
.Custom collection mapping example
====
[source,java]
----
include::{sourcedir}/QueueTest.java[tags=collections-custom-collection-mapping-example,indent=0]
include::{sourcedir}/type/QueueType.java[tags=collections-custom-collection-mapping-example,indent=0]
include::{sourcedir}/type/PersistentQueue.java[tags=collections-custom-collection-mapping-example,indent=0]
----
====
[NOTE]
====
The reason why the `Queue` interface is not used for the entity attribute is because Hibernate only allows the following types:
- `java.util.List`
- `java.util.Set`
- `java.util.Map`
- `java.util.SortedSet`
- `java.util.SortedMap`
However, the custom collection type can still be customized as long as the base type is one of the aformentioned persistent types.
====
This way, the `Phone` collection can be used as a `java.util.Queue`:
[[collections-custom-collection-example]]
.Custom collection example
====
[source,java]
----
include::{sourcedir}/QueueTest.java[tags=collections-custom-collection-example,indent=0]
----
====

158
documentation/src/test/java/org/hibernate/userguide/collections/QueueTest.java Normal file
View File

@ -0,0 +1,158 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* License: GNU Lesser General Public License (LGPL), version 2.1 or later.
* See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
*/
package org.hibernate.userguide.collections;
import java.util.Collection;
import java.util.LinkedList;
import java.util.Objects;
import java.util.Queue;
import javax.persistence.CascadeType;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.OneToMany;
import org.hibernate.annotations.CollectionType;
import org.hibernate.annotations.NaturalId;
import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
import org.junit.Test;
import org.jboss.logging.Logger;
import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertSame;
/**
* @author Vlad Mihalcea
*/
public class QueueTest extends BaseEntityManagerFunctionalTestCase {
private static final Logger log = Logger.getLogger( QueueTest.class );
@Override
protected Class<?>[] getAnnotatedClasses() {
return new Class<?>[] {
Person.class,
Phone.class,
};
}
@Test
public void test() {
doInJPA( this::entityManagerFactory, entityManager -> {
Person person = new Person( 1L );
person.getPhones().add( new Phone( 1L, "landline", "028-234-9876" ) );
person.getPhones().add( new Phone( 2L, "mobile", "072-122-9876" ) );
entityManager.persist( person );
} );
doInJPA( this::entityManagerFactory, entityManager -> {
//tag::collections-custom-collection-example[]
Person person = entityManager.find( Person.class, 1L );
Queue<Phone> phones = person.getPhones();
Phone head = phones.peek();
assertSame(head, phones.poll());
assertEquals( 1, phones.size() );
//end::collections-custom-collection-example[]
} );
doInJPA( this::entityManagerFactory, entityManager -> {
Person person = entityManager.find( Person.class, 1L );
person.getPhones().clear();
} );
}
//tag::collections-custom-collection-mapping-example[]
@Entity(name = "Person")
public static class Person {
@Id
private Long id;
@OneToMany(cascade = CascadeType.ALL)
@CollectionType( type = "org.hibernate.userguide.collections.type.QueueType")
private Collection<Phone> phones = new LinkedList<>();
//Getters and setters are omitted for brevity
//end::collections-custom-collection-mapping-example[]
public Person() {
}
public Person(Long id) {
this.id = id;
}
public Queue<Phone> getPhones() {
return (Queue<Phone>) phones;
}
//tag::collections-custom-collection-mapping-example[]
}
@Entity(name = "Phone")
public static class Phone implements Comparable<Phone> {
@Id
private Long id;
private String type;
@NaturalId
@Column(name = "`number`")
private String number;
//Getters and setters are omitted for brevity
//end::collections-custom-collection-mapping-example[]
public Phone() {
}
public Phone(Long id, String type, String number) {
this.id = id;
this.type = type;
this.number = number;
}
public Long getId() {
return id;
}
public String getType() {
return type;
}
public String getNumber() {
return number;
}
@Override
public int compareTo(Phone o) {
return number.compareTo( o.getNumber() );
}
@Override
public boolean equals(Object o) {
if ( this == o ) {
return true;
}
if ( o == null || getClass() != o.getClass() ) {
return false;
}
Phone phone = (Phone) o;
return Objects.equals( number, phone.number );
}
@Override
public int hashCode() {
return Objects.hash( number );
}
//tag::collections-custom-collection-mapping-example[]
}
//end::collections-custom-collection-mapping-example[]
}

58
documentation/src/test/java/org/hibernate/userguide/collections/type/PersistentQueue.java Normal file
View File

@ -0,0 +1,58 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* License: GNU Lesser General Public License (LGPL), version 2.1 or later.
* See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
*/
package org.hibernate.userguide.collections.type;
import java.util.List;
import java.util.NoSuchElementException;
import java.util.Queue;
import org.hibernate.collection.internal.PersistentBag;
import org.hibernate.engine.spi.SharedSessionContractImplementor;
//tag::collections-custom-collection-mapping-example[]
public class PersistentQueue extends PersistentBag implements Queue {
public PersistentQueue(SharedSessionContractImplementor session) {
super( session );
}
public PersistentQueue(SharedSessionContractImplementor session, List list) {
super( session, list );
}
@Override
public boolean offer(Object o) {
return add(o);
}
@Override
public Object remove() {
return poll();
}
@Override
public Object poll() {
int size = size();
if(size > 0) {
Object first = get(0);
remove( 0 );
return first;
}
throw new NoSuchElementException();
}
@Override
public Object element() {
return peek();
}
@Override
public Object peek() {
return size() > 0 ? get( 0 ) : null;
}
}
//end::collections-custom-collection-mapping-example[]

75
documentation/src/test/java/org/hibernate/userguide/collections/type/QueueType.java Normal file
View File

@ -0,0 +1,75 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* License: GNU Lesser General Public License (LGPL), version 2.1 or later.
* See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
*/
package org.hibernate.userguide.collections.type;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.Queue;
import org.hibernate.HibernateException;
import org.hibernate.collection.spi.PersistentCollection;
import org.hibernate.engine.spi.SharedSessionContractImplementor;
import org.hibernate.persister.collection.CollectionPersister;
import org.hibernate.usertype.UserCollectionType;
//tag::collections-custom-collection-mapping-example[]
public class QueueType implements UserCollectionType {
@Override
public PersistentCollection instantiate(
SharedSessionContractImplementor session,
CollectionPersister persister) throws HibernateException {
return new PersistentQueue( session );
}
@Override
public PersistentCollection wrap(
SharedSessionContractImplementor session,
Object collection) {
return new PersistentQueue( session, (List) collection );
}
@Override
public Iterator getElementsIterator(Object collection) {
return ( (Queue) collection ).iterator();
}
@Override
public boolean contains(Object collection, Object entity) {
return ( (Queue) collection ).contains( entity );
}
@Override
public Object indexOf(Object collection, Object entity) {
int i = ( (List) collection ).indexOf( entity );
return ( i < 0 ) ? null : i;
}
@Override
public Object replaceElements(
Object original,
Object target,
CollectionPersister persister,
Object owner,
Map copyCache,
SharedSessionContractImplementor session)
throws HibernateException {
Queue result = (Queue) target;
result.clear();
result.addAll( (Queue) original );
return result;
}
@Override
public Object instantiate(int anticipatedSize) {
return new LinkedList<>();
}
}
//end::collections-custom-collection-mapping-example[]