CR-6060 OPENDJ-1785 Add "extra" doc into code for generated content

Mark Craig

12.56.2015 bae9398cc148d37215ff0c6f2e2dcc347f4dc134

CR-6060 OPENDJ-1785 Add "extra" doc into code for generated content

This patch adds supplemental documentation
for what is already part of the hand-written reference
to the generated reference content.
For example, descriptions that are longer in the hand-written reference
than in the generated reference content
are now included in the generated reference content.

This patch does not, however, add additional reference sections
that are not currently part of generated content,
such as EXIT CODES, EXAMPLES, SEE ALSO, etc.

This is a subtask of the following issue:
OPENDJ-386 Move to single reference document

 opendj-cli/src/main/java/com/forgerock/opendj/cli/Argument.java

@@ -22,7 +22,7 @@
 *
 *
 *      Copyright 2006-2008 Sun Microsystems, Inc.
 *      Portions copyright 2014-2015 ForgeRock AS
 *      Portions copyright 2014-2015 ForgeRock AS.
 */
package com.forgerock.opendj.cli;

@@ -239,6 +239,35 @@
    }

    /**
     * A supplement to the description for this argument
     * intended for use in generated reference documentation.
     */
    private LocalizableMessage docDescriptionSupplement;

    /**
     * Retrieves a supplement to the description for this argument
     * intended for use in generated reference documentation.
     *
     * @return The supplement to the description for this argument
     *         for use in generated reference documentation,
     *         or LocalizableMessage.EMPTY if there is no supplement.
     */
    public LocalizableMessage getDocDescriptionSupplement() {
        return docDescriptionSupplement != null ? docDescriptionSupplement : LocalizableMessage.EMPTY;
    }

    /**
     * Sets a supplement to the description for this argument
     * intended for use in generated reference documentation.
     *
     * @param docDescriptionSupplement  The supplement to the description for this argument
     *                                  for use in generated reference documentation.
     */
    public void setDocDescriptionSupplement(final LocalizableMessage docDescriptionSupplement) {
        this.docDescriptionSupplement = docDescriptionSupplement;
    }

    /**
     * Retrieves the value of this argument as an integer.
     *
     * @return The value of this argument as an integer.

 opendj-cli/src/main/java/com/forgerock/opendj/cli/ArgumentParser.java

@@ -608,6 +608,35 @@
    }

    /**
     * A supplement to the description for this tool
     * intended for use in generated reference documentation.
     */
    private LocalizableMessage docToolDescriptionSupplement;

    /**
     * Retrieves a supplement to the description for this tool,
     * intended for use in generated reference documentation.
     *
     * @return A supplement to the description for this tool
     *         intended for use in generated reference documentation,
     *         or LocalizableMessage.EMPTY if there is no supplement.
     */
    LocalizableMessage getDocToolDescriptionSupplement() {
        return docToolDescriptionSupplement != null ? docToolDescriptionSupplement : LocalizableMessage.EMPTY;
    }

    /**
     * Sets a supplement to the description for this tool,
     * intended for use in generated reference documentation.
     *
     * @param docToolDescriptionSupplement  The supplement to the description for this tool
     *                                      intended for use in generated reference documentation.
     */
    public void setDocToolDescriptionSupplement(final LocalizableMessage docToolDescriptionSupplement) {
        this.docToolDescriptionSupplement = docToolDescriptionSupplement;
    }

    /**
     * Retrieves the set of unnamed trailing arguments that were provided on the
     * command line.
     *
@@ -647,6 +676,14 @@
        sb.append(" <title>").append(scriptName).append("</title>").append(EOL);
        sb.append(" <para>").append(getToolDescription()).append("</para>").append(EOL);

        // If there is a supplement to the description for this utility,
        // then it is formatted for use in generated reference documentation.
        // In other words, it is already DocBook XML, so append it as is.
        final LocalizableMessage toolDocDescriptionSupplement = getDocToolDescriptionSupplement();
        if (!LocalizableMessage.EMPTY.equals(toolDocDescriptionSupplement)) {
            sb.append(toolDocDescriptionSupplement.toString()).append(EOL);
        }

        if (!argumentList.isEmpty()) {
            sb.append(" <variablelist>").append(EOL);
            for (Argument a : argumentList) {
@@ -669,6 +706,19 @@
                sb.append("</option></term>").append(EOL);
                sb.append("    <listitem>").append(EOL);
                sb.append("      <para>").append(a.getDescription()).append("</para>").append(EOL);

                final String defaultValue = a.getDefaultValue();
                if (defaultValue != null && !defaultValue.isEmpty()) {
                    sb.append("      <para>Default: ").append(defaultValue).append("</para>").append(EOL);
                }

                // If there is a supplement to the description for this argument,
                // then for now it is already formatted in DocBook XML.
                final LocalizableMessage aDocDescriptionSupplement = a.getDocDescriptionSupplement();
                if (!LocalizableMessage.EMPTY.equals(aDocDescriptionSupplement)) {
                    sb.append(aDocDescriptionSupplement.toString()).append(EOL);
                }

                sb.append("    </listitem>").append(EOL);
                sb.append("  </varlistentry>").append(EOL);
            }

 opendj-cli/src/main/java/com/forgerock/opendj/cli/SubCommand.java

@@ -22,7 +22,7 @@
 *
 *
 *      Copyright 2006-2008 Sun Microsystems, Inc.
 *      Portions Copyright 2014-2015 ForgeRock AS
 *      Portions Copyright 2014-2015 ForgeRock AS.
 */
