NH-3488 - Documentation, modernizing tests, minor refactoring

 * C#7
 * White-spaces
 * Use of new ReflectionCache
 * ...

Author: fredericDelaporte

doc/reference/modules/batch.xml

@@ -133,7 +133,8 @@ session.Close();]]></programlisting>
             (DML) statements: <literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>)
             data directly in the database will not affect in-memory state. However, NHibernate provides methods
             for bulk SQL-style DML statement execution which are performed through the
-            Hibernate Query Language (<link linkend="queryhql">HQL</link>).
+            Hibernate Query Language (<link linkend="queryhql">HQL</link>). A
+            <link linkend="querylinq-modifying">Linq implementation</link> is available too.
         </para>
 
 	    <para>

doc/reference/modules/query_linq.xml

@@ -467,6 +467,101 @@ IList<Cat> oldCats =
         .ToList();]]></programlisting>
   </sect1>
 
+  <sect1 id="querylinq-modifying">
+    <title>Modifying entities inside the database</title>
+
+    <para>
+      Beginning with NHibernate 5.0, Linq queries can be used for inserting, updating or deleting entities.
+      The query defines the data to delete, update or insert, and then <literal>Delete</literal>,
+      <literal>Update</literal> and <literal>Insert</literal> queryable extension methods allow to delete it,
+      or instruct in which way it should updated or inserted. Those queries happen entirely inside the
+      database, without extracting corresponding entities out of the database.
+    </para>
+    <para>
+      These operations are a Linq implementation of <xref linkend="batch-direct" />, with the same abilities
+      and limitations.
+    </para>
+
+    <sect2 id="querylinq-modifying-insert">
+      <title>Inserting new entities</title>
+      <para>
+        <literal>Insert</literal> method extension expects a NHibernate queryable defining the data source of
+        the insert. This data can be entities or a projection. Then it allows specifying the target entity type
+        to insert, and how to convert source data to those target entities. Two forms of target specification
+        exist.
+      </para>
+      <para>
+        Using projection to target entity:
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Insert()
+    .As(c => new Dog { Name = c.Name + "dog", BodyWeight = c.BodyWeight });]]></programlisting>
+      <para>
+        Or using assignments:
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Insert()
+    .Into<Dog>(a => a
+        .Set(d => d.Name, c => c.Name + "dog")
+        .Set(d => d.BodyWeight, c => c.BodyWeight));]]></programlisting>
+      <para>
+        In both cases, unspecified properties are not included in the resulting SQL insert.
+        <link linkend="mapping-declaration-version"><literal>version</literal></link> and
+        <link linkend="mapping-declaration-timestamp"><literal>timestamp</literal></link> properties are
+        exceptions. If not specified, they are inserted with their <literal>seed</literal> value.
+      </para>
+      <para>
+        For more information on <literal>Insert</literal> limitations, please refer to
+        <xref linkend="batch-direct" />.
+      </para>
+    </sect2>
+
+    <sect2 id="querylinq-modifying-update">
+      <title>Updating entities</title>
+      <para>
+        <literal>Update</literal> method extension expects a queryable defining the entities to update.
+        Then it allows specifying which properties should be updated with which values. As for
+        <literal>Insert</literal>, two forms of target specification exist.
+      </para>
+      <para>
+        Using projection to updated entity:
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Update()
+    .As(c => new Cat { BodyWeight = c.BodyWeight / 2 });]]></programlisting>
+      <para>
+        Or using assignments:
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Update()
+    .Assign(a => a
+        .Set(c => c.BodyWeight, c => c.BodyWeight / 2));]]></programlisting>
+      <para>
+        In both cases, unspecified properties are not included in the resulting SQL update. This could
+        be changed for <link linkend="mapping-declaration-version"><literal>version</literal></link> and
+        <link linkend="mapping-declaration-timestamp"><literal>timestamp</literal></link> properties:
+        <literal>As</literal> and <literal>Assign</literal> methods take an optional boolean parameter,
+        <literal>versioned</literal>, which allows incrementing the version. Custom version types
+        (<literal>NHibernate.Usertype.IUserVersionType</literal>) are not supported.
+      </para>
+    </sect2>
+
+    <sect2 id="querylinq-modifying-delete">
+      <title>Deleting entities</title>
+      <para>
+        <literal>Delete</literal> method extension expects a queryable defining the entities to delete.
+        It immediately deletes them.
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Delete();]]></programlisting>
+    </sect2>
+  </sect1>
+
   <sect1 id="querylinq-querycache">
     <title>Query cache</title>