OPENDJ-3144 Align log ref generation with fix for msgID

Mark Craig

20.48.2016 20006755d0477e1b9f9c31dd8e7601263b8e5c5a

OPENDJ-3144 Align log ref generation with fix for msgID

This patch adds category descriptions,
but does not resolve the problem that
the log message ref depends on properties files in opendj.jar.

This patch also lets the developer list all generated properties files.
No more need to grep through them looking for the files
with at least error-level messages.

 opendj-doc-generated-ref/pom.xml

@@ -127,28 +127,29 @@
                        <configuration>
                            <outputDirectory>${project.build.directory}/docbkx-sources/shared</outputDirectory>
                            <messageFileNames>
                                <!-- for xxx_yyy.properties generates a log-ref-xxx-yyy.xml file -->
                                <!--
                                  For each .properties with messages of at least error severity,
                                  generate a section in the log message reference listing the messages.
                                -->
                                <messageFileName>access_control</messageFileName>
                                <messageFileName>admin</messageFileName>
                                <messageFileName>admin_tool</messageFileName>
                                <messageFileName>backend</messageFileName>
                                <messageFileName>config</messageFileName>
                                <messageFileName>core</messageFileName>
                                <messageFileName>extension</messageFileName>
                                <messageFileName>external</messageFileName>
                                <messageFileName>logger</messageFileName>
                                <messageFileName>plugin</messageFileName>
                                <messageFileName>protocol</messageFileName>
                                <messageFileName>quickSetup</messageFileName>
                                <messageFileName>replication</messageFileName>
                                <messageFileName>runtime</messageFileName>
                                <messageFileName>schema</messageFileName>
                                <messageFileName>task</messageFileName>
                                <messageFileName>tool</messageFileName>
                                <messageFileName>utility</messageFileName>

                                <!-- Ignore following message files as we document only serious errors. -->
                                <!-- <messageFileName>access_control</messageFileName> -->
                                <!-- <messageFileName>admin_tool</messageFileName> -->
                                <!-- <messageFileName>external</messageFileName> -->
                                <!-- <messageFileName>quicksetup.properties</messageFileName> -->
                                <!-- <messageFileName>runtime_information.properties</messageFileName> -->
                                <!-- <messageFileName>version.properties</messageFileName> -->
                                <messageFileName>version</messageFileName>
                            </messageFileNames>
                        </configuration>
                    </execution>

 opendj-doc-maven-plugin/src/main/java/org/forgerock/opendj/maven/doc/GenerateMessageFileMojo.java

@@ -75,18 +75,20 @@
        CATEGORY_DESCRIPTIONS.put("ACCESS_CONTROL", CATEGORY_ACCESS_CONTROL.get());
        CATEGORY_DESCRIPTIONS.put("ADMIN", CATEGORY_ADMIN.get());
        CATEGORY_DESCRIPTIONS.put("ADMIN_TOOL", CATEGORY_ADMIN_TOOL.get());
        CATEGORY_DESCRIPTIONS.put("AUDIT", CATEGORY_AUDIT.get());
        CATEGORY_DESCRIPTIONS.put("BACKEND", CATEGORY_BACKEND.get());
        CATEGORY_DESCRIPTIONS.put("CONFIG", CATEGORY_CONFIG.get());
        CATEGORY_DESCRIPTIONS.put("CORE", CATEGORY_CORE.get());
        CATEGORY_DESCRIPTIONS.put("DSCONFIG", CATEGORY_DSCONFIG.get());
        CATEGORY_DESCRIPTIONS.put("EXTENSIONS", CATEGORY_EXTENSIONS.get());
        CATEGORY_DESCRIPTIONS.put("JEB", CATEGORY_JEB.get());
        CATEGORY_DESCRIPTIONS.put("JVM", CATEGORY_JVM.get());
        CATEGORY_DESCRIPTIONS.put("LOG", CATEGORY_LOG.get());
        CATEGORY_DESCRIPTIONS.put("PLUGIN", CATEGORY_PLUGIN.get());
        CATEGORY_DESCRIPTIONS.put("PROTOCOL", CATEGORY_PROTOCOL.get());
        CATEGORY_DESCRIPTIONS.put("QUICKSETUP", CATEGORY_QUICKSETUP.get());
        CATEGORY_DESCRIPTIONS.put("RUNTIME_INFORMATION", CATEGORY_RUNTIME_INFORMATION.get());
        CATEGORY_DESCRIPTIONS.put("SCHEMA", CATEGORY_SCHEMA.get());
        CATEGORY_DESCRIPTIONS.put("SDK", CATEGORY_SDK.get());
        CATEGORY_DESCRIPTIONS.put("SYNC", CATEGORY_SYNC.get());
        CATEGORY_DESCRIPTIONS.put("TASK", CATEGORY_TASK.get());
        CATEGORY_DESCRIPTIONS.put("THIRD_PARTY", CATEGORY_THIRD_PARTY.get());
@@ -309,7 +311,10 @@
        map.put("intro", LOG_REF_INTRO.get());
        List<Map<String, Object>> categories = new LinkedList<>();
        for (String category : messageFileNames) {
            categories.add(getCategoryMap(category));
            Map<String, Object> categoryMap = getCategoryMap(category);
            if (!categoryMap.isEmpty()) {   // Empty: no messages to document
                categories.add(getCategoryMap(category));
            }
        }
        map.put("categories", categories);
        File file = new File(outputDirectory, "log-message-reference.xml");
@@ -356,6 +361,7 @@
    }

    private InputStream loadPropertiesFromJar(final String category) throws IOException {
        getLog().debug("category: " + category);
        final JarFile jarFile = new JarFile(
                Paths.get(project.getBuild().getDirectory(), "opendj", "lib", "opendj.jar").toString());
        return jarFile.getInputStream(jarFile.getJarEntry(

 opendj-doc-maven-plugin/src/main/resources/org/forgerock/opendj/maven/doc/docs.properties

@@ -11,7 +11,7 @@
# Header, with the fields enclosed by brackets [] replaced by your own identifying
# information: "Portions Copyright [year] [name of copyright owner]".
#
# Copyright 2015 ForgeRock AS.
# Copyright 2015-2016 ForgeRock AS.

#
# Documentation messages
@@ -19,19 +19,21 @@
CATEGORY_ACCESS_CONTROL=Access Control.
CATEGORY_ADMIN=the administration framework.
CATEGORY_ADMIN_TOOL=the tool like the offline installer and uninstaller.
CATEGORY_AUDIT=common audit event handling.
CATEGORY_BACKEND=generic backends.
CATEGORY_CONFIG=configuration handling.
CATEGORY_CORE=the core server.
CATEGORY_DSCONFIG=the dsconfig administration tool.
CATEGORY_EXTENSIONS=server extensions (for example, extended operations, \
  SASL mechanisms, password storage schemes, password validators, and so on).
CATEGORY_JEB=the JE backend.
CATEGORY_JVM=the Java Virtual Machine.
CATEGORY_LOG=the server loggers.
CATEGORY_PLUGIN=plugin processing.
CATEGORY_PROTOCOL=connection and protocol handling (for example, ASN.1 and LDAP).
CATEGORY_QUICKSETUP=quicksetup tools.
CATEGORY_RUNTIME_INFORMATION=the runtime information.
CATEGORY_SCHEMA=the server schema elements.
CATEGORY_SDK=the OpenDJ LDAP SDK.
CATEGORY_SYNC=replication.
CATEGORY_TASK=tasks.
CATEGORY_THIRD_PARTY=third-party (including user-defined) modules.