CR-7022 OPENDJ-2013 Build without local-db-backend doc

Mark Craig

21.32.2015 f9b09a0664e59d101c6b922a0d34d165c3907b96

CR-7022 OPENDJ-2013 Build without local-db-backend doc

This patch uses conditional text to make it possible
to exclude elements related to the local-db-backend
from the hand-written documentation.

This patch does not address local-db-backend related content
in the generated reference documentation.
For the most part, that should be a by-product of changes
to OpenDJ directory server code, though there is one place
in the opendj-server-legacy POM that I've left a comment
regarding the need to avoid trying to build a man page for dbtest.

 opendj-doc-maven-plugin/src/main/java/org/forgerock/opendj/maven/doc/CommandLineTool.java

@@ -155,4 +155,23 @@
    public void setTrailingSectionPaths(final List<String> paths) {
        this.trailingSectionPaths = paths;
    }

    /** Whether the tool is enabled. Default: true. */
    private boolean enabled = true;

    /**
     * Returns true if the tool is enabled.
     * @return true if the tool is enabled.
     */
    public boolean getEnabled() {
        return enabled;
    }

    /**
     * Set to true if the tool is enabled, false otherwise.
     * @param enabled true if the tool is enabled, false otherwise.
     */
    public void setEnabled(final boolean enabled) {
        this.enabled = enabled;
    }
}

 opendj-doc-maven-plugin/src/main/java/org/forgerock/opendj/maven/doc/GenerateRefEntriesMojo.java

@@ -98,7 +98,9 @@
        // Prepare a ClassLoader capable of loading the command-line tools.
        final URLClassLoader toolsClassLoader = getBootToolsClassLoader();
        for (CommandLineTool tool : tools) {
            generateManPageForTool(toolsClassLoader, tool);
            if (tool.getEnabled()) {
                generateManPageForTool(toolsClassLoader, tool);
            }
        }
    }


 opendj-server-legacy/pom.xml

@@ -1610,6 +1610,9 @@
                       <trailingSectionPath>exit-codes-0-gt0.xml</trailingSectionPath>
                       <trailingSectionPath>dbtest-examples.xml</trailingSectionPath>
                     </trailingSectionPaths>
                     <!-- If no dbtest tool is provided, use this setting
                     <enabled>false</enabled>
                     -->
                    </tool>

                    <tool>
@@ -1958,6 +1961,13 @@
            <groupId>org.forgerock.commons</groupId>
            <artifactId>forgerock-doc-maven-plugin</artifactId>
            <inherited>false</inherited>
            <!-- Use conditional text to exclude local-db related elements in hand-written docs.
            <configuration>
              <exclusions>
                <condition>local-db</condition>
              </exclusions>
            </configuration>
            -->
            <executions>
              <execution>
                <id>build-doc</id>

 opendj-server-legacy/src/main/docbkx/admin-guide/chap-import-export.xml

@@ -418,11 +418,11 @@
   When you create a backend, choose the type of backend that fits your purpose.
  </para>

  <para>
  <para condition="local-db">
   The following example creates a local backend named <literal>testData</literal>.
  </para>

  <screen>
  <screen condition="local-db">
$ <userinput>dsconfig create-backend --backend-name testData --type local-db</userinput>

<computeroutput>
@@ -485,10 +485,6 @@
The Local DB Backend was created successfully</computeroutput>
  </screen>

  <para>Alternatively, you can create a new backend in OpenDJ Control Panel
  (Directory Data > New Base DN > Backend > New Backend:
  <replaceable>backend-name</replaceable>).</para>

  <para>
   The following example creates a <literal>persistit</literal> backend,
   which relies on a Persistit database for data storage and indexing.
@@ -537,6 +533,12 @@
writability-mode  : enabled</computeroutput>
  </screen>

  <para>
   Alternatively, you can create a new backend in OpenDJ Control Panel
   (Directory Data > New Base DN > Backend > New Backend:
   <replaceable>backend-name</replaceable>).
  </para>

  <xinclude:include href="../shared/informalexample-default-indexes.xml" />
 </section>

