From 841f44a425521c22aecf534f64596c147253237a Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 12 Feb 2013 09:37:42 +0000
Subject: [PATCH] CR-1275 Fix for OPENDJ-751: Mention rebuild-index --clearDegradedState in documentation
---
opends/resource/man/man1/rebuild-index.1 | 13 +++++-
opendj3/src/main/docbkx/shared/man-rebuild-index.xml | 15 ++++++-
opendj3/src/main/docbkx/admin-guide/chap-indexing.xml | 52 +++++++++++++++++++++++++
opendj3/src/main/docbkx/release-notes/chap-whats-new.xml | 10 ++++
4 files changed, 83 insertions(+), 7 deletions(-)
diff --git a/opendj3/src/main/docbkx/admin-guide/chap-indexing.xml b/opendj3/src/main/docbkx/admin-guide/chap-indexing.xml
index c18c090..8aac9e5 100644
--- a/opendj3/src/main/docbkx/admin-guide/chap-indexing.xml
+++ b/opendj3/src/main/docbkx/admin-guide/chap-indexing.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2013 ForgeRock AS
!
-->
<chapter xml:id='chap-indexing'
@@ -414,6 +414,56 @@
...
Rebuild Index task 20120131164324838 has been successfully completed</screen>
</example>
+
+ <example xml:id="clear-degraded-indexes-example">
+ <title>Clear New, Unused, "Degraded" Indexes</title>
+
+ <para>When you add a new attribute as described in <link
+ xlink:href="admin-guide#update-schema"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Updating
+ Directory Schema</citetitle></link>, and then create indexes for the new
+ attribute, the new indexes appear as degraded, even though the attribute
+ has not yet been used, and so indexes are sure to be empty, rather than
+ degraded.</para>
+
+ <para>In this special case, you can safely use the
+ <command>rebuild-index</command> command
+ <option>--clearDegradedState</option> option to avoid having to scan
+ the entire directory backend to rebuild the new, unused index. This
+ is shown in the following example, where an index has just been created
+ for <literal>newUnusedAttribute</literal>.</para>
+
+ <screen>$ dbtest
+ list-index-status
+ --backendID userRoot
+ --baseDN dc=example,dc=com
+ | grep newUnusedAttribute
+newUnusedAttribute.equality Index ...newUnusedAttribute.equality false...
+newUnusedAttribute.presence Index ...newUnusedAttribute.presence false...
+newUnusedAttribute.substring Index ...newUnusedAttribute.substring false...
+$ rebuild-index
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN dc=example,dc=com
+ --clearDegradedState
+ --index newUnusedAttribute
+ --start 0
+Rebuild Index task 20130211175925012 scheduled to start Feb 11, 2013 5:59:25
+ PM CET
+$ dbtest
+ list-index-status
+ --backendID userRoot
+ --baseDN dc=example,dc=com
+ | grep newUnusedAttribute
+newUnusedAttribute.equality Index ...newUnusedAttribute.equality true...
+newUnusedAttribute.presence Index ...newUnusedAttribute.presence true...
+newUnusedAttribute.substring Index ...newUnusedAttribute.substring true...</screen>
+
+ <para>If the newly indexed attribute has already been used, rebuild indexes
+ instead.</para>
+ </example>
</section>
<section xml:id="index-entry-limits">
diff --git a/opendj3/src/main/docbkx/release-notes/chap-whats-new.xml b/opendj3/src/main/docbkx/release-notes/chap-whats-new.xml
index 4ff6522..ee7b2af 100644
--- a/opendj3/src/main/docbkx/release-notes/chap-whats-new.xml
+++ b/opendj3/src/main/docbkx/release-notes/chap-whats-new.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2013 ForgeRock AS
!
-->
<chapter xml:id='chap-whats-new'
@@ -86,6 +86,14 @@
>OPENDJ-482</link>).</para>
</listitem>
<listitem>
+ <para>The OpenDJ <command>rebuild-index</command> command now provides
+ an option, <option>--clearDegradedState</option>, to forcefully clear
+ the state of an unused index for a newly created attribute (<link
+ xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-473"
+ >OPENDJ-473</link>).</para>
+ </listitem>
+ <listitem>
<para>Import now performs better when handling LDIF entries with
attributes that have many values, such as large static group entries
(<link xlink:show="new"
diff --git a/opendj3/src/main/docbkx/shared/man-rebuild-index.xml b/opendj3/src/main/docbkx/shared/man-rebuild-index.xml
index 1b2892f..b5166df 100644
--- a/opendj3/src/main/docbkx/shared/man-rebuild-index.xml
+++ b/opendj3/src/main/docbkx/shared/man-rebuild-index.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2013 ForgeRock AS
!
-->
<refentry xml:id='rebuild-index-1'
@@ -30,7 +30,7 @@
xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
- <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
<refmeta>
<refentrytitle>rebuild-index</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="software">OpenDJ</refmiscinfo>
@@ -63,6 +63,17 @@
</listitem>
</varlistentry>
<varlistentry>
+ <term><option>--clearDegradedState</option></term>
+ <listitem>
+ <para>Indicates that indexes do not need rebuilding because they are known
+ to be empty and forcefully marks them as valid. <emphasis>This is an
+ advanced option which must only be used in cases where a degraded index is
+ known to be empty and does not therefore need rebuilding.</emphasis> This
+ situation typically arises when an index is created for an attribute which
+ has just been added to the schema.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><option>-i, --index {index}</option></term>
<listitem>
<para>Names of index(es) to rebuild. For an attribute index this is
diff --git a/opends/resource/man/man1/rebuild-index.1 b/opends/resource/man/man1/rebuild-index.1
index 54b69ef..afc341b 100644
--- a/opends/resource/man/man1/rebuild-index.1
+++ b/opends/resource/man/man1/rebuild-index.1
@@ -2,12 +2,12 @@
.\" Title: rebuild-index
.\" Author:
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\" Date: 03/21/2012
+.\" Date: 02/12/2013
.\" Manual: Tools Reference
.\" Source: OpenDJ 2.5.0
.\" Language: English
.\"
-.TH "REBUILD\-INDEX" "1" "03/21/2012" "OpenDJ 2\&.5\&.0" "Tools Reference"
+.TH "REBUILD\-INDEX" "1" "02/12/2013" "OpenDJ 2\&.5\&.0" "Tools Reference"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -44,6 +44,13 @@
Base DN of a backend supporting indexing\&. Rebuild is performed on indexes within the scope of the given base DN\&.
.RE
.PP
+\fB\-\-clearDegradedState\fR
+.RS 4
+Indicates that indexes do not need rebuilding because they are known to be empty and forcefully marks them as valid\&.
+\fIThis is an advanced option which must only be used in cases where a degraded index is known to be empty and does not therefore need rebuilding\&.\fR
+This situation typically arises when an index is created for an attribute which has just been added to the schema\&.
+.RE
+.PP
\fB\-i, \-\-index {index}\fR
.RS 4
Names of index(es) to rebuild\&. For an attribute index this is simply an attribute name\&. At least one index must be specified for rebuild\&. Cannot be used with the
@@ -248,5 +255,5 @@
.\}
.SH "COPYRIGHT"
.br
-Copyright \(co 2011-2012 ForgeRock AS
+Copyright \(co 2011-2013 ForgeRock AS
.br
--
Gitblit v1.10.0