From 095d90536e06b18cc0dad6951e06cb25f4b566ba Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 27 Jan 2015 11:03:40 +0000
Subject: [PATCH] CR-5899 OPENDJ-1748 Document psearch control in ldapsearch
---
opendj-sdk/opendj3-server-dev/resource/man/man1/ldapsearch.1 | 70 ++++++++++++++++
opendj-sdk/opendj3-server-dev/src/main/docbkx/admin-guide/man-ldapsearch.xml | 133 ++++++++++++++++++++++++++++++++
2 files changed, 198 insertions(+), 5 deletions(-)
diff --git a/opendj-sdk/opendj3-server-dev/resource/man/man1/ldapsearch.1 b/opendj-sdk/opendj3-server-dev/resource/man/man1/ldapsearch.1
index 01495e5..b727c52 100644
--- a/opendj-sdk/opendj3-server-dev/resource/man/man1/ldapsearch.1
+++ b/opendj-sdk/opendj3-server-dev/resource/man/man1/ldapsearch.1
@@ -2,12 +2,12 @@
.\" Title: ldapsearch
.\" Author:
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\" Date: 10/22/2014
+.\" Date: 01/27/2015
.\" Manual: Tools Reference
.\" Source: OpenDJ 3.0.0
.\" Language: English
.\"
-.TH "LDAPSEARCH" "1" "10/22/2014" "OpenDJ 3\&.0\&.0" "Tools Reference"
+.TH "LDAPSEARCH" "1" "01/27/2015" "OpenDJ 3\&.0\&.0" "Tools Reference"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -69,6 +69,70 @@
\fB\-C, \-\-persistentSearch ps[:changetype[:changesonly[:entrychgcontrols]]]\fR
.RS 4
Use the persistent search control
+.sp
+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\&.
+The optional
+changetype
+setting defines the kinds of updates that result in notification\&. By default the
+changetype
+is not set\&.
+.PP
+add
+.RS 4
+Send notifications for LDAP add operations\&.
+.RE
+.PP
+del, delete
+.RS 4
+Send notifications for LDAP delete operations\&.
+.RE
+.PP
+mod, modify
+.RS 4
+Send notifications for LDAP modify operations\&.
+.RE
+.PP
+moddn, modrdn, modifydn
+.RS 4
+Send notifications for LDAP modify DN (rename and move) operations\&.
+.RE
+.PP
+all, any
+.RS 4
+Send notifications for all LDAP update operations\&.
+.RE
+.sp
+The optional
+changesonly
+setting defines whether the server returns existing entries as well as changes\&.
+.PP
+true
+.RS 4
+Do not return existing entries, but instead only notifications about changes\&.
+.sp
+This is the default setting\&.
+.RE
+.PP
+false
+.RS 4
+Also return existing entries\&.
+.RE
+.sp
+The optional
+entrychgcontrols
+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 as 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\&.
+.PP
+true
+.RS 4
+Do request the Entry Change Notification control\&.
+.sp
+This is the default setting\&.
+.RE
+.PP
+false
+.RS 4
+Do not request the Entry Change Notification control\&.
+.RE
.RE
.PP
\fB\-\-countEntries\fR
@@ -539,5 +603,5 @@
.\}
.SH "COPYRIGHT"
.br
-Copyright \(co 2011-2014 ForgeRock AS
+Copyright \(co 2011-2015 ForgeRock AS.
.br
diff --git a/opendj-sdk/opendj3-server-dev/src/main/docbkx/admin-guide/man-ldapsearch.xml b/opendj-sdk/opendj3-server-dev/src/main/docbkx/admin-guide/man-ldapsearch.xml
index eed6b0a..4d1d69c 100644
--- a/opendj-sdk/opendj3-server-dev/src/main/docbkx/admin-guide/man-ldapsearch.xml
+++ b/opendj-sdk/opendj3-server-dev/src/main/docbkx/admin-guide/man-ldapsearch.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2014 ForgeRock AS
+ ! Copyright 2011-2015 ForgeRock AS.
!
-->
<refentry xml:id='ldapsearch-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'>
- <info><copyright><year>2011-2014</year><holder>ForgeRock AS</holder></copyright></info>
+ <info><copyright><year>2011-2015</year><holder>ForgeRock AS.</holder></copyright></info>
<refmeta>
<refentrytitle>ldapsearch</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="software">OpenDJ</refmiscinfo>
@@ -92,6 +92,135 @@
<term><option>-C, --persistentSearch ps[:changetype[:changesonly[:entrychgcontrols]]]</option></term>
<listitem>
<para>Use the persistent search control</para>
+
+ <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.
+ By default the <literal>changetype</literal> is not set.
+ </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 as 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>
</listitem>
</varlistentry>
<varlistentry>
--
Gitblit v1.10.0