[#1128] Replace the DocBook xinclude and olink leftovers of the generated r...

Valery Kharseko

12 hours ago e521b43bf59c5e7e09224507b9457d397c3811ac

[#1128] Replace the DocBook xinclude and olink leftovers of the generated reference with AsciiDoc (#1132)

 opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java

@@ -414,7 +414,7 @@

                @Override
                public String visitACI(ACIPropertyDefinition prop, Void p) {
                    b.append(op).append(REF_DSCFG_ACI_SYNTAX_REL_URL.get()).append(cp).append(EOL);
                    b.append(op).append(REF_DSCFG_ACI_SYNTAX.get()).append(cp).append(EOL);
                    return null;
                }

@@ -470,7 +470,7 @@

                @Override
                public String visitDuration(DurationPropertyDefinition prop, Void p) {
                    b.append(REF_DSCFG_DURATION_SYNTAX_REL_URL.get()).append(EOL);
                    b.append(REF_DSCFG_DURATION_SYNTAX.get()).append(EOL);
                    b.append(op);
                    if (prop.isAllowUnlimited()) {
                        b.append(REF_DSCFG_ALLOW_UNLIMITED.get()).append(" ");
@@ -485,7 +485,7 @@
                    b.append(REF_DSCFG_DURATION_LOWER_LIMIT.get(lowerLimit, unitName)).append(".");
                    if (prop.getUpperLimit() != null) {
                        final long upperLimit = valueOf(baseUnit, prop.getUpperLimit());
                        b.append(REF_DSCFG_DURATION_UPPER_LIMIT.get(upperLimit, unitName)).append(".");
                        b.append(" ").append(REF_DSCFG_DURATION_UPPER_LIMIT.get(upperLimit, unitName)).append(".");
                    }
                    b.append(cp).append(EOL);
                    return null;
@@ -540,14 +540,17 @@
                @Override
                public String visitSize(SizePropertyDefinition prop, Void p) {
                    b.append(op);
                    String separator = "";
                    if (prop.getLowerLimit() != 0) {
                        b.append(REF_DSCFG_INT_LOWER_LIMIT.get(prop.getLowerLimit())).append(".");
                        separator = " ";
                    }
                    if (prop.getUpperLimit() != null) {
                        b.append(REF_DSCFG_INT_UPPER_LIMIT.get(prop.getUpperLimit())).append(".");
                        b.append(separator).append(REF_DSCFG_INT_UPPER_LIMIT.get(prop.getUpperLimit())).append(".");
                        separator = " ";
                    }
                    if (prop.isAllowUnlimited()) {
                        b.append(REF_DSCFG_ALLOW_UNLIMITED.get());
                        b.append(separator).append(REF_DSCFG_ALLOW_UNLIMITED.get());
                    }
                    b.append(cp).append(EOL);
                    return null;

 opendj-config/src/main/resources/com/forgerock/opendj/dsconfig/dsconfig.properties

@@ -12,6 +12,7 @@
#
# Copyright 2006-2010 Sun Microsystems, Inc.
# Portions Copyright 2011-2016 ForgeRock AS.
# Portions Copyright 2026 3A Systems, LLC.

#
# Format string definitions
@@ -398,8 +399,12 @@

# Strings for generated reference documentation.
REF_DSCFG_ALLOW_UNLIMITED_1000=A value of "-1" or "unlimited" for no limit.
REF_DSCFG_ACI_SYNTAX_REL_URL_1001=<olink targetdoc="admin-guide" targetptr="about-acis" />
REF_DSCFG_DURATION_SYNTAX_REL_URL_1002=<xinclude:include href="itemizedlist-duration.xml" />
REF_DSCFG_ACI_SYNTAX_1001=An access control instruction, as described in \
 xref:../admin-guide/chap-privileges-acis.adoc#about-acis["About Access Control Instructions"] \
 in the __Administration Guide__.
REF_DSCFG_DURATION_SYNTAX_1002=A duration: a number followed by a unit, one of \
 `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours), `d` (days) \
 or `w` (weeks), for example `1 s` or `2 w`.
REF_DSCFG_ARG_ADDITIONAL_INFO_1003=%s properties depend on the %s type, \
 which depends on the %s option.
REF_DSCFG_SUBTYPE_DEPENDENCIES_1004=%s properties depend on the %s type, \

 opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-import-export.adoc

@@ -498,7 +498,7 @@

OpenDJ directory server encrypts data using a symmetric key that is stored with the server configuration. The symmetric key is encrypted in turn with the server's public key that is also stored with the server configuration. When multiple servers are configured to replicate data as described in xref:chap-replication.adoc#configure-repl["Configuring Replication"], the servers replicate the keys as well, allowing any server replica to decrypt the data.

In addition to entry encryption, you can enable confidentiality by backend index, as long as confidentiality is enabled for the backend itself. Confidentiality hashes keys for equality type indexes using SHA-1, and encrypts the list of entries matching a substring key for substring indexes. The following example shows how to enable confidentiality for the `mail` index:
In addition to entry encryption, you can enable confidentiality by backend index, as long as confidentiality is enabled for the backend itself. Confidentiality encrypts the list of entries matching each key, for every index type of the attribute, and hashes the keys of the equality index using SHA-1. The keys of the other index types are stored as they are. The following example shows how to enable confidentiality for the `mail` index:

[source, console]
----

 opendj-doc-generated-ref/src/main/asciidoc/man-pages/_description-upgrade.adoc

New file
@@ -0,0 +1,39 @@
////

  The contents of this file are subject to the terms of the Common Development and
  Distribution License (the License). You may not use this file except in compliance with the
  License.

  You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
  specific language governing permission and limitations under the License.

  When distributing Covered Software, include this CDDL Header Notice in each file and include
  the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
  Header, with the fields enclosed by brackets [] replaced by your own identifying
  information: "Portions Copyright [year] [name of copyright owner]".

  Copyright 2015 ForgeRock AS.
  Portions Copyright 2026 3A Systems, LLC.

////

This utility thus performs only part of the upgrade process, which includes the following phases for a single server.

. Get and unpack a newer version of OpenDJ directory server software.

. Stop the current OpenDJ directory server.

. Overwrite existing binary and script files with those of the newer version, and then run this utility before restarting OpenDJ.

. Start the upgraded OpenDJ directory server.

[IMPORTANT]
====
This utility __does not back up OpenDJ before you upgrade, nor does it restore OpenDJ if the utility fails__. In order to revert a failed upgrade, make sure you back up OpenDJ directory server before you overwrite existing binary and script files.
====

By default this utility requests confirmation before making important configuration changes. You can use the `--no-prompt` option to run the command non-interactively.

When using the `--no-prompt` 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 `--force` option to force a non-interactive upgrade to continue in this case, also performing long running and critical tasks.

After upgrading, see the resulting `logs/upgrade.log` file for a full list of operations performed.

 opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc

New file
@@ -0,0 +1,49 @@
////

  The contents of this file are subject to the terms of the Common Development and
  Distribution License (the License). You may not use this file except in compliance with the
  License.

  You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
  specific language governing permission and limitations under the License.

  When distributing Covered Software, include this CDDL Header Notice in each file and include
  the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
  Header, with the fields enclosed by brackets [] replaced by your own identifying
  information: "Portions Copyright [year] [name of copyright owner]".

  Copyright 2015 ForgeRock AS.
  Portions Copyright 2026 3A Systems, LLC.

////

When you run the `show-index-status` subcommand, the result is a table, followed by a "Total", which is the total number of indexes, followed by a list of indexes with "Over index-entry-limit keys" to show the values for which the number of entries exceeded the index entry limit. The table has the following columns.

Index Name::
Name of the index, which takes the form __attr.type__ for attribute indexes, and vlv.__name__ for VLV indexes. Some indexes are for OpenDJ directory server's internal use.
+
Example: `givenName.caseIgnoreSubstringsMatch:6`

Raw DB Name::
Name of the backend tree, which reflects how OpenDJ directory server organizes the data in the database.
+
Example: `/dc=com,dc=example/givenName.caseIgnoreSubstringsMatch:6`

Valid::
This is `true` for valid indexes. If this is `false`, the index might be degraded. Verify the index, and rebuild the index if necessary. For an attribute index that is not valid, the record count and the key counts that follow it show `-`.

Confidential::
This is `true` for indexes with `confidentiality-enabled`, whose lists of entry IDs are stored encrypted. The keys are not encrypted: an equality index stores its keys hashed, the other index types store them as they are. This is recorded as `-` for VLV indexes, which have no confidentiality setting.

Record Count::
Number of indexed keys. Use the `backendstat dump-index` command to see how many entry IDs correspond to each key.

Over Entry Limit::
Number of keys for which there are too many values to maintain an index, based on the index entry limit. This is recorded as `-` for VLV indexes.
+
In other words, with the default index entry limit of 4000, if every user in your large directory has an email address ending in `@example.com`, and a substring index with default substring length of 6 is maintained for `mail`, then OpenDJ directory server does not maintain indexes for keys corresponding to substrings in `@example.com`.
+
As a result, an LDAP search with the filter `"(mail=*@example.com)"` 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 from sending searches that return every user in the directory for example. Clients should refine their search filters instead.

95%, 90%, 80%::
Number of keys for which the number of values is approaching the index entry limit. This is a measure of how full the entry ID lists are. The `95%` column counts keys holding at least 95% of the limit, the `90%` column keys holding at least 90% but less than 95%, and the `80%` column keys holding at least 80% but less than 90%. These columns are recorded as `-` for VLV indexes, and stay at 0 for an index whose entry limit is 0, which means no limit.

 opendj-maven-plugin/src/main/resources/config/xml/org/forgerock/opendj/server/config/BackendIndexConfiguration.xml

@@ -14,6 +14,7 @@

  Copyright 2007-2009 Sun Microsystems, Inc.
  Portions copyright 2014-2016 ForgeRock AS.
  Portions Copyright 2026 3A Systems, LLC.
  ! -->
<adm:managed-object name="backend-index" plural-name="backend-indexes"
  package="org.forgerock.opendj.server.config"
@@ -224,8 +225,9 @@
      Specifies whether contents of the index should be confidential.
    </adm:synopsis>
    <adm:description>
      Setting the flag to true will hash keys for equality type indexes using SHA-1
      and encrypt the list of entries matching a substring key for substring indexes.
      Setting the flag to true will encrypt the list of entries matching each key, for
      every index type of the attribute, and hash the keys of the equality index using SHA-1.
      The keys of the other index types are stored as they are.
    </adm:description>
    <adm:requires-admin-action>
      <adm:other>

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

@@ -2615,7 +2615,7 @@
REF_SHORT_DESC_BACKEND_TOOL_15031=gather OpenDJ backend debugging information

# Supplements to descriptions for generated reference documentation.
SUPPLEMENT_DESCRIPTION_UPGRADE_CLI_20004=<xinclude:include href="description-upgrade.xml" />
SUPPLEMENT_DESCRIPTION_UPGRADE_CLI_20004=include::./_description-upgrade.adoc[]
INFO_ARGUMENT_DESCRIPTION_TESTONLY_20005=Just verify that the JVM can be \
 started properly
INFO_INSTALLDS_BACKEND_TYPE_PLACEHOLDER_20006={backendType}
@@ -2632,7 +2632,7 @@
ERR_SEARCH_INVALID_DEREFERENCE_POLICY_20014=Invalid deref alias specified: %s
ERR_FILE_NOT_FULLY_READABLE_20015=Could not completely read file '%s'
SUPPLEMENT_DESCRIPTION_BACKEND_TOOL_SUBCMD_LIST_INDEX_STATUS_20016=\
  <xinclude:include href="variablelist-backendstat-index-status.xml" />
  include::./_variablelist-backendstat-index-status.adoc[]
INFO_DESCRIPTION_DEFAULT_ADD_20017=Legacy argument for ForgeRock OpenDJ compatibility.
WARN_CONFIGDS_KEY_WRAPPING_TRANSFORMATION_UNSUPPORTED_20018=This Java runtime \
 supports neither the default key wrapping transformation %s nor an alternative \

 opendj-server-legacy/src/test/java/org/opends/server/backends/pluggable/BackendStatTest.java

@@ -15,9 +15,12 @@
 */
package org.opends.server.backends.pluggable;

import static com.forgerock.opendj.cli.ArgumentParser.PROPERTY_SCRIPT_NAME;
import static org.assertj.core.api.Assertions.*;
import static org.opends.server.backends.pluggable.BackendStat.*;

import java.io.ByteArrayOutputStream;

import org.opends.server.DirectoryServerTestCase;
import org.testng.annotations.Test;

@@ -82,4 +85,38 @@
      }
    }
  }

  /** The generated reference of show-index-status includes its AsciiDoc description of the columns (#1128). */
  @Test
  public void testGenerateDocIncludesTheIndexStatusSupplement() throws Exception
  {
    final String scriptName = System.getProperty(PROPERTY_SCRIPT_NAME);
    System.setProperty("org.forgerock.opendj.gendoc", "true");
    System.setProperty(PROPERTY_SCRIPT_NAME, "backendstat");
    final ByteArrayOutputStream out = new ByteArrayOutputStream();
    try
    {
      assertThat(BackendStat.main(new String[] { "-?" }, out, System.err)).isEqualTo(0);
    }
    finally
    {
      System.clearProperty("org.forgerock.opendj.gendoc");
      restoreProperty(PROPERTY_SCRIPT_NAME, scriptName);
    }
    assertThat(out.toString("UTF-8"))
        .contains("include::./_variablelist-backendstat-index-status.adoc[]")
        .doesNotContain("<xinclude:include");
  }

  private static void restoreProperty(String name, String value)
  {
    if (value != null)
    {
      System.setProperty(name, value);
    }
    else
    {
      System.clearProperty(name);
    }
  }
}

 opendj-server-legacy/src/test/java/org/opends/server/tools/UpgradeTestCase.java

@@ -12,6 +12,7 @@
 * information: "Portions Copyright [year] [name of copyright owner]".
 *
 * Portions Copyright 2013-2016 ForgeRock AS.
 * Portions Copyright 2026 3A Systems, LLC.
 */
package org.opends.server.tools;

@@ -29,6 +30,7 @@
import org.testng.annotations.Test;

import static com.forgerock.opendj.cli.ArgumentConstants.*;
import static com.forgerock.opendj.cli.ArgumentParser.PROPERTY_SCRIPT_NAME;
import static org.opends.messages.ToolMessages.*;
import static org.testng.Assert.*;

@@ -114,6 +116,35 @@
    }
  }

  /** The generated reference of the upgrade tool includes its AsciiDoc description (#1128). */
  @Test
  public void testUpgradeToolGenerateDocIncludesItsDescriptionSupplement() throws Exception
  {
    final String scriptName = System.getProperty(PROPERTY_SCRIPT_NAME);
    System.setProperty("org.forgerock.opendj.gendoc", "true");
    System.setProperty(PROPERTY_SCRIPT_NAME, "upgrade");
    try (final ByteArrayOutputStream baos = new ByteArrayOutputStream();
        final PrintStream ps = new PrintStream(baos))
    {
      assertEquals(UpgradeCli.main(setArgs("-?"), true, ps, ps), 0);
      Assertions.assertThat(baos.toString())
          .contains("include::./_description-upgrade.adoc[]")
          .doesNotContain("<xinclude:include");
    }
    finally
    {
      System.clearProperty("org.forgerock.opendj.gendoc");
      if (scriptName != null)
      {
        System.setProperty(PROPERTY_SCRIPT_NAME, scriptName);
      }
      else
      {
        System.clearProperty(PROPERTY_SCRIPT_NAME);
      }
    }
  }

  /** Tests the upgrade tool with an invalid sub-command. */
  @Test
  public void testUpgradeToolDoesntAllowWrongSubcommand() throws Exception

 opendj-server-legacy/src/test/java/org/opends/server/tools/dsconfig/DsconfigOptionsTestCase.java

@@ -12,6 +12,7 @@
 * information: "Portions Copyright [year] [name of copyright owner]".
 *
 * Copyright 2011-2016 ForgeRock AS.
 * Portions Copyright 2026 3A Systems, LLC.
 */
package org.opends.server.tools.dsconfig;

@@ -19,6 +20,8 @@

import static org.testng.Assert.*;

import java.io.ByteArrayOutputStream;

import org.forgerock.opendj.config.dsconfig.DSConfig;
import org.opends.server.DirectoryServerTestCase;
import org.opends.server.TestCaseUtils;
@@ -182,6 +185,35 @@
    }
  }

  /**
   * Tests that the generated reference describes the duration and ACI values in AsciiDoc,
   * and keeps the duration and size limits apart.
   */
  @Test
  public void testGenerateDocHasNoDocBookLeftovers() throws Exception
  {
    System.setProperty("org.forgerock.opendj.gendoc", "true");
    System.setProperty("com.forgerock.opendj.ldap.tools.scriptName", "dsconfig");
    final ByteArrayOutputStream out = new ByteArrayOutputStream();
    try
    {
      assertEquals(DSConfig.main(new String[] { "--no-prompt", "-?" }, out, System.err), SUCCESS.get());
    }
    finally
    {
      System.clearProperty("org.forgerock.opendj.gendoc");
    }
    final String doc = out.toString("UTF-8");
    assertTrue(doc.contains("Upper limit is"), "no duration property with an upper limit was generated");
    assertTrue(doc.contains("A duration: a number followed by a unit"), "duration syntax");
    assertTrue(doc.contains("xref:../admin-guide/chap-privileges-acis.adoc#about-acis"), "ACI syntax");
    assertFalse(doc.contains("<xinclude:include"), "DocBook xinclude leftover");
    assertFalse(doc.contains("<olink"), "DocBook olink leftover");
    assertFalse(doc.contains(".Lower limit") || doc.contains(".Upper limit"), "duration sentences glued together");
    assertTrue(doc.contains("Lower value is 512"), "no size property with a lower limit was generated");
    assertFalse(doc.contains(".Upper value"), "size sentences glued together");
  }

  private int dsconfigMain(String[] args)
  {
    return DSConfig.main(args, System.out, System.err);