@@ -556,15 +558,8 @@
  </para>

  <para>
   Local database backends therefore have advanced properties,
   <link
    xlink:href="${configRefBase}/local-db-backend.html#disk-low-threshold"
    xlink:show="new"
   ><literal>disk-low-threshold</literal></link> and
   <link
    xlink:href="${configRefBase}/local-db-backend.html#disk-full-threshold"
    xlink:show="new"
   ><literal>disk-full-threshold</literal></link>.
   Database backends therefore have advanced properties,
   <literal>disk-low-threshold</literal> and <literal>disk-full-threshold</literal>.
   When available disk space falls below <literal>disk-low-threshold</literal>,
   OpenDJ server only allows updates from users and applications
   that have the privilege to

 opendj-server-legacy/src/main/docbkx/admin-guide/chap-indexing.xml

@@ -423,13 +423,13 @@
   <example xml:id="create-index-example">
    <title>Create a New Index</title>
    
    <para>
    <para condition="local-db">
     The following example creates a new substring index
     for the <literal>description</literal> attribute
     in a backend of type <literal>local-db</literal>.
    </para>
    
    <screen>
    <screen condition="local-db">
$ <userinput>dsconfig \
 create-local-db-index \
 --port 4444 \
@@ -472,13 +472,13 @@
     <secondary>Approximate</secondary>
    </indexterm>

    <para>
    <para condition="local-db">
     The following example configures an approximate index for
     the <literal>cn</literal> (common name) attribute
     in a backend of type <literal>local-db</literal>.
    </para>
    
    <screen>
    <screen condition="local-db">
$ <userinput>dsconfig \
 set-local-db-index-prop \
 --port 4444 \
@@ -525,14 +525,14 @@
    extensible matching rule indexes. Use the <command>dsconfig</command>
    command instead.</para>

    <para>
    <para condition="local-db">
     The following example configures an extensible matching rule index
     for "later than" and "earlier than" generalized time matching
     on a <literal>lastLoginTime</literal> attribute
     in a backend of type <literal>local-db</literal>.
    </para>

    <screen>
    <screen condition="local-db">
$ <userinput>dsconfig \
 create-local-db-index \
 --port 4444 \
@@ -604,11 +604,14 @@
   <para>
    You can also create the equivalent index configuration
    by using the <command>dsconfig</command> command.
   </para>

   <para condition="local-db">
    The following example shows how to create the VLV index
    for a backend of type <literal>local-db</literal>.
   </para>
   
   <screen>
   <screen condition="local-db">
$ <userinput>dsconfig \
 create-local-db-vlv-index \
 --port 4444 \
@@ -742,7 +745,7 @@
    is shown in the following example, where an index has just been created
    for <literal>newUnusedAttribute</literal>.</para>

    <para>
    <para condition="local-db">
     Start by testing the index status by using the
     <link
      xlink:show="new"
@@ -753,14 +756,7 @@
     <literal>false</literal> before the rebuild, <literal>true</literal> after.
    </para>

    <note>
     <para>
      The <command>dbtest list-index-status</command> command
      can take a long time to complete, as it reads all indexes for all backends.
     </para>
    </note>

    <screen>
    <screen condition="local-db">
$ <userinput>dbtest \
 list-index-status \
 --backendID userRoot \
@@ -769,7 +765,16 @@
<computeroutput>newUnusedAttribute.equality   Index  ...newUnusedAttribute.equality   false...
newUnusedAttribute.presence   Index  ...newUnusedAttribute.presence   false...
newUnusedAttribute.substring  Index  ...newUnusedAttribute.substring  false...</computeroutput>
    </screen>

    <note condition="local-db">
     <para>
      The <command>dbtest list-index-status</command> command
      can take a long time to complete, as it reads all indexes for all backends.
     </para>
    </note>

    <screen>
$ <userinput>rebuild-index \
 --port 4444 \
 --hostname opendj.example.com \
