HHH-12479 - Document the converted:: prefix for HBM type mappings

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

@@ -2,6 +2,7 @@
 === Basic Types
 :modeldir: ../../../../../main/java/org/hibernate/userguide/model
 :sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping
+:resourcedir: ../../../../../test/resources/org/hibernate/userguide/
 :extrasdir: extras
 
 Basic value types usually map a single database column, to a single, non-aggregated Java type.
@@ -535,6 +536,59 @@ JPA explicitly disallows the use of an AttributeConverter with an attribute mark
 So if using the AttributeConverter approach, be sure not to mark the attribute as `@Enumerated`.
 ====
 
+[[basic-hbm-attribute-converter]]
+====== Mapping an AttributeConverter using HBM mappings
+
+When using HBM mappings, you can still make use of the JPA `AttributeConverter` because Hibernate supports
+such mapping via the `type` attribute as demonstrated by the following example.
+
+Let's consider we have an application-specific `Money` type:
+
+[[basic-hbm-attribute-converter-mapping-money-example]]
+.Application-specific `Money` type
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/converter/hbm/Money.java[tags=basic-hbm-attribute-converter-mapping-money-example]
+----
+====
+
+Now, we want to use the `Money` type when mapping the `Account` entity:
+
+[[basic-hbm-attribute-converter-mapping-account-example]]
+.`Account` entity using the `Money` type
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/converter/hbm/Account.java[tags=basic-hbm-attribute-converter-mapping-account-example]
+----
+====
+
+Since Hibernate has no knowledge how to persist the `Money` type, we could use a JPA `AttributeConverter`
+to transform the `Money` type as a `Long`. For this purpose, we are going to use the following
+`MoneyConverter` utility:
+
+[[basic-hbm-attribute-converter-mapping-moneyconverter-example]]
+.`MoneyConverter` implementing the JPA `AttributeConverter` interface
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/converter/hbm/MoneyConverter.java[tags=basic-hbm-attribute-converter-mapping-moneyconverter-example]
+----
+====
+
+To map the `MoneyConverter` using HBM configuration files you need to use the `converted::` prefix in the `type`
+attribute of the `property` element.
+
+[[basic-hbm-attribute-converter-mapping-xml-config-example]]
+.HBM mapping for `AttributeConverter`
+====
+[source, JAVA, indent=0]
+----
+include::{resourcedir}/mapping/converter/hbm/MoneyConverterHbmTest.hbm.xml[]
+----
+====
+
 [[basic-enums-custom-type]]
 ===== Custom type
 

documentation/src/test/java/org/hibernate/userguide/mapping/converter/MoneyConverterTest.java

@@ -1,25 +1,8 @@
 /*
  * Hibernate, Relational Persistence for Idiomatic Java
  *
- * Copyright (c) 2013, Red Hat Inc. or third-party contributors as
- * indicated by the @author tags or express copyright attribution
- * statements applied by the authors.  All third-party contributions are
- * distributed under license by Red Hat Inc.
- *
- * This copyrighted material is made available to anyone wishing to use, modify,
- * copy, or redistribute it subject to the terms and conditions of the GNU
- * Lesser General Public License, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
- * for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this distribution; if not, write to:
- * Free Software Foundation, Inc.
- * 51 Franklin Street, Fifth Floor
- * Boston, MA  02110-1301  USA
+ * 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.mapping.converter;
 

documentation/src/test/java/org/hibernate/userguide/mapping/converter/hbm/Account.java

@@ -0,0 +1,45 @@
+/*
+ * 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.mapping.converter.hbm;
+
+//tag::basic-hbm-attribute-converter-mapping-account-example[]
+public class Account {
+
+    private Long id;
+
+    private String owner;
+
+    private Money balance;
+
+    //Getters and setters are omitted for brevity
+    //end::basic-hbm-attribute-converter-mapping-account-example[]
+    public Long getId() {
+        return id;
+    }
+
+    public void setId(Long id) {
+        this.id = id;
+    }
+
+    public String getOwner() {
+        return owner;
+    }
+
+    public void setOwner(String owner) {
+        this.owner = owner;
+    }
+
+    public Money getBalance() {
+        return balance;
+    }
+
+    public void setBalance(Money balance) {
+        this.balance = balance;
+    }
+//tag::basic-hbm-attribute-converter-mapping-account-example[]
+}
+//end::basic-hbm-attribute-converter-mapping-account-example[]

documentation/src/test/java/org/hibernate/userguide/mapping/converter/hbm/Money.java

@@ -0,0 +1,26 @@
+/*
+ * 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.mapping.converter.hbm;
+
+//tag::basic-hbm-attribute-converter-mapping-money-example[]
+public class Money {
+
+    private long cents;
+
+    public Money(long cents) {
+        this.cents = cents;
+    }
+
+    public long getCents() {
+        return cents;
+    }
+
+    public void setCents(long cents) {
+        this.cents = cents;
+    }
+}
+//end::basic-hbm-attribute-converter-mapping-money-example[]

documentation/src/test/java/org/hibernate/userguide/mapping/converter/hbm/MoneyConverter.java

@@ -0,0 +1,25 @@
+/*
+ * 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.mapping.converter.hbm;
+
+import javax.persistence.AttributeConverter;
+
+//tag::basic-hbm-attribute-converter-mapping-moneyconverter-example[]
+public class MoneyConverter
+        implements AttributeConverter<Money, Long> {
+
+    @Override
+    public Long convertToDatabaseColumn(Money attribute) {
+        return attribute == null ? null : attribute.getCents();
+    }
+
+    @Override
+    public Money convertToEntityAttribute(Long dbData) {
+        return dbData == null ? null : new Money( dbData );
+    }
+}
+//end::basic-hbm-attribute-converter-mapping-moneyconverter-example[]

documentation/src/test/java/org/hibernate/userguide/mapping/converter/hbm/MoneyConverterHbmTest.java

@@ -0,0 +1,47 @@
+/*
+ * 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.mapping.converter.hbm;
+
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+
+import org.junit.Test;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+
+/**
+ * @author Vlad Mihalcea
+ */
+public class MoneyConverterHbmTest extends BaseEntityManagerFunctionalTestCase {
+
+	@Test
+	public void testConverterMutability() {
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			Account account = new Account();
+			account.setId( 1L );
+			account.setOwner( "John Doe" );
+			account.setBalance( new Money( 250 * 100L ) );
+
+			entityManager.persist( account );
+		} );
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			//tag::basic-hbm-convert-money-converter-mutability-plan-example[]
+			Account account = entityManager.find( Account.class, 1L );
+			account.getBalance().setCents( 150 * 100L );
+			entityManager.persist( account );
+			//end::basic-hbm-convert-money-converter-mutability-plan-example[]
+		} );
+	}
+
+	@Override
+	protected String[] getMappings() {
+		return new String[] {
+				"org/hibernate/userguide/mapping/converter/hbm/MoneyConverterHbmTest.hbm.xml"
+		};
+	}
+}

documentation/src/test/resources/org/hibernate/userguide/mapping/converter/hbm/MoneyConverterHbmTest.hbm.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0"?>
+<!DOCTYPE hibernate-mapping PUBLIC
+        "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
+        "http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">
+
+<hibernate-mapping package="org.hibernate.userguide.mapping.converter.hbm">
+    <class name="Account" table="account" >
+        <id name="id"/>
+
+        <property name="owner"/>
+
+        <property name="balance"
+            type="converted::org.hibernate.userguide.mapping.converter.hbm.MoneyConverter"/>
+        
+    </class>
+</hibernate-mapping>