package com.forgerock.opendj.cli;

@@ -164,6 +164,35 @@
    }

    /**
     * A supplement to the description for this subcommand
     * intended for use in generated reference documentation.
     */
    private LocalizableMessage docDescriptionSupplement;

    /**
     * Retrieves a supplement to the description for this subcommand
     * intended for use in generated reference documentation.
     *
     * @return The supplement to the description for this subcommand
     *         for use in generated reference documentation,
     *         or LocalizableMessage.EMPTY if there is no supplement.
     */
    public LocalizableMessage getDocDescriptionSupplement() {
        return docDescriptionSupplement != null ? docDescriptionSupplement : LocalizableMessage.EMPTY;
    }

    /**
     * Sets a supplement to the description for this subcommand
     * intended for use in generated reference documentation.
     *
     * @param docDescriptionSupplement  The supplement to the description for this subcommand
     *                                  for use in generated reference documentation.
     */
    public void setDocDescriptionSupplement(final LocalizableMessage docDescriptionSupplement) {
        this.docDescriptionSupplement = docDescriptionSupplement;
    }

    /**
     * Retrieves the set of arguments for this subcommand.
     *
     * @return The set of arguments for this subcommand.

 opendj-cli/src/main/java/com/forgerock/opendj/cli/SubCommandArgumentParser.java

@@ -22,7 +22,7 @@
 *
 *
 *      Copyright 2006-2010 Sun Microsystems, Inc.
 *      Portions Copyright 2011-2015 ForgeRock AS
 *      Portions Copyright 2011-2015 ForgeRock AS.
 */
package com.forgerock.opendj.cli;

@@ -1176,6 +1176,14 @@
        sb.append(" <title>").append(nameRef).append("</title>").append(EOL);
        sb.append(" <para>").append(sc.getDescription()).append("</para>").append(EOL);

        // If there is a supplement to the description for this subcommand,
        // then it is formatted for use in generated reference documentation.
        // In other words, it is already DocBook XML, so append it as is.
        final LocalizableMessage scDocDescriptionSupplement = sc.getDocDescriptionSupplement();
        if (!LocalizableMessage.EMPTY.equals(scDocDescriptionSupplement)) {
            sb.append(scDocDescriptionSupplement.toString()).append(EOL);
        }

        if (!sc.getArguments().isEmpty()) {
            sb.append(" <refsect3 xml:id=\"").append(idRef).append("-options\">").append(EOL);
            sb.append("   <title>Options</title>").append(EOL);
@@ -1202,6 +1210,18 @@
                }
                if (subCommandUsageHandler != null) {
                    subCommandUsageHandler.appendArgumentAdditionalInfo(sb, sc, a, nameOption);
                } else {
                    final String defaultValue = a.getDefaultValue();
                    if (defaultValue != null && !defaultValue.isEmpty()) {
                        sb.append("         <para>Default: ").append(defaultValue).append("</para>").append(EOL);
                    }

                    // If there is a supplement to the description for this argument,
                    // then for now it is already formatted in DocBook XML.
                    final LocalizableMessage aDocDescriptionSupplement = a.getDocDescriptionSupplement();
                    if (!LocalizableMessage.EMPTY.equals(aDocDescriptionSupplement)) {
                        sb.append(aDocDescriptionSupplement.toString()).append(EOL);
                    }
                }
                sb.append("       </listitem>").append(EOL);
                sb.append("     </varlistentry>").append(EOL);

 opendj-cli/src/main/resources/com/forgerock/opendj/cli/cli.properties

