Documentation for "Large Objects" and the MAX_LENGTH_INPLACE_LOB setting is inconsistent with current code

Reviewing the trunk source on May, 10 2013 I found:

- in `src/main/org/h2/engine/Constants.java`, lines 198-208:

>   /**
>     * The default maximum length of an LOB that is stored in the database 
file.
>     */
>    public static final int DEFAULT_MAX_LENGTH_INPLACE_LOB = 4096;
>
>    /**
>     * The default maximum length of an LOB that is stored with the record 
itself,
>     * and not in a separate place.
>     * Only used if h2.lobInDatabase is enabled.
>     */
>    public static final int DEFAULT_MAX_LENGTH_INPLACE_LOB2 = 128;

- in `src/main/org/h2/constant/SysProperties.java`, line 195:

>    public static final boolean LOB_IN_DATABASE = 
Utils.getProperty("h2.lobInDatabase", true);

Thus, by default in h2-1.3.171, MAX_LENGTH_INPLACE_LOB setting is 128. The 
documentation states that value is equal to 1024. According to 
`src/docsrc/help/help.csv`, line 1271:

>    Sets the maximum size of an in-place LOB object. LOB objects larger that 
this
>    size are stored in a separate file, otherwise stored directly in the 
database
>    (in-place). The default max size is 1024.

This is inconsistent with what I see in the code. H2 1.3 seems to store lobs in 
a database regardless of their sizes, unless the `h2.lobInDatabase` system 
property is set to `false`. The MAX_LENGTH_INPLACE_LOB only seems to affect the 
strategy used for space allocation within the database. I suggest the following 
replacement text:

<    Sets the maximum size of a LOB object stored in-place. 
<    Since version 1.3, H2 stores all LOBs in the database unless
<    <a 
href="../docs/javadoc/org/h2/constant/SysProperties.html#h2.lobInDatabase">
<    <code>h2.lobInDatabase</code> system property</a> is set to 
<code>false</code>.
<    When that property is set to <code>false</code>, LOBs larger than this 
threshold
<    are stored in separate files. The default maximum size in that mode is 
4096.

Also note in 'src/docsrc/html/advanced.html', line 133:

>    This database stores large LOB (CLOB and BLOB) objects as separate files.

That is no longer true under the default settings. Large LOBs are stored in a 
special hidden table in the database. One possible correction would be:

<    This database stores large LOBs separately from the tables that contain 
them.
<    The exact storage strategy depends on the 
<    <a 
href="../docs/javadoc/org/h2/constant/SysProperties.html#h2.lobInDatabase">
<    <code>h2.lobInDatabase</code> system property</a> setting.

Original issue reported on code.google.com by h...@data-bag.org on 11 May 2013 at 4:05

kashipai / h2database

Documentation for "Large Objects" and the MAX_LENGTH_INPLACE_LOB setting is inconsistent with current code #459