Merge branch 'master' into ObsoleteMultiQuery

Author: fredericDelaporte

doc/reference/modules/basic_mapping.xml

@@ -3982,12 +3982,11 @@
             </para>
 
             <para>
-                The <literal>ICompositeUserType</literal>, <literal>IEnhancedUserType</literal>,
-                <literal>INullableUserType</literal>, <literal>IUserCollectionType</literal>,
-                and <literal>IUserVersionType</literal> interfaces provide support for more specialized
-                uses.
+                The <literal>IEnhancedUserType</literal>, <literal>IUserVersionType</literal>,
+                and <literal>IUserCollectionType</literal> interfaces provide support for more specialized
+                uses. The later is to be used with collections, see <xref linkend="collections-persistent" />.
             </para>
-            
+
             <para>
                 You may even supply parameters to an <literal>IUserType</literal> in the mapping file. To
                 do this, your <literal>IUserType</literal> must implement the

doc/reference/modules/performance.xml

@@ -1405,4 +1405,67 @@ var items = list.GetEnumerable();]]></programlisting>
         </para>
 
     </sect1>
+
+     <sect1 id="performance-future">
+        <title>Future results</title>
+
+        <para>
+            Queries can be converted to future results instead of being directly executed. Future
+            results are not evaluated till one gets executed. At that point, all defined future
+            results are evaluated in one single round-trip to the database.
+        </para>
+
+        <para>
+            Future results are an alternative to using <xref linkend="performance-multi-query"/>.
+            They avoid the need to explicitly regroup queries, but they also hide which queries will
+            get executed: any pending future results of the session will be batched together, no
+            matter where they were defined, included out-of-scope pending future results.
+        </para>
+
+        <para>
+            Future results are obtained by calling <literal>Future</literal> or
+            <literal>FutureValue</literal> methods of a HQL, Criteria, QueryOver or SQL query.
+            For LINQ queries, the methods are named <literal>ToFuture</literal> and
+            <literal>ToFutureValue</literal>, see <xref linkend="querylinq-futureresults"/> for
+            an example.
+        </para>
+
+        <programlisting><![CDATA[// Define queries
+IFutureEnumerable<Cat> cats =
+    session.CreateQuery("from Cat c where c.Color = :color")
+        .SetString("color", "black")
+        .Future();
+IFutureValue<int> catCount =
+    session.QueryOver<Cat>()
+        .ToRowCountQuery()
+        .FutureValue<int>();
+// Execute them
+foreach(Cat cat in cats.GetEnumerable())
+{
+    // Do something
+}
+if (catCount.Value > 10)
+{
+    // Do something
+}
+]]></programlisting>
+
+        <para>
+            In the above example, accessing <literal>catCount.Value</literal> does not trigger a round-trip
+            to the database: it has been evaluated with <literal>cats.GetEnumerable()</literal> call. If
+            instead <literal>catCount.Value</literal> was accessed first, it would have executed both
+            future results and <literal>cats.GetEnumerable()</literal> would not have triggered a round-trip
+            to the database.
+        </para>
+
+        <para>
+            As showcased in the previous example, <literal>Future</literal> allows to get a future enumerable
+            result, and <literal>FutureValue</literal> is meant to obtain a single value result.
+        </para>
+
+        <para>
+            Note: in NHibernate v5.1 and previous versions, Criteria/QueryOver future results were batched
+            separately. Since NHibernate v5.2, they are batched with other querying API future results.
+        </para>
+    </sect1>
 </chapter>

doc/reference/modules/query_linq.xml

@@ -425,7 +425,7 @@ using NHibernate.Linq;]]></programlisting>
 
     <para>
       Future results are supported by the Linq provider. They are not evaluated till one gets executed.
-      At that point, all defined future results are evaluated in one single round-trip to database.
+      At that point, all defined future results are evaluated in one single round-trip to the database.
     </para>
     <programlisting><![CDATA[// Define queries
 IFutureEnumerable<Cat> cats =
@@ -446,10 +446,7 @@ if (catCount.Value > 10)
 }
 ]]></programlisting>
     <para>