@@ -21,7 +21,7 @@
# CDDL HEADER END
#
#
#      Copyright 2014 ForgeRock AS.
#      Copyright 2014-2015 ForgeRock AS.
#
#
# CLI messages
@@ -176,7 +176,8 @@
INFO_DESCRIPTION_TRUSTALL=Trust all server SSL certificates
INFO_DESCRIPTION_BINDDN=DN to use to bind to the server
INFO_DESCRIPTION_BINDPASSWORD=Password to use to bind to \
 the server
 the server. Use -w - to ensure that the command prompts for the password, \
 rather than entering the password as a command argument
INFO_DESCRIPTION_BINDPASSWORDFILE=Bind password file
INFO_DESCRIPTION_ENCODING=Use the specified character set for \
 command-line input

 opendj-server-legacy/src/messages/org/opends/messages/tool.properties

@@ -20,7 +20,7 @@
# CDDL HEADER END
#
#      Copyright 2006-2010 Sun Microsystems, Inc.
#      Portions Copyright 2011-2014 ForgeRock AS
#      Portions Copyright 2011-2015 ForgeRock AS.



@@ -247,7 +247,8 @@
INFO_SEARCH_DESCRIPTION_TIME_LIMIT_133=Maximum length of time in seconds to \
 allow for the search
INFO_SEARCH_DESCRIPTION_SEARCH_SCOPE_134=Search scope ('base', 'one', 'sub', \
 or 'subordinate')
 or 'subordinate'). Note: 'subordinate' is an LDAP extension \
 that might not work with all LDAP servers
INFO_SEARCH_DESCRIPTION_DEREFERENCE_POLICY_135=Alias dereference policy \
 ('never', 'always', 'search', or 'find')
ERR_LDAPAUTH_CANNOT_SEND_SIMPLE_BIND_136=Cannot send the simple bind \
@@ -1121,7 +1122,14 @@
INFO_LDAPPWMOD_DESCRIPTION_BIND_PW_FILE_639=Path to a file \
 containing the password to use to bind to the server
INFO_LDAPPWMOD_DESCRIPTION_AUTHZID_640=Authorization ID for the \
 user entry whose password should be changed
 user entry whose password should be changed. \
 The authorization ID is a string having either \
 the prefix "dn:" followed by the user's distinguished name, or \
 the prefix "u:" followed by a user identifier \
 that depends on the identity mapping used \
 to match the user identifier to an entry in the directory. \
 Examples include "dn:uid=bjensen,ou=People,dc=example,dc=com", and, \
 if we assume that "bjensen" is mapped to Barbara Jensen's entry, "u:bjensen"
INFO_LDAPPWMOD_DESCRIPTION_PROVIDE_DN_FOR_AUTHZID_641=Use the bind \
 DN as the authorization ID for the password modify operation
INFO_LDAPPWMOD_DESCRIPTION_NEWPW_642=New password to provide \
@@ -1226,7 +1234,12 @@
INFO_RESTOREDB_TOOL_DESCRIPTION_698=This utility can be used to restore a \
 backup of a Directory Server backend
INFO_STOPDS_TOOL_DESCRIPTION_699=This utility can be used to request that the \
 Directory Server stop running or perform a restart
 Directory Server stop running or perform a restart. \
 When run without connection options, \
 this utility sends a signal to the OpenDJ process to stop the server. \
 When run with connection options, \
 this utility connects to the OpenDJ administration port and \
 creates a shutdown task to stop the server