@@ -824,13 +829,18 @@
   
   <para>The default index entry limit value is 4000. 4000 is intended to be
   large enough for most index keys, though it prevents OpenDJ from maintaining
   indexes at any cost. You can use the <command>dbtest</command> command to
   evaluate how well attributes are indexed, and consider whether to change
   the index entry limit. Non-zero values in the "Undefined" column indicate
   the number of index keys that have reached the limit and are no longer
   maintained. The "Undefined keys" are then listed below.</para>
   indexes at any cost.
   </para>

   <informalexample><?dbfo pgwide="1"?>
   <para condition="local-db">
    Use the <command>dbtest</command> command to
    evaluate how well attributes are indexed, and consider whether to change
    the index entry limit. Non-zero values in the "Undefined" column indicate
    the number of index keys that have reached the limit and are no longer
    maintained. The "Undefined keys" are then listed below.
   </para>

   <informalexample condition="local-db"><?dbfo pgwide="1"?>
    <screen width="136">
$ <userinput>dbtest list-index-status --backendID userRoot --baseDN dc=example,dc=com</userinput>
<computeroutput>Index Name                 Index Type  JE Database Name                             Index Valid  Record Count  Undefined  95%  90%  85%
@@ -872,14 +882,14 @@
    </screen>
   </informalexample>

   <para>In this case (for a directory with only about 10,000 entries) the
   <para condition="local-db">In this case (for a directory with only about 10,000 entries) the
   list of undefined keys is perfectly reasonable. Every user entry has the
   object classes listed, and every user entry has a mail address ending in
   <literal>@maildomain.net</literal>, so those values are not specific enough
   to be used in search filters. The <literal>id2children</literal> and
   <literal>id2subtree</literal> are for OpenDJ's internal use.</para>

   <para>
   <para condition="local-db">
    For an explanation of the output
    of the <command>dbtest list-index-status</command> command, see
    <link xlink:show="new" xlink:href="reference#dbtest-1"
@@ -904,15 +914,13 @@
     production.</para>
    </important>

    <para>
    <para condition="local-db">
     The following example uses
     the <command>dsconfig set-local-db-index-prop</command> command,
     and works with a backend of type <literal>local-db</literal>.
     For other indexed backend types, use
     the <command>dsconfig set-backend-index-prop</command> command.
    </para>

    <screen>
    <screen condition="local-db">
$ <userinput>dsconfig \
 set-local-db-index-prop \
 --port 4444 \
@@ -935,6 +943,38 @@
 --start 0</userinput>
<computeroutput>Rebuild Index task 20110607160349596 scheduled to start Jun 7, 2011 4:03:49 PM</computeroutput>
    </screen>

    <para>
     The following example shows how to use
     the <command>dsconfig set-backend-index-prop</command> command
     to change the index entry limit
     for a backend of type <literal>persistit</literal>.
    </para>

    <screen>
$ <userinput>dsconfig \
 set-backend-index-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --index-name objectClass \
 --set index-entry-limit:5000 \
 --trustAll \
 --no-prompt</userinput>

$ <userinput>rebuild-index \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --baseDN dc=example,dc=com \
 --index objectclass \
 --start 0</userinput>
<computeroutput>Rebuild Index task 20150520135018932 scheduled to start May 20, 2015 1:50:18
PM CEST</computeroutput>
    </screen>
   </example>
   
   <para>Alternatively, you can configure the index entry limit for all
@@ -975,24 +1015,12 @@
 --index cn \
 --clean \
 --countErrors</userinput>
