From b6e9e06f20da682aac8532650eee2144baea58d7 Mon Sep 17 00:00:00 2001
From: Lukas Eder <lukas.eder@gmail.com>
Date: Sun, 12 Aug 2012 11:37:00 +0200
Subject: [PATCH] [#1704] Document the behaviour of Factory.newRecord(Table<?>,
 Object), and Record.from(Object) with respect to UpdatableRecord.store()

---
 jOOQ/src/main/java/org/jooq/FactoryOperations.java | 6 ++++++
 jOOQ/src/main/java/org/jooq/Record.java            | 7 +++++++
 2 files changed, 13 insertions(+)

diff --git a/jOOQ/src/main/java/org/jooq/FactoryOperations.java b/jOOQ/src/main/java/org/jooq/FactoryOperations.java
index fa1a5a2f9d..358d405c75 100644
--- a/jOOQ/src/main/java/org/jooq/FactoryOperations.java
+++ b/jOOQ/src/main/java/org/jooq/FactoryOperations.java
@@ -966,6 +966,12 @@ public interface FactoryOperations extends Configuration {
      * <p>
      * This performs roughly the inverse operation of {@link Record#into(Class)}
      * <p>
+     * The resulting record will have its internal "changed" flags set to true
+     * for all values. This means that {@link UpdatableRecord#store()} will
+     * perform an <code>INSERT</code> statement. If you wish to store the record
+     * using an <code>UPDATE</code> statement, use
+     * {@link #executeUpdate(UpdatableRecord)} instead.
+     * <p>
      * The resulting record is attached to this {@link Configuration} by
      * default. Use {@link Settings#isAttachRecords()} to override this
      * behaviour.
diff --git a/jOOQ/src/main/java/org/jooq/Record.java b/jOOQ/src/main/java/org/jooq/Record.java
index a38995df78..abc2a88c21 100644
--- a/jOOQ/src/main/java/org/jooq/Record.java
+++ b/jOOQ/src/main/java/org/jooq/Record.java
@@ -49,6 +49,7 @@ import javax.persistence.Column;
 
 import org.jooq.exception.DataTypeException;
 import org.jooq.exception.MappingException;
+import org.jooq.impl.Factory;
 import org.jooq.tools.Convert;
 import org.jooq.tools.reflect.Reflect;
 
@@ -1275,6 +1276,12 @@ public interface Record extends FieldProvider, Store<Object> {
      * <ul>
      * <li>primitive types are supported.</li>
      * </ul>
+     * <h3>General notes</h3>
+     * The resulting record will have its internal "changed" flags set to true
+     * for all values. This means that {@link UpdatableRecord#store()} will
+     * perform an <code>INSERT</code> statement. If you wish to store the record
+     * using an <code>UPDATE</code> statement, use
+     * {@link Factory#executeUpdate(UpdatableRecord)} instead.
      *
      * @param source The source object to copy data from
      * @throws MappingException wrapping any reflection exception that might