INFO_VERIFYINDEX_TOOL_DESCRIPTION_700=This utility can be used to ensure that \
 index data is consistent within a backend based on the Berkeley DB Java \
 Edition
@@ -1839,7 +1852,8 @@
INFO_DESCRIPTION_DBTEST_SUBCMD_LIST_ENTRY_CONTAINERS_1329=List the entry \
  containers for a root container
INFO_DESCRIPTION_DBTEST_SUBCMD_DUMP_DATABASE_CONTAINER_1330=Dump records from \
  a database container
  a database container. Depending on database size, \
  this subcommand can generate lots of output
INFO_DESCRIPTION_DBTEST_BACKEND_ID_1331=The backend ID of the JE backend to \
  debug
INFO_DESCRIPTION_DBTEST_BASE_DN_1332=The base DN of the entry container to debug
@@ -1849,7 +1863,9 @@
  their appropriate types
ERR_DBTEST_DECODE_FAIL_1335=An error occurred while decoding data: %s
INFO_DESCRIPTION_DBTEST_SUBCMD_LIST_INDEX_STATUS_1336=List the status of \
  indexes in an entry container
  indexes in an entry container. \
  This subcommand can take a long time to complete, \
  as it reads all indexes for all backends
INFO_DESCRIPTION_DBTEST_MAX_KEY_VALUE_1337=Only show records with keys that \
  should be ordered before the provided value using the comparator for the \
  database container
@@ -2600,3 +2616,393 @@
 Do you want to launch this process automatically at the end of the upgrade?
INFO_UPGRADE_TASK_11339_SUMMARY_10036=Removing config for 'Extensions'
INFO_UPGRADE_TASK_11476_SUMMARY_10037=Removing config for 'File System Entry Cache'