<computeroutput>[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
 msgID=9437595 msg=Local DB backend userRoot does not specify the number of
 lock tables: defaulting to 97
[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
 msgID=9437594 msg=Local DB backend userRoot does not specify the number of
 cleaner threads: defaulting to 24 threads
[07/Jun/2011:16:06:51 +0200] category=JEB severity=NOTICE msgID=8847461
 msg=Checked 1316 records and found 0 error(s) in 0 seconds
<computeroutput>...msg=Checked 1316 records and found 0 error(s) in 0 seconds
 (average rate 2506.7/sec)
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388710 msg=Number of records referencing more than one entry: 315
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388711 msg=Number of records that exceed the entry limit: 0
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388712 msg=Average number of entries referenced is 1.58/record
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388713 msg=Maximum number of entries referenced by any
 record is 32</computeroutput>
...msg=Number of records referencing more than one entry: 315
...msg=Number of records that exceed the entry limit: 0
...msg=Average number of entries referenced is 1.58/record
...msg=Maximum number of entries referenced by any record is 32</computeroutput>
   </screen>

   <para>Ignore the messages regarding lock tables and cleaner threads. The

 opendj-server-legacy/src/main/docbkx/admin-guide/chap-monitoring.xml

@@ -383,10 +383,10 @@
   <listitem>
    <para>The <firstterm>errors log</firstterm> traces server events, error
    conditions, and warnings, categorized and identified by severity.</para>
    <para>The following errors log excerpt shows log entries about a
    <para condition="local-db">The following errors log excerpt shows log entries about a
    backup task, with lines wrapped for readability.</para>

    <programlisting language="none">
    <programlisting language="none" condition="local-db">
[22/Jun/2011:12:32:23 +0200] category=BACKEND severity=NOTICE msgID=9896349
 msg=Backup task 20110622123224088 started execution
[22/Jun/2011:12:32:23 +0200] category=TOOLS severity=NOTICE msgID=10944792
@@ -886,7 +886,7 @@
     one or more ACI rules when the server first started.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
   <varlistentry condition="local-db">
    <term><literal>org.opends.server.BackendRunRecovery</literal></term>
    <listitem>
     <para>

 opendj-server-legacy/src/main/docbkx/admin-guide/chap-server-process.xml

@@ -277,12 +277,22 @@
  the server process is killed abruptly. OpenDJ might have to replay the last
  few entries in a transaction log. Generally OpenDJ returns to service
  quickly.</para>
  
  <para>You can find Berkeley Java Edition database recovery messages in the
  database log file, such as
  <filename>/path/to/opendj/db/userRoot/je.info.0</filename>. The following
  shows two example messages from that log, the first written at the beginning
  of the recovery process, the second written at the end of the process.</para>

  <para>
   Database recovery messages are found in the database log file,
   such as <filename>/path/to/opendj/db/userRoot/dj.log</filename>.
  </para>

  <para condition="local-db">
   For <literal>local-db</literal> type backends, the log file name is similar to
   <filename>/path/to/opendj/db/userRoot/je.info.0</filename>.
  </para>

  <para>
   The following example shows two example messages from the recover log.
   The first message is written at the beginning of the recovery process.
   The second message is written at the end of the process.
  </para>
  
  <programlisting language="none">
111104 10:23:48:967 CONFIG [/path/to/opendj/db/userRoot]Recovery

 opendj-server-legacy/src/main/docbkx/admin-guide/chap-tuning.xml

@@ -177,13 +177,13 @@
    <para>High performance storage is essential if you need to handle high
    write throughput.</para>
    
    <para>The Berkeley Java Edition DB works well with traditional disks as
    <para condition="local-db">The Berkeley Java Edition DB works well with traditional disks as
    long as the database cache size allows the DB to stay fully cached in
    memory. This is the case because the database transaction log is append
    only. When the DB is too big to stay cached in memory, however, then
    cache misses lead to random disk access, slowing OpenDJ performance.</para>
    
    <para>You might mitigate this effect by using solid-state disks for
    <para condition="local-db">You might mitigate this effect by using solid-state disks for
    persistent storage, or for file system cache.</para>
    
    <para>Regarding database size on disk, if you have sustained write traffic
@@ -376,11 +376,8 @@
    stored in its backend database.
    If your entries hold values that compress well &#8212;
    such as text, and not JPEG photos or MP3 audio &#8212;
    you can gain space by setting the local DB backend property,
    <link
     xlink:show="new"
     xlink:href="${configRefBase}local-db-backend.html#entries-compressed"
    ><literal>entries-compressed</literal></link>,
    you can gain space by setting the backend property
    <literal>entries-compressed</literal>,
    to <literal>true</literal> before you (re-)import data from LDIF.
    With <literal>entries-compressed: true</literal>
    OpenDJ compresses entries before writing them to the database.<footnote>
@@ -460,16 +457,8 @@
   
   <para>
    Database cache size is, by default, set as a percentage of the JVM heap
    by using the backend property,
    <link
     xlink:show="new"
     xlink:href="${configRefBase}local-db-backend.html#db-cache-percent"
    ><literal>db-cache-percent</literal></link>.
    Alternatively, you use the backend property,
    <link
     xlink:show="new"
     xlink:href="${configRefBase}local-db-backend.html#db-cache-size"
    ><literal>db-cache-size</literal></link>,
    by using the backend property <literal>db-cache-percent</literal>.
    Alternatively, you use the backend property <literal>db-cache-size</literal>,
    to set the size.
    If you set up multiple database backends,
    the total percent of JVM heap used must remain less than 100,
@@ -490,12 +479,9 @@
    which you must pre-load on startup,
    and which can result in long garbage collections
    and a difficult-to-manage JVM.
    Test database pre-load on startup by setting the
    <link
     xlink:show="new"
     xlink:href="${configRefBase}local-db-backend.html#preload-time-limit"
    ><literal>preload-time-limit</literal></link>
    for the backend.</para>
    Test database pre-load on startup by setting
    the <literal>preload-time-limit</literal> for the backend.
   </para>
   
   <screen>
$ <userinput>dsconfig \

 opendj-server-legacy/src/main/docbkx/install-guide/chap-install-cli.xml

@@ -214,13 +214,14 @@
On which port would you like the Administration Connector to accept
connections? [4444]: 

Do you want to create base DNs in the server? (yes / no) [yes]:
Do you want to create base DNs in the server? (yes / no) [yes]:</computeroutput>
<computeroutput condition="local-db">
Provide the backend type:

    1)  local-db
    2)  persistit

