HHH-17014 - Complete "Mapping Maps" chapter of User Guide

https://hibernate.atlassian.net/browse/HHH-17014

documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc

@@ -204,10 +204,41 @@ instead.
 [[collections-map]]
 ==== Mapping Maps
 
-// todo (6.0) - finish
+A `java.util.Map` is a collection of key/value pairs.
 
+[[collection-map-ex]]
+.Simple MAP mapping
+====
+[source, JAVA, indent=0]
+----
+include::{example-dir-collection}/classification/map/EntityWithMap.java[tags=collections-map-ex]
+----
+====
 
+Hibernate has the ability to map sorted and ordered maps - the ordering and sorting applies
+to the Map key.  As we saw with Sets, the use of ordered Maps is generally discouraged.
 
+Maps may be sorted naturally -
+
+[[collection-sortedmap-natural-ex]]
+.Naturally sorted MAP mapping
+====
+[source, JAVA, indent=0]
+----
+include::{example-dir-collection}/classification/map/EntityWithNaturallySortedMap.java[tags=example]
+----
+====
+
+or via a Comparator -
+
+[[collection-sortedmap-ex]]
+.Comparator sorted MAP mapping
+====
+[source, JAVA, indent=0]
+----
+include::{example-dir-collection}/classification/map/EntityWithSortedMap.java[tags=example]
+----
+====
 
 
 

hibernate-core/src/test/java/org/hibernate/orm/test/mapping/collections/classification/Status.java

@@ -0,0 +1,16 @@
+/*
+ * 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.orm.test.mapping.collections.classification;
+
+/**
+ * @author Steve Ebersole
+ */
+public enum Status {
+	PENDING,
+	ACTIVE,
+	EXPIRED
+}

hibernate-core/src/test/java/org/hibernate/orm/test/mapping/collections/classification/map/EntityWithMap.java

@@ -0,0 +1,61 @@
+/*
+ * 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.orm.test.mapping.collections.classification.map; /**
+ * @author Steve Ebersole
+ */
+
+import java.util.Map;
+import java.util.Set;
+
+import org.hibernate.orm.test.mapping.collections.classification.Name;
+import org.hibernate.orm.test.mapping.collections.classification.Status;
+
+import jakarta.persistence.Basic;
+import jakarta.persistence.ElementCollection;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+
+//tag::collections-map-ex[]
+@Entity
+public class EntityWithMap {
+	// ...
+//end::collections-map-ex[]
+
+	@Id
+	private Integer id;
+	@Basic
+	private String name;
+
+	//tag::collections-map-ex[]
+	@ElementCollection
+	private Map<Name, Status> names;
+	//end::collections-map-ex[]
+
+	private EntityWithMap() {
+		// for Hibernate use
+	}
+
+	public EntityWithMap(Integer id, String name) {
+		this.id = id;
+		this.name = name;
+	}
+
+	public Integer getId() {
+		return id;
+	}
+
+	public String getName() {
+		return name;
+	}
+
+	public void setName(String name) {
+		this.name = name;
+	}
+
+//tag::collections-map-ex[]
+}
+//end::collections-map-ex[]

hibernate-core/src/test/java/org/hibernate/orm/test/mapping/collections/classification/map/EntityWithNaturallySortedMap.java

@@ -0,0 +1,63 @@
+/*
+ * 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.orm.test.mapping.collections.classification.map;
+
+import java.util.Map;
+import java.util.SortedSet;
+
+import org.hibernate.annotations.SortNatural;
+import org.hibernate.orm.test.mapping.collections.classification.Name;
+import org.hibernate.orm.test.mapping.collections.classification.Status;
+
+import jakarta.persistence.Basic;
+import jakarta.persistence.ElementCollection;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+
+/**
+ * @author Steve Ebersole
+ */
+//tag::example[]
+@Entity
+public class EntityWithNaturallySortedMap {
+	// ...
+//end::example[]
+
+	@Id
+	private Integer id;
+	@Basic
+	private String name;
+
+	//tag::example[]
+	@ElementCollection
+	@SortNatural
+	private Map<Name, Status> names;
+	//end::example[]
+
+	private EntityWithNaturallySortedMap() {
+		// for Hibernate use
+	}
+
+	public EntityWithNaturallySortedMap(Integer id, String name) {
+		this.id = id;
+		this.name = name;
+	}
+
+	public Integer getId() {
+		return id;
+	}
+
+	public String getName() {
+		return name;
+	}
+
+	public void setName(String name) {
+		this.name = name;
+	}
+//tag::example[]
+}
+//end::example[]

hibernate-core/src/test/java/org/hibernate/orm/test/mapping/collections/classification/map/EntityWithSortedMap.java

@@ -0,0 +1,63 @@
+/*
+ * 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.orm.test.mapping.collections.classification.map; /**
+ * @author Steve Ebersole
+ */
+
+import java.util.Map;
+import java.util.SortedSet;
+
+import org.hibernate.annotations.SortComparator;
+import org.hibernate.orm.test.mapping.collections.classification.Name;
+import org.hibernate.orm.test.mapping.collections.classification.NameComparator;
+import org.hibernate.orm.test.mapping.collections.classification.Status;
+
+import jakarta.persistence.Basic;
+import jakarta.persistence.ElementCollection;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+
+//tag::example[]
+@Entity
+public class EntityWithSortedMap {
+	// ...
+//end::example[]
+
+	@Id
+	private Integer id;
+	@Basic
+	private String name;
+
+	//tag::example[]
+	@ElementCollection
+	@SortComparator( NameComparator.class )
+	private Map<Name, Status> names;
+	//end::example[]
+
+	private EntityWithSortedMap() {
+		// for Hibernate use
+	}
+
+	public EntityWithSortedMap(Integer id, String name) {
+		this.id = id;
+		this.name = name;
+	}
+
+	public Integer getId() {
+		return id;
+	}
+
+	public String getName() {
+		return name;
+	}
+
+	public void setName(String name) {
+		this.name = name;
+	}
+//tag::example[]
+}
+//end::example[]