# Supplements to descriptions for generated reference documentation.
SUPPLEMENT_DESCRIPTION_DBTEST_SUBCMD_LIST_INDEX_STATUS_20001=<para>                \
        When you list index status, the result is a table,                         \
        followed by a "Total", which is the total number of indexes,               \
        followed by a list of indexes with "Undefined keys" to show                \
        the values for which the number of entries exceeded the index entry limit. \
        The table has the following columns.                                       \
       </para>                                                                     \
                                                                                   \
       <variablelist>                                                              \
        <varlistentry>                                                             \
         <term>Index Name</term>                                                   \
         <listitem>                                                                \
          <para>                                                                   \
           Name of the index,                                                      \
           which takes the form <replaceable>attr.type</replaceable>               \
           for attribute indexes,                                                  \
           and vlv.<replaceable>name</replaceable> for VLV indexes.                \
           Some indexes are for OpenDJ directory server's internal use.            \
          </para>                                                                  \
                                                                                   \
          <para>                                                                   \
           Example: <literal>givenName.substring</literal>                         \
          </para>                                                                  \
         </listitem>                                                               \
        </varlistentry>                                                            \
                                                                                   \
        <varlistentry>                                                             \
         <term>Index Type</term>                                                   \
         <listitem>                                                                \
          <para>                                                                   \
           Type of the index,                                                      \
           which is <literal>Index</literal> for attribute indexes,                \
           and <literal>VLVIndex</literal> for VLV indexes.                        \
          </para>                                                                  \
         </listitem>                                                               \
        </varlistentry>                                                            \
                                                                                   \
        <varlistentry>                                                             \
         <term>JE Database Name</term>                                             \
         <listitem>                                                                \
          <para>                                                                   \
           Name of the Berkeley Java Edition database,                             \
           which reflects how OpenDJ directory server                              \
           organizes the data in the database.                                     \
          </para>                                                                  \
                                                                                   \
          <para>                                                                   \
           Example: <literal>dc_example_dc_com_givenName.substring</literal>       \
          </para>                                                                  \
         </listitem>                                                               \
        </varlistentry>                                                            \
                                                                                   \
        <varlistentry>                                                             \
         <term>Index Valid</term>                                                  \
         <listitem>                                                                \
          <para>                                                                   \
           This is <literal>true</literal> for valid indexes.                      \
           If this is <literal>false</literal>,                                    \
           the index might be degraded.                                            \
           Verify the index, and rebuild the index if necessary.                   \
          </para>                                                                  \
         </listitem>                                                               \
        </varlistentry>                                                            \
                                                                                   \
        <varlistentry>                                                             \
         <term>Record Count</term>                                                 \
         <listitem>                                                                \
          <para>                                                                   \
           Number of indexed keys.                                                 \
           Use the <command>dbtest dump-database-container</command> command       \
           to see how many entry IDs correspond to each key.                       \
          </para>                                                                  \
         </listitem>                                                               \
        </varlistentry>                                                            \
                                                                                   \
        <varlistentry>                                                             \
         <term>Undefined</term>                                                    \
         <listitem>                                                                \
          <para>                                                                   \
           Number of keys for which there are too many values                      \
           to maintain an index, based on the index entry limit.                   \
           This is recorded as <literal>-</literal> for VLV indexes.               \
          </para>                                                                  \
                                                                                   \
          <para>                                                                   \
           In other words, with the default index entry limit of 4000,             \
           if every user in your large directory has an email address              \
           ending in <literal>@example.com</literal>,                              \
           and a substring index is maintained for <literal>mail</literal>,        \
           then OpenDJ directory server does not maintain indexes for              \
           keys corresponding to substrings in <literal>@example.com</literal>.    \
          </para>                                                                  \
                                                                                   \
          <para>                                                                   \
           As a result, an LDAP search with the filter                             \
           <literal>"(mail=*@example.com)"</literal> becomes an unindexed search   \
           even though a substring index exists for the mail attribute.            \
           By default OpenDJ directory server does not allow unindexed searches    \
           except by privileged users.                                             \
           This is usually exactly the behavior you want                           \
           in order to prevent client applications for example                     \
           from sending searches that return every user in the directory.          \
           Clients should refine their search filters instead.                     \
          </para>                                                                  \
         </listitem>                                                               \
        </varlistentry>                                                            \
                                                                                   \
        <varlistentry>                                                             \
         <term>95&#x25;, 90&#x25;, 85&#x25;</term>                                 \
         <listitem>                                                                \
          <para>                                                                   \
           Number of keys for which the number of values is approaching            \
           the index entry limit, having reached the specified percentage.         \
           This is a measure of how full the entry ID lists are.                   \
          </para>                                                                  \
         </listitem>                                                               \
        </varlistentry>                                                            \
       </variablelist>
