From 3d700c42df1c846576560fe8dd7f4d4b624703e3 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 24 Nov 2015 14:21:11 +0000
Subject: [PATCH] OPENDJ-2432 Add more explanation about each global ACI
---
opendj-sdk/opendj-doc-maven-plugin/src/main/resources/templates/table-global-acis.ftl | 13 ++++--
opendj-sdk/opendj-doc-maven-plugin/src/main/resources/org/forgerock/opendj/maven/doc/docs.properties | 3 +
opendj-sdk/opendj-doc-maven-plugin/src/main/java/org/forgerock/opendj/maven/doc/GenerateGlobalAcisTableMojo.java | 78 ++++++++++++++++++++++++++++----------
3 files changed, 68 insertions(+), 26 deletions(-)
diff --git a/opendj-sdk/opendj-doc-maven-plugin/src/main/java/org/forgerock/opendj/maven/doc/GenerateGlobalAcisTableMojo.java b/opendj-sdk/opendj-doc-maven-plugin/src/main/java/org/forgerock/opendj/maven/doc/GenerateGlobalAcisTableMojo.java
index 5fe593b..67e0c2f 100644
--- a/opendj-sdk/opendj-doc-maven-plugin/src/main/java/org/forgerock/opendj/maven/doc/GenerateGlobalAcisTableMojo.java
+++ b/opendj-sdk/opendj-doc-maven-plugin/src/main/java/org/forgerock/opendj/maven/doc/GenerateGlobalAcisTableMojo.java
@@ -36,8 +36,10 @@
import org.forgerock.opendj.ldap.Entry;
import org.forgerock.opendj.ldif.LDIFEntryReader;
+import java.io.BufferedReader;
import java.io.File;
import java.io.FileInputStream;
+import java.io.FileReader;
import java.io.IOException;
import java.text.SimpleDateFormat;
import java.util.Date;
@@ -65,8 +67,12 @@
@Parameter(defaultValue = "${project.build.directory}/docbkx-sources/shared")
private File outputDirectory;
+ /** Holds descriptions for ACIs. */
+ private Map<String, String> descriptions;
+
/** Holds documentation for an ACI. */
private class Aci {
+ String name;
String description;
String definition;
}
@@ -82,7 +88,7 @@
@Override
public void execute() throws MojoExecutionException, MojoFailureException {
try {
- readAcis();
+ readAcis(getAciDescriptions());
} catch (IOException e) {
throw new MojoFailureException(e.getMessage(), e);
}
@@ -96,10 +102,35 @@
}
/**
- * Reads {@code ds-cfg-global-aci} values from {@code config.ldif} into the list of Acis.
+ * Populates map of {@code ds-cfg-global-aci} descriptions from comments in {@code config.ldif}.
+ * Keys are ACI names. Values are descriptions.
+ * <br>
+ * The format expected for ACI description comments is the following:
+ * {@code # @aci name: description},
+ * where {@code name} matches the name embedded in the ACI,
+ * and {@code description} is a longer description.
* @throws IOException Failed to read the LDIF.
*/
- private void readAcis() throws IOException {
+ private Map<String, String> getAciDescriptions() throws IOException {
+ final Map<String, String> descriptions = new HashMap<>();
+ BufferedReader reader = new BufferedReader(new FileReader(configDotLdif));
+ String line;
+ while ((line = reader.readLine()) != null) {
+ if (line.startsWith("# @aci ")) {
+ String[] split = line.replace("# @aci ", "").split(":", 2);
+ descriptions.put(split[0], split[1]);
+ }
+ }
+ return descriptions;
+ }
+
+ /**
+ * Reads {@code ds-cfg-global-aci} values from {@code config.ldif} into the list of Acis.
+ * @param descriptions Long descriptions from comments in {@code config.ldif}.
+ * Keys are ACI names. Values are descriptions.
+ * @throws IOException Failed to read the LDIF.
+ */
+ private void readAcis(Map<String, String> descriptions) throws IOException {
LDIFEntryReader reader = new LDIFEntryReader(new FileInputStream(configDotLdif));
reader.setIncludeBranch(DN.valueOf("cn=Access Control Handler,cn=config"));
@@ -107,7 +138,10 @@
Entry entry = reader.readEntry();
for (String attribute : entry.parseAttribute("ds-cfg-global-aci").asSetOfString()) {
Aci aci = new Aci();
- aci.description = getDescription(attribute);
+ aci.name = getName(attribute);
+ if (descriptions != null) {
+ aci.description = descriptions.get(aci.name);
+ }
aci.definition = attribute;
allGlobalAcis.add(aci);
}
@@ -115,6 +149,23 @@
}
/**
+ * Returns the user-friendly name embedded in the ACI.
+ * @param aci The string representation of the ACI value.
+ * @return The user-friendly name embedded in the ACI,
+ * or an empty string if no name is found.
+ */
+ private String getName(String aci) {
+ // Extract the user-friendly string in
+ // {@code ...version 3.0; acl "user-friendly name"...}.
+ Pattern pattern = Pattern.compile(".+version 3.0; ?acl \"([^\"]+)\".+");
+ Matcher matcher = pattern.matcher(aci);
+ if (matcher.find()) {
+ return matcher.group(1);
+ }
+ return "";
+ }
+
+ /**
* Returns a DocBook XML table listing global ACIs.
* @return A DocBook XML table listing global ACIs.
*/
@@ -124,6 +175,7 @@
map.put("lang", locale);
map.put("title", DOC_GLOBAL_ACIS_TABLE_TITLE.get());
map.put("summary", DOC_GLOBAL_ACIS_TABLE_SUMMARY.get());
+ map.put("nameTitle", DOC_GLOBAL_ACIS_NAME_COLUMN_TITLE.get());
map.put("descTitle", DOC_GLOBAL_ACIS_DESCRIPTION_COLUMN_TITLE.get());
map.put("defTitle", DOC_GLOBAL_ACIS_DEFINITION_COLUMN_TITLE.get());
map.put("acis", getDefaultGlobalAciList());
@@ -138,27 +190,11 @@
final List<Map<String, Object>> globalAciList = new LinkedList<>();
for (final Aci aci : allGlobalAcis) {
final Map<String, Object> map = new HashMap<>();
+ map.put("name", aci.name);
map.put("description", aci.description);
map.put("definition", aci.definition);
globalAciList.add(map);
}
return globalAciList;
}
-
- /**
- * Returns the user-friendly description embedded in the ACI.
- * @param aci The string representation of the ACI value.
- * @return The user-friendly description embedded in the ACI,
- * or an empty string if no description is found.
- */
- private String getDescription(String aci) {
- // Extract the user-friendly string in
- // {@code ...version 3.0; acl "user-friendly string"...}.
- Pattern pattern = Pattern.compile(".+version 3.0; ?acl \"([^\"]+)\".+");
- Matcher matcher = pattern.matcher(aci);
- if (matcher.find()) {
- return matcher.group(1);
- }
- return "";
- }
}
diff --git a/opendj-sdk/opendj-doc-maven-plugin/src/main/resources/org/forgerock/opendj/maven/doc/docs.properties b/opendj-sdk/opendj-doc-maven-plugin/src/main/resources/org/forgerock/opendj/maven/doc/docs.properties
index 52211e3..8a41989 100644
--- a/opendj-sdk/opendj-doc-maven-plugin/src/main/resources/org/forgerock/opendj/maven/doc/docs.properties
+++ b/opendj-sdk/opendj-doc-maven-plugin/src/main/resources/org/forgerock/opendj/maven/doc/docs.properties
@@ -72,6 +72,7 @@
DOC_GLOBAL_ACIS_TABLE_TITLE=Default Global ACIs
DOC_GLOBAL_ACIS_TABLE_SUMMARY=OpenDJ directory server defines \
- the following global ACIs by default.
+ the following global ACIs by default:
+DOC_GLOBAL_ACIS_NAME_COLUMN_TITLE=Name
DOC_GLOBAL_ACIS_DESCRIPTION_COLUMN_TITLE=Description
DOC_GLOBAL_ACIS_DEFINITION_COLUMN_TITLE=ACI Definition
diff --git a/opendj-sdk/opendj-doc-maven-plugin/src/main/resources/templates/table-global-acis.ftl b/opendj-sdk/opendj-doc-maven-plugin/src/main/resources/templates/table-global-acis.ftl
index a4352a7..59197bb 100644
--- a/opendj-sdk/opendj-doc-maven-plugin/src/main/resources/templates/table-global-acis.ftl
+++ b/opendj-sdk/opendj-doc-maven-plugin/src/main/resources/templates/table-global-acis.ftl
@@ -38,25 +38,30 @@
</para>
</textobject>
- <tgroup cols="2">
+ <tgroup cols="3">
<colspec colnum="1" colwidth="1*"/>
<colspec colnum="2" colwidth="2*" />
+ <colspec colnum="3" colwidth="2*" />
<thead>
<row>
+ <entry>${nameTitle}</entry>
<entry>${descTitle}</entry>
<entry>${defTitle}</entry>
</row>
</thead>
<tbody>
- <#list acis?sort_by("description") as aci>
+ <#list acis?sort_by("name") as aci>
<row valign="top">
<entry>
- ${aci.description}<!-- In English in config.ldif by default -->
+ <para>${aci.name}</para> <!-- In English in config.ldif by default -->
</entry>
<entry>
- <literallayout>${aci.definition}</literallayout>
+ <para>${aci.description}</para> <!-- In English in config.ldif by default -->
+ </entry>
+ <entry>
+ <para><literal>${aci.definition}</literal></para>
</entry>
</row>
</#list>
--
Gitblit v1.10.0