Enter choice [1]:</computeroutput> <userinput>2</userinput>
Enter choice [1]:</computeroutput> <userinput condition="local-db">2</userinput>

<computeroutput>Provide the base DN for the directory data: [dc=example,dc=com]:


 opendj-server-legacy/src/main/docbkx/man-pages/verify-index-examples.xml

@@ -31,11 +31,36 @@
 <title>Examples</title>

 <para>
  The following example verifies the <literal>cn</literal> (common name) index
  for completeness and for errors.
  The following example shows how to verify
  the <literal>sn</literal> (surname) index for completeness and for errors.
  The messages shown are for a backend of type <literal>persistit</literal>.
 </para>

  <screen>
$ <userinput>verify-index -b dc=example,dc=com -i sn --clean --countErrors</userinput>
<computeroutput>[20/05/2015:14:24:18 +0200] category=...persistit.PersistItStorage seq=0 severity=INFO
 msg=The Persistit storage for backend 'userRoot' initialized
 to use 57528 buffers of 16384 bytes (total 920448kb)
[20/05/2015:14:24:18 +0200] category=...pluggable.VerifyJob seq=1 severity=INFO
 msg=Checked 478 records and found 0 error(s) in 0 seconds
 (average rate 3594.0/sec)
[20/05/2015:14:24:18 +0200] category=...pluggable.VerifyJob seq=2 severity=FINE
 msg=Number of records referencing more than one entry: 224
[20/05/2015:14:24:18 +0200] category=...pluggable.VerifyJob seq=3 severity=FINE
 msg=Number of records that exceed the entry limit: 0
[20/05/2015:14:24:18 +0200] category=...pluggable.VerifyJob seq=4 severity=FINE
 msg=Average number of entries referenced is 2.00/record
[20/05/2015:14:24:18 +0200] category=...pluggable.VerifyJob seq=5 severity=FINE
 msg=Maximum number of entries referenced by any record is 32</computeroutput>
  </screen>

 <para condition="local-db">
  The following example shows how to verify
  the <literal>cn</literal> (common name) index for completeness and for errors.
  The messages shown are for a backend of type <literal>local-db</literal>.
 </para>

  <screen condition="local-db">
$ <userinput>verify-index -b dc=example,dc=com -i cn --clean --countErrors</userinput>
<computeroutput>[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
 msgID=9437595 msg=Local DB backend userRoot does not specify the number of

 opendj-server-legacy/src/main/docbkx/shared/sec-cli-overview.xml

@@ -148,7 +148,7 @@
   </listitem>
  </varlistentry>

  <varlistentry>
  <varlistentry condition="local-db">
   <term><link
    xlink:href="reference#dbtest-1"
    xlink:role="http://docbook.org/xlink/role/olink">dbtest</link></term>