SUPPLEMENT_DESCRIPTION_PSEARCH_INFO_20002=<para>                                   \
      A persistent search allows the client to continue receiving new results      \
      whenever changes are made to data that is in the scope of the search,        \
      thus using the search as a form of change notification.                      \
     </para>                                                                       \
                                                                                   \
     <variablelist>                                                                \
      <para>                                                                       \
       The optional <literal>changetype</literal> setting defines                  \
       the kinds of updates that result in notification.                           \
       If you do not set the <literal>changetype</literal>,                        \
       the default behavior is to send notifications for all updates.              \
      </para>                                                                      \
                                                                                   \
      <varlistentry>                                                               \
       <term><literal>add</literal></term>                                         \
       <listitem>                                                                  \
        <para>                                                                     \
         Send notifications for LDAP add operations.                               \
        </para>                                                                    \
       </listitem>                                                                 \
      </varlistentry>                                                              \
                                                                                   \
      <varlistentry>                                                               \
       <term><literal>del</literal></term>                                         \
       <term><literal>delete</literal></term>                                      \
       <listitem>                                                                  \
        <para>                                                                     \
         Send notifications for LDAP delete operations.                            \
        </para>                                                                    \
       </listitem>                                                                 \
      </varlistentry>                                                              \
                                                                                   \
      <varlistentry>                                                               \
       <term><literal>mod</literal></term>                                         \
       <term><literal>modify</literal></term>                                      \
       <listitem>                                                                  \
        <para>                                                                     \
         Send notifications for LDAP modify operations.                            \
        </para>                                                                    \
       </listitem>                                                                 \
      </varlistentry>                                                              \
                                                                                   \
      <varlistentry>                                                               \
       <term><literal>moddn</literal></term>                                       \
       <term><literal>modrdn</literal></term>                                      \
       <term><literal>modifydn</literal></term>                                    \
       <listitem>                                                                  \
        <para>                                                                     \
         Send notifications for LDAP modify DN (rename and move) operations.       \
        </para>                                                                    \
       </listitem>                                                                 \
      </varlistentry>                                                              \
                                                                                   \
      <varlistentry>                                                               \
       <term><literal>all</literal></term>                                         \
       <term><literal>any</literal></term>                                         \
       <listitem>                                                                  \
        <para>                                                                     \
         Send notifications for all LDAP update operations.                        \
        </para>                                                                    \
       </listitem>                                                                 \
      </varlistentry>                                                              \
     </variablelist>                                                               \
                                                                                   \
     <variablelist>                                                                \
      <para>                                                                       \
       The optional <literal>changesonly</literal> setting defines                 \
       whether the server returns existing entries as well as changes.             \
      </para>                                                                      \
                                                                                   \
      <varlistentry>                                                               \
       <term><literal>true</literal></term>                                        \
       <listitem>                                                                  \
        <para>                                                                     \
         Do not return existing entries,                                           \
         but instead only notifications about changes.                             \
        </para>                                                                    \
                                                                                   \
        <para>                                                                     \
         This is the default setting.                                              \
        </para>                                                                    \
       </listitem>                                                                 \
      </varlistentry>                                                              \
                                                                                   \
      <varlistentry>                                                               \
       <term><literal>false</literal></term>                                       \
       <listitem>                                                                  \
        <para>                                                                     \
         Also return existing entries.                                             \
        </para>                                                                    \
       </listitem>                                                                 \
      </varlistentry>                                                              \
     </variablelist>                                                               \
                                                                                   \
     <variablelist>                                                                \
      <para>                                                                       \
       The optional <literal>entrychgcontrols</literal> setting defines            \
       whether the server returns an Entry Change Notification control             \
       with each entry notification.                                               \
       The Entry Change Notification control provides additional information       \
       about the change that caused the entry to be returned by the search.        \
       In particular, it indicates the change type,                                \
       the change number if available,                                             \
       and the previous DN if the change type was a modify DN operation.           \
      </para>                                                                      \
                                                                                   \
      <varlistentry>                                                               \
       <term><literal>true</literal></term>                                        \
       <listitem>                                                                  \
        <para>                                                                     \
         Do request the Entry Change Notification control.                         \
        </para>                                                                    \
                                                                                   \
        <para>                                                                     \
         This is the default setting.                                              \
        </para>                                                                    \
       </listitem>                                                                 \
      </varlistentry>                                                              \
                                                                                   \
      <varlistentry>                                                               \
       <term><literal>false</literal></term>                                       \
       <listitem>                                                                  \
        <para>                                                                     \
         Do not request the Entry Change Notification control.                     \
        </para>                                                                    \
       </listitem>                                                                 \
      </varlistentry>                                                              \
     </variablelist>
