HHH-9998 - Continue documentation TLC - mapping basic-types

documentation/src/main/docbook/manual/en-US/chapters/domain/DomainModel.xml

@@ -34,8 +34,8 @@
     <para>
         This chapter will describe the characteristics of a persistable domain model.  However, it will not discuss
         defining the mapping for the domain model.  That is a massive topic in its own right and is the subject of an
-        entire dedicated manual.  See the <citetitle>Hibernate - Domain Model Mapping</citetitle> documentation
-        from the <link xlink:href="http://hibernate.org/documentation">documentation site</link>.
+        entire dedicated manual.  See the <citetitle>Hibernate Domain Model Mapping Guide</citetitle> from the
+        <link xlink:href="http://hibernate.org/documentation">documentation site</link>.
     </para>
 
     <section xml:id="domainmodel-pojo">

documentation/src/main/docbook/mapping/en-US/Hibernate_Mapping.xml

@@ -48,17 +48,26 @@
     <xi:include href="chapters/basic/Basic_Types.xml" />
     <xi:include href="chapters/composition/Composition.xml" />
     <xi:include href="chapters/collection/Collection.xml" />
+    <xi:include href="chapters/entity/Entity.xml" />
+    <xi:include href="chapters/id/Identifiers.xml" />
+    <xi:include href="chapters/natural_id/Natural_Id.xml" />
 
     <!--
-        <xi:include href="chapters/entity/Entity.xml" />
-        <xi:include href="chapters/id/Identifiers.xml" />
         <xi:include href="chapters/association/Associations.xml" />
-        <xi:include href="chapters/natural_id/Natural_Id.xml" />
+        <xi:include href="chapters/secondary/Secondary_Tables.xml" />
+
+        <xi:include href="chapters/constraints/Database_Constraints.xml" /> pk, fk, index, check, unique
+        <xi:include href="chapters/auxiliary/Auxiliary_DB_Objects.xml" />
 
-        <xi:include href="chapters/generation/Generated_attributes.xml" />
         <xi:include href="chapters/access/Attribute_Access.xml" />
         <xi:include href="chapters/overrides/Mapping_Overrides.xml" /> AttributeOverrides/AssociationOverrides
+
+        <xi:include href="chapters/generation/Generated_attributes.xml" />
+
+        columns, formulas, read/write-fragments
+
         <xi:include href="chapters/naming/Naming_Strategies.xml" />
+        <xi:include href="chapters/quoting/SQL_Identifier_Quoting.xml" />
     -->
 
     <!-- appendices? -->

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/Blob.sql

@@ -0,0 +1,5 @@
+create table step(
+	...
+	instruction BLOB not null,
+	...
+)

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/BlobLocator.java

