From edaa9e524a9a2d7ec2b378e45c7acb10833892d7 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 07 Jul 2015 10:39:35 +0000
Subject: [PATCH] CR-7462 OPENDJ-2150 Expand doc on use of entry caches
---
opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-tuning.xml | 40 ++++++++++++++++++++++++++++++++--------
opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-groups.xml | 17 +++++++++++++++++
2 files changed, 49 insertions(+), 8 deletions(-)
diff --git a/opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-tuning.xml b/opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-tuning.xml
index e5ad961..3746fce 100644
--- a/opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-tuning.xml
+++ b/opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-tuning.xml
@@ -502,13 +502,35 @@
</section>
<section xml:id="perf-entry-cache">
- <title>Entry Cache Settings</title>
+ <title>Caching Large, Frequently Used Entries</title>
- <para>OpenDJ implements an entry cache. The entry cache is not designed to
- cache every entry in your database, but is instead useful in cases where you
- have a few, typically large entries that are regularly used. For example, if
- you have a few large static groups and applications that regularly check
- group membership, you could cache your group entries.</para>
+ <para>
+ OpenDJ implements an entry cache designed for deployments
+ with a few large entries that are regularly updated or accessed.
+ The common use case is a deployment with a few large static groups
+ that are updated or accessed regularly.
+ An entry cache is used to keep such groups in memory in a format that
+ avoids the need to constantly read and deserialize the large entries.
+ </para>
+
+ <para>
+ When configuring an entry cache,
+ take care to include only the entries that need to be cached
+ by using the configuration properties
+ <literal>include-filter</literal> and <literal>exclude-filter</literal>.
+ The memory devoted to the entry cache is not available for other purposes.
+ </para>
+
+ <para>
+ The following example adds a Soft Reference entry cache
+ to hold entries that match the filter
+ <literal>(ou=Large Static Groups)</literal>.
+ A Soft Reference entry cache allows cached entries to be released
+ if the JVM is running low on memory.
+ A Soft Reference entry cache has no maximum size setting,
+ so the number of entries cached is limited only by the
+ <literal>include-filter</literal> and <literal>exclude-filter</literal> settings.
+ </para>
<screen>
$ <userinput>dsconfig \
@@ -518,15 +540,17 @@
--bindDN "cn=Directory Manager" \
--bindPassword password \
--cache-name "Large Group Entry Cache" \
- --type fifo \
+ --type soft-reference \
--set cache-level:1 \
--set include-filter:"(ou=Large Static Groups)" \
- --set max-entries:10 \
--set enabled:true \
--trustAll \
--no-prompt</userinput>
</screen>
+ <para>
+ The entry cache configuration takes effect when the entry cache is enabled.
+ </para>
</section>
<section xml:id="perf-logging">
diff --git a/opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-groups.xml b/opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-groups.xml
index b9c98cf..6c4f006 100644
--- a/opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-groups.xml
+++ b/opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-groups.xml
@@ -112,6 +112,23 @@
<para>A <firstterm>static group</firstterm> is expressed as an entry
that enumerates all the entries that belong to the group. Static group
entries grow as their membership increases.</para>
+
+ <tip>
+ <para>
+ Large static groups can be a performance bottleneck.
+ The recommended way to avoid the issue is to use dynamic groups instead
+ as described in <xref linkend="dynamic-groups" />.
+ If using dynamic groups is not an option
+ for a deployment with large static groups that are updated regularly,
+ use an entry cache.
+ For details, see the <citetitle>Administration Guide</citetitle> section
+ <link
+ xlink:href="admin-guide#perf-entry-cache"
+ xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:show="new"
+ ><citetitle>Caching Large, Frequently Used Entries</citetitle></link>.
+ </para>
+ </tip>
<para>Static group entries can take the standard object class
<literal>groupOfNames</literal> where each <literal>member</literal>
--
Gitblit v1.10.0