SUPPLEMENT_DESCRIPTION_CONTROLS_20003=<para>                                       \
    For some <replaceable>controloid</replaceable> values,                         \
    you can replace object identifiers with user-friendly strings.                 \
                                                                                   \
    The strings are listed here in lower case, but the case is not important.      \
    You can use camelCase if you prefer, for example.                              \
   </para>                                                                         \
                                                                                   \
   <variablelist>                                                                  \
    <varlistentry>                                                                 \
     <term><literal>accountusable</literal></term>                                 \
     <term><literal>accountusability</literal></term>                              \
     <listitem>                                                                    \
      <para>Account Usability Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>authzid</literal></term>                                       \
     <term><literal>authorizationidentity</literal></term>                         \
     <listitem>                                                                    \
      <para>Authorization Identity Request Control, Object Identifier: 2.16.840.1.113730.3.4.16</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>effectiverights</literal></term>                               \
     <term><literal>geteffectiverights</literal></term>                            \
     <listitem>                                                                    \
      <para>Get Effective Rights Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>managedsait</literal></term>                                   \
     <listitem>                                                                    \
      <para>Manage DSAIT Request Control, Object Identifier: 2.16.840.1.113730.3.4.2</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>noop</literal></term>                                          \
     <term><literal>no-op</literal></term>                                         \
     <listitem>                                                                    \
      <para>No-Op Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.2</para>       \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>pwpolicy</literal></term>                                      \
     <term><literal>passwordpolicy</literal></term>                                \
     <listitem>                                                                    \
      <para>Password Policy Control, Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>realattrsonly</literal></term>                                 \
     <term><literal>realattributesonly</literal></term>                            \
     <listitem>                                                                    \
      <para>Real Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.17</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>subtreedelete</literal></term>                                 \
     <term><literal>treedelete</literal></term>                                    \
     <listitem>                                                                    \
      <para>Subtree Delete Request Control, Object Identifier: 1.2.840.113556.1.4.805</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>virtualattrsonly</literal></term>                              \
     <term><literal>virtualattributesonly</literal></term>                         \
     <listitem>                                                                    \
      <para>Virtual Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.19</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
   </variablelist>
SUPPLEMENT_DESCRIPTION_UPGRADE_CLI_20004=<para>                                    \
    This utility thus performs only part of the upgrade process,                   \
    which includes the following phases for a single server.                       \
   </para>                                                                         \
                                                                                   \
   <orderedlist>                                                                   \
    <listitem>                                                                     \
     <para>                                                                        \
      Get and unpack a newer version of OpenDJ directory server software.          \
     </para>                                                                       \
    </listitem>                                                                    \
    <listitem>                                                                     \
     <para>                                                                        \
      Stop the current OpenDJ directory server.                                    \
     </para>                                                                       \
    </listitem>                                                                    \
    <listitem>                                                                     \
     <para>                                                                        \
      Overwrite existing binary and script files with those of the newer version,  \
      and then run this utility before restarting OpenDJ.                          \
     </para>                                                                       \
    </listitem>                                                                    \
    <listitem>                                                                     \
     <para>                                                                        \
      Start the upgraded OpenDJ directory server.                                  \
     </para>                                                                       \
    </listitem>                                                                    \
   </orderedlist>                                                                  \
                                                                                   \
   <important>                                                                     \
    <para>                                                                         \
     This utility <emphasis>does not back up OpenDJ before you upgrade,            \
     nor does it restore OpenDJ if the utility fails</emphasis>.                   \
     In order to revert a failed upgrade,                                          \
     make sure you back up OpenDJ directory server                                 \
     before you overwrite existing binary and script files.                        \
    </para>                                                                        \
   </important>                                                                    \
                                                                                   \
   <para>                                                                          \
    By default this utility requests confirmation                                  \
    before making important configuration changes.                                 \
    You can use the <option>--no-prompt</option> option                            \
    to run the command non-interactively.                                          \
   </para>                                                                         \
                                                                                   \
   <para>                                                                          \
    When using the <option>--no-prompt</option> option,                            \
    if this utility cannot complete                                                \
    because it requires confirmation for a potentially very long or critical task, \
    then it exits with an error and                                                \
    a message about how to finish making the changes.                              \
    You can add the <option>--force</option> option                                \
    to force a non-interactive upgrade to continue in this case,                   \
    also performing long running and critical tasks.                               \
   </para>                                                                         \
                                                                                   \
   <para>                                                                          \
    After upgrading, see the resulting <filename>upgrade.log</filename> file       \
    for a full list of operations performed.                                       \
   </para>

 opendj-server-legacy/src/messages/org/opends/messages/utility.properties

@@ -20,7 +20,7 @@
# CDDL HEADER END
#
#      Copyright 2006-2009 Sun Microsystems, Inc.
#      Portions Copyright 2011-2014 ForgeRock AS
#      Portions Copyright 2011-2015 ForgeRock AS.



@@ -417,8 +417,11 @@
 decode information using base64
INFO_BASE64_HELP_DESCRIPTION_187=Display this usage information
INFO_BASE64_DECODE_DESCRIPTION_188=Decode base64-encoded information into \
 raw data