@@ -0,0 +1,8 @@
+@Entity
+public class Step {
+	...
+	@Lob
+	@Basic
+	public Blob instructions;
+	...
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/BlobMaterialized.java

@@ -0,0 +1,8 @@
+@Entity
+public class Step {
+	...
+	@Lob
+	@Basic
+	public byte[] instructions;
+	...
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/Clob.sql

@@ -0,0 +1,5 @@
+create table product(
+	...
+	description CLOB not null,
+	...
+)

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/ClobLocator.java

@@ -0,0 +1,8 @@
+@Entity
+public class Product {
+	...
+	@Lob
+	@Basic
+	public Clob description;
+	...
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/ClobMaterialized.java

@@ -0,0 +1,8 @@
+@Entity
+public class Product {
+	...
+	@Lob
+	@Basic
+	public String description;
+	...
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/ClobMaterializedCharArray.java

@@ -0,0 +1,8 @@
+@Entity
+public class Product {
+	...
+	@Lob
+	@Basic
+	public char[] description;
+	...
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/EnumAttributeConverter.java

@@ -0,0 +1,53 @@
+@Entity
+public class Person {
+	...
+	@Basic
+	@Convert( converter=GenderConverter.class )
+	public Gender gender;
+}
+
+public enum Gender {
+	MALE( 'M' ),
+	FEMALE( 'F' );
+
+	private final char code;
+
+	private Gender(char code) {
+		this.code = code;
+	}
+
+	public char getCode() {
+		return code;
+	}
+
+	public static Gender fromCode(char code) {
+		if ( code == 'M' || code == 'm' ) {
+			return MALE;
+		}
+		if ( code == 'F' || code == 'f' ) {
+			return FEMALE;
+		}
+		throw ...
+	}
+}
+
+@Converter
+public class GenderConverter
+		implements AttributeConverter<Character,Gender> {
+
+	public Character convertToDatabaseColumn(Gender value) {
+		if ( value == null ) {
+			return null;
+		}
+
+		return value.getCode();
+	}
+
+	public Gender convertToEntityAttribute(Character value) {
+		if ( value == null ) {
+			return null;
+		}
+
+		return Gender.fromCode( value );
+	}
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/EnumCustomType.java

@@ -0,0 +1,82 @@
+import org.hibernate.type.descriptor.java.CharacterTypeDescriptor;
+
+@Entity
+public class Person {
+	...
+	@Basic
+	@Type( type = GenderType.class )
+	public Gender gender;
+}
+
+public enum Gender {
+	MALE( 'M' ),
+	FEMALE( 'F' );
+
+	private final char code;
+
+	private Gender(char code) {
+		this.code = code;
+	}
+
+	public char getCode() {
+		return code;
+	}
+
+	public static Gender fromCode(char code) {
+		if ( code == 'M' || code == 'm' ) {
+			return MALE;
+		}
+		if ( code == 'F' || code == 'f' ) {
+			return FEMALE;
+		}
+		throw ...
+	}
+}
+
+@Converter
+public class GenderType
+		extends AbstractSingleColumnStandardBasicType<Gender> {
+
+	public static final GenderType INSTANCE = new GenderType();
+
+	private GenderType() {
+		super(
+				CharTypeDescriptor.INSTANCE,
+				GenderJavaTypeDescriptor.INSTANCE
+		);
+	}
+
+	public String getName() {
+		return "gender";
+	}
+
+	@Override
+	protected boolean registerUnderJavaType() {
+		return true;
+	}
+}
+
+public static class GenderJavaTypeDescriptor
+		extends AbstractTypeDescriptor<Gender> {
+	public static final GenderJavaTypeDescriptor INSTANCE = new GenderJavaTypeDescriptor();
+
+	public String toString(Gender value) {
+		return value == null ? null : value.name();
+	}
+
+	public Gender fromString(String string) {
+		return string == null ? null : Gender.valueOf( string );
+	}
+
+	public <X> X unwrap(Gender value, Class<X> type, WrapperOptions options) {
+		return CharacterTypeDescriptor.INSTANCE.unwrap(
+				value == null ? null : value.getCode(),
+				type,
+				options
+		);
+	}
+
+	public <X> Gender wrap(X value, WrapperOptions options) {
+		return CharacterTypeDescriptor.INSTANCE.wrap( value, options );
+	}
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/EnumeratedOrdinal.java

@@ -0,0 +1,11 @@
+@Entity
+public class Person {
+	...
+	@Enumerated
+	public Gender gender;
+
+	public static enum Gender {
+		MALE,
+		FEMALE
+	}
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/EnumeratedString.java

@@ -0,0 +1,11 @@
+@Entity
+public class Person {
+	...
+	@Enumerated(STRING)
+	public Gender gender;
+
+	public static enum Gender {
+		MALE,
+		FEMALE
+	}
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/ExplicitColumnNaming.java

@@ -0,0 +1,13 @@
+@Entity
+public class Product {
+	@Id
+	@Basic
+	private Integer id;
+	@Basic
+	private String sku;
+	@Basic
+	private String name;
+	@Basic
+	@Column( name = "NOTES" )
+	private String description;
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/NCLOB_locator.java

@@ -0,0 +1,12 @@
+@Entity
+public class Product {
+	...
+	@Lob
+	@Basic
+	@Nationalized
+	public NClob description;
+	// Clob also works, because NClob
+	// extends Clob.  The db type is
+	// still NCLOB either way and
+	// handled as such
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/NCLOB_materialized.java

@@ -0,0 +1,8 @@
+@Entity
+public class Product {
+	...
+	@Lob
+	@Basic
+	@Nationalized
+	public String description;
+}

documentation/src/main/docbook/mapping/en-US/chapters/basic/extras/NVARCHAR.java

@@ -0,0 +1,8 @@
+@Entity
+public class Product {
+	...
+	@Basic
+	@Nationalized
+	public String description;
+	...
+}

documentation/src/main/docbook/mapping/en-US/chapters/collection/Collection.xml

@@ -73,7 +73,7 @@
         <title>Bags</title>
         <para>
             <!-- todo : discuss mapping bags -->
-            todo : discuss mapping bags
+            todo : discuss mapping bags and idbags
         </para>
     </section>
 

documentation/src/main/docbook/mapping/en-US/chapters/entity/Entity.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ 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>.
+  -->
+<chapter xml:id="entity"
+         version="5.0"
+         xml:lang="en"
+         xmlns="http://docbook.org/ns/docbook"
+        >
+    <title>Entity</title>
+    <para>
+        * POJO, etc discussion from manual/en-US/chapters/domain/DomainModel.xml
+        * dynamic models (hbm.xml)
+            * Map mode
+            * proxy solutions (hibernate-core/src/test/java/org/hibernate/test/dynamicentity/tuplizer2)
+        * inheritance
+        * optimistic locking
+    </para>
+</chapter>