-      In above example, accessing <literal>catCount.Value</literal> does not trigger a round-trip to database:
-      it has been evaluated with <literal>cats.GetEnumerable()</literal> call. If instead
-      <literal>catCount.Value</literal> was accessed first, it would have executed both future and
-      <literal>cats.GetEnumerable()</literal> would have not trigger a round-trip to database.
+      See <xref linkend="performance-future" /> for more information.
     </para>
   </sect1>
 

src/NHibernate/UserTypes/ICompositeUserType.cs

@@ -9,19 +9,22 @@ namespace NHibernate.UserTypes
 	/// A UserType that may be dereferenced in a query.
 	/// This interface allows a custom type to define "properties".
 	/// These need not necessarily correspond to physical .NET style properties.
-	///
-	/// A ICompositeUserType may be used in almost every way
+	/// </summary>
+	/// <remarks>
+	/// <para>
+	/// An <c>ICompositeUserType</c> may be used in almost every way
 	/// that a component may be used. It may even contain many-to-one
 	/// associations.
-	///
-	/// Implementors must be immutable and must declare a public
-	/// default constructor.
-	///
-	/// Unlike UserType, cacheability does not depend upon
-	/// serializability. Instead, Assemble() and
-	/// Disassemble() provide conversion to/from a cacheable
+	/// </para>
+	/// <para>
+	/// Implementors must declare a public default constructor.
+	/// </para>
+	/// <para>
+	/// For ensuring cacheability, <see cref="Assemble" /> and
+	/// <see cref="Disassemble" /> must provide conversion to/from a cacheable
 	/// representation.
-	/// </summary>
+	/// </para>
+	/// </remarks>
 	public interface ICompositeUserType
 	{
 		/// <summary>
@@ -135,4 +138,4 @@ public interface ICompositeUserType
 		/// </summary>
 		object Replace(object original, object target, ISessionImplementor session, object owner);
 	}
-}
+}

src/NHibernate/UserTypes/IEnhancedUserType.cs

@@ -4,7 +4,7 @@ namespace NHibernate.UserTypes
 {
 	/// <summary>
 	/// A custom type that may function as an identifier or discriminator
-	/// type, or may be marshalled to and from an XML document.
+	/// type.
 	/// </summary>
 	public interface IEnhancedUserType : IUserType
 	{

src/NHibernate/UserTypes/ILoggableUserType.cs

@@ -1,3 +1,4 @@
+using System;
 using NHibernate.Engine;
 
 namespace NHibernate.UserTypes
@@ -6,6 +7,8 @@ namespace NHibernate.UserTypes
 	/// Marker interface for user types which want to perform custom
 	/// logging of their corresponding values 
 	/// </summary>
+	// Since 5.2
+	[Obsolete("This interface has no usage and will be removed in a future version")]
 	public interface ILoggableUserType
 	{
 		/// <summary> Generate a loggable string representation of the collection (value). </summary>

src/NHibernate/UserTypes/IUserType.cs

@@ -10,19 +10,23 @@ namespace NHibernate.UserTypes
 	/// <remarks>
 	/// <para>
 	/// The interface abstracts user code from future changes to the <see cref="Type.IType"/> interface,
-	/// simplifies the implementation of custom types and hides certain "internal interfaces from
+	/// simplifies the implementation of custom types and hides certain "internal interfaces" from
 	/// user code.
 	/// </para>
 	/// <para>
-	/// Implementers must be immutable and must declare a public default constructor.
+	/// Implementers must declare a public default constructor.
 	/// </para>
 	/// <para>
-	/// The actual class mapped by a <c>IUserType</c> may be just about anything. However, if it is to
-	/// be cacheble by a persistent cache, it must be serializable.
+	/// The actual class mapped by a <c>IUserType</c> may be just about anything.
+	/// </para>
+	/// <para>
+	/// For ensuring cacheability, <see cref="Assemble" /> and
+	/// <see cref="Disassemble" /> must provide conversion to/from a cacheable
+	/// representation.
 	/// </para>
 	/// <para>
 	/// Alternatively, custom types could implement <see cref="Type.IType"/> directly or extend one of the
-	/// abstract classes in <c>NHibernate.Type</c>. This approach risks future incompatible changes
+	/// abstract classes in <c>NHibernate.Type</c>. This approach risks more future incompatible changes
 	/// to classes or interfaces in the package.
 	/// </para>
 	/// </remarks>