INFO_BASE64_ENCODE_DESCRIPTION_189=Encode raw data using base64
 raw data. When no options are specified, \
 this subcommand reads from standard input and writes to standard output
INFO_BASE64_ENCODE_DESCRIPTION_189=Encode raw data using base64. \
 When no options are specified, this subcommand reads from standard input and \
 writes to standard output
INFO_BASE64_ENCODED_DATA_DESCRIPTION_190=The base64-encoded data to be decoded
INFO_BASE64_ENCODED_FILE_DESCRIPTION_191=The path to a file containing the \
 base64-encoded data to be decoded

 opendj-server-legacy/src/server/org/opends/server/tools/DBTest.java

@@ -22,7 +22,7 @@
 *
 *
 *      Copyright 2006-2010 Sun Microsystems, Inc.
 *      Portions Copyright 2013-2015 ForgeRock AS
 *      Portions Copyright 2013-2015 ForgeRock AS.
 */
package org.opends.server.tools;

@@ -331,6 +331,8 @@

      sub = new SubCommand(parser, "list-index-status",
                        INFO_DESCRIPTION_DBTEST_SUBCMD_LIST_INDEX_STATUS.get());
      sub.setDocDescriptionSupplement(
              SUPPLEMENT_DESCRIPTION_DBTEST_SUBCMD_LIST_INDEX_STATUS.get());
      backendID =
          new StringArgument("backendid", 'n', "backendID", true, false, true,
                             INFO_BACKENDNAME_PLACEHOLDER.get(), null, null,

 opendj-server-legacy/src/server/org/opends/server/tools/LDAPSearch.java

@@ -22,7 +22,7 @@
 *
 *
 *      Copyright 2006-2010 Sun Microsystems, Inc.
 *      Portions Copyright 2012-2015 ForgeRock AS
 *      Portions Copyright 2012-2015 ForgeRock AS.
 */
package org.opends.server.tools;

@@ -903,6 +903,7 @@
                             INFO_PSEARCH_PLACEHOLDER.get(),
                              null, null, INFO_DESCRIPTION_PSEARCH_INFO.get());
      pSearchInfo.setPropertyName("persistentSearch");
      pSearchInfo.setDocDescriptionSupplement(SUPPLEMENT_DESCRIPTION_PSEARCH_INFO.get());
      argParser.addArgument(pSearchInfo);

      simplePageSize = new IntegerArgument(
@@ -953,6 +954,7 @@
                    INFO_LDAP_CONTROL_PLACEHOLDER.get(),
                    null, null, INFO_DESCRIPTION_CONTROLS.get());
      controlStr.setPropertyName("control");
      controlStr.setDocDescriptionSupplement(SUPPLEMENT_DESCRIPTION_CONTROLS.get());
      argParser.addArgument(controlStr);

      subEntriesArgument = new BooleanArgument("subEntries",
@@ -1008,7 +1010,7 @@
      dereferencePolicy =
           new StringArgument("derefpolicy", 'a', "dereferencePolicy", false,
                              false, true,
                              INFO_DEREFERENCE_POLICE_PLACEHOLDER.get(), null,
                              INFO_DEREFERENCE_POLICE_PLACEHOLDER.get(), "never",
                              null,
                              INFO_SEARCH_DESCRIPTION_DEREFERENCE_POLICY.get());
      dereferencePolicy.setPropertyName("dereferencePolicy");

 opendj-server-legacy/src/server/org/opends/server/tools/upgrade/UpgradeCli.java

@@ -21,7 +21,7 @@
 * CDDL HEADER END
 *
 *
 *      Portions Copyright 2013-2015 ForgeRock AS
 *      Portions Copyright 2013-2015 ForgeRock AS.
 */
package org.opends.server.tools.upgrade;

@@ -102,6 +102,7 @@
        new SubCommandArgumentParser(getClass().getName(),
            INFO_UPGRADE_DESCRIPTION_CLI.get(), false);
    this.parser.setVersionHandler(new DirectoryServerVersionHandler());
    this.parser.setDocToolDescriptionSupplement(SUPPLEMENT_DESCRIPTION_UPGRADE_CLI.get());
  }

  /**