CR-658 Fix for OPENDJ-566: Add log reference to OpenDJ docs

Mark Craig

17.03.2012 e3323d107f6d3b2585615b01f19b44421405cba5

CR-658 Fix for OPENDJ-566: Add log reference to OpenDJ docs

 opendj3/pom.xml

@@ -123,6 +123,33 @@
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>2.5.1</version>
        <executions>
          <execution>
            <id>unpack-log-ref</id>
            <phase>pre-site</phase>
            <goals>
              <goal>unpack</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <artifactItems>
            <artifactItem>
              <groupId>org.forgerock.opendj</groupId>
              <artifactId>opendj-log-ref</artifactId>
              <version>2.5.0-SNAPSHOT</version>
              <type>jar</type>
              <overWrite>true</overWrite>
              <outputDirectory>${project.build.directory}/logref</outputDirectory>
              <includes>**/*.xml</includes>
            </artifactItem>
          </artifactItems>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.forgerock.commons</groupId>
        <artifactId>forgerock-doc-maven-plugin</artifactId>
        <version>1.1.0-SNAPSHOT</version>

 opendj3/src/main/docbkx/admin-guide/index.xml

@@ -139,6 +139,7 @@
 <xinclude:include href='appendix-controls.xml' />
 <xinclude:include href='appendix-extended-ops.xml' />
 <xinclude:include href='appendix-l10n.xml' />
 <xinclude:include href='../../../../target/logref/log-message-reference.xml' />

 <index />
</book>

 opends/build.xml

@@ -146,6 +146,7 @@
  <property name="msg.dir"         location="src/messages" />
  <property name="msg.prop.dir"    location="${msg.dir}/messages" />
  <property name="msg.javagen.dir" location="${msg.dir}/generated" />
  <property name="msg.logref.dir"  location="${docgen.dir}/logref" />
  <property name="msg.package.dir" location="${classes.dir}/messages" />
  <property name="msg.src.dir"     location="${msg.dir}/src" />

@@ -305,6 +306,97 @@

  </target>


  <target name="generateLogReference" depends="buildtools">
    <typedef name="genlogref"
             classname="org.opends.build.tools.GenerateMessageFile" >
      <classpath>
        <fileset dir="${build.dir}/build-tools">
          <include name="*.jar" />
        </fileset>
      </classpath>
    </typedef>
    <!--
    <genlogref sourceProps="${msg.prop.dir}/xxx_yyy.properties"
               destJava="${msg.logref.dir}/log-ref-xxx-yyy.xml"
               writelogref="true" />
    -->
    <genlogref sourceProps="${msg.prop.dir}/access_control.properties"
               destJava="${msg.logref.dir}/log-ref-access-control.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/admin.properties"
               destJava="${msg.logref.dir}/log-ref-admin.xml"
               writelogref="true" />
    <!-- Ignore admin tool messages while documenting only serious errors.
    <genlogref sourceProps="${msg.prop.dir}/admin_tool.properties"
               destJava="${msg.logref.dir}/log-ref-admin-tool.xml"
               writelogref="true" />
    -->
    <genlogref sourceProps="${msg.prop.dir}/backend.properties"
               destJava="${msg.logref.dir}/log-ref-backend.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/config.properties"
               destJava="${msg.logref.dir}/log-ref-config.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/core.properties"
               destJava="${msg.logref.dir}/log-ref-core.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/dsconfig.properties"
               destJava="${msg.logref.dir}/log-ref-dsconfig.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/extension.properties"
               destJava="${msg.logref.dir}/log-ref-extension.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/jeb.properties"
               destJava="${msg.logref.dir}/log-ref-jeb.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/log.properties"
               destJava="${msg.logref.dir}/log-ref-log.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/plugin.properties"
               destJava="${msg.logref.dir}/log-ref-plugin.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/protocol.properties"
               destJava="${msg.logref.dir}/log-ref-protocol.xml"
               writelogref="true" />
    <!-- Ignore QuickSetup messages that users handle interactively.
    <genlogref sourceProps="${msg.prop.dir}/quicksetup.properties"
               destJava="${msg.logref.dir}/log-ref-quicksetup.xml"
               writelogref="true" />
    -->
    <genlogref sourceProps="${msg.prop.dir}/replication.properties"
               destJava="${msg.logref.dir}/log-ref-replication.xml"
               writelogref="true" />
    <!-- Ignore runtime info messages while documenting only serious errors.
    <genlogref sourceProps="${msg.prop.dir}/runtime_information.properties"
               destJava="${msg.logref.dir}/log-ref-runtime-information.xml"
               writelogref="true" />
    -->
    <genlogref sourceProps="${msg.prop.dir}/schema.properties"
               destJava="${msg.logref.dir}/log-ref-schema.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/task.properties"
               destJava="${msg.logref.dir}/log-ref-task.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/tools.properties"
               destJava="${msg.logref.dir}/log-ref-tools.xml"
               writelogref="true" />
    <genlogref sourceProps="${msg.prop.dir}/utility.properties"
               destJava="${msg.logref.dir}/log-ref-utility.xml"
               writelogref="true" />
    <!-- Ignore version messages while documenting only serious errors.
    <genlogref sourceProps="${msg.prop.dir}/version.properties"
               destJava="${msg.logref.dir}/log-ref-version.xml"
               writelogref="true" />
    -->

    <copy file="${resource.dir}/log-message-reference.xml"
          todir="${msg.logref.dir}" />
    <jar destfile="${docgen.dir}/log-ref.jar"
         basedir="${msg.logref.dir}"
         includes="**/*.xml" />
  </target>

  <!-- Remove all dynamically-generated build files. -->
  <target name="clean" depends="init,cleanadmin,cleanmessages,cleansnmp"
       description="Clean up any files generated during the build process">

 opends/opendj-log-ref/pom.xml

New file
@@ -0,0 +1,90 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
  ! CDDL HEADER START
  !
  ! The contents of this file are subject to the terms of the
  ! Common Development and Distribution License, Version 1.0 only
  ! (the "License").  You may not use this file except in compliance
  ! with the License.
  !
  ! You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
  ! or http://forgerock.org/license/CDDLv1.0.html.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
  ! When distributing Covered Code, include this CDDL HEADER in each
  ! file and include the License file at legal-notices/CDDLv1_0.txt.
  ! If applicable, add the following below this CDDL HEADER, with the
  ! fields enclosed by brackets "[]" replaced with your own identifying
  ! information:
  !      Portions Copyright [yyyy] [name of copyright owner]
  !
  ! CDDL HEADER END
  !
  !      Copyright 2012 ForgeRock AS
  !    
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>

 <parent>
  <artifactId>opendj-server</artifactId>
  <groupId>org.forgerock.opendj</groupId>
  <version>2.5.0-SNAPSHOT</version>
 </parent>

 <artifactId>opendj-log-ref</artifactId>
 <name>OpenDJ Directory Server Log Reference Sources</name>
 <description>
    The module builds the OpenDJ directory server log reference sources in
    DocBook 5 XML form, suitable for inclusion in the core documentation.
  </description>
 <packaging>pom</packaging>

 <build>
  <directory>../build</directory>
  <plugins>
   <plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <version>1.7</version>
    <executions>
     <execution>
      <id>parse-version</id>
      <goals>
       <goal>parse-version</goal>
      </goals>
     </execution>
     <execution>
      <id>attach-artifacts</id>
      <phase>package</phase>
      <goals>
       <goal>attach-artifact</goal>
      </goals>
      <configuration>
       <artifacts>
        <artifact>
         <file>../build/docgen/log-ref.jar</file>
         <type>jar</type>
        </artifact>
       </artifacts>
      </configuration>
     </execution>
    </executions>
   </plugin>

   <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.0</version>
    <configuration>
     <skip>true</skip>
     <skipDeploy>true</skipDeploy>
    </configuration>
   </plugin>
  </plugins>
 </build>
</project>

 opends/pom.xml

@@ -69,6 +69,26 @@
      </notifier>
    </notifiers>
  </ciManagement>

  <repositories>
    <repository>
      <id>forgerock-staging-repository</id>
      <name>ForgeRock Release Repository</name>
      <url>http://maven.forgerock.org/repo/releases</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>forgerock-snapshots-repository</id>
      <name>ForgeRock Snapshot Repository</name>
      <url>http://maven.forgerock.org/repo/snapshots</url>
      <releases>
        <enabled>false</enabled>
      </releases>
    </repository>
  </repositories>

  <properties>
    <ant.home>ext/ant</ant.home>
    <BUILD_NUMBER>0</BUILD_NUMBER>
@@ -78,6 +98,7 @@
    <plugins>
      <plugin>
        <artifactId>maven-antrun-plugin</artifactId>
        <inherited>false</inherited>
        <executions>
          <execution>
            <id>clean</id>
@@ -106,6 +127,18 @@
            </configuration>
          </execution>
          <execution>
            <id>generate-log-reference</id>
            <phase>compile</phase>
            <goals>
              <goal>run</goal>
            </goals>
            <configuration>
              <target>
                <ant target="generateLogReference" />
              </target>
            </configuration>
          </execution>
          <execution>
            <id>generate-docs</id>
            <phase>pre-site</phase>
            <goals>
@@ -192,6 +225,7 @@
        <plugins>
          <plugin>
            <artifactId>maven-antrun-plugin</artifactId>
            <inherited>false</inherited>
            <executions>
              <execution>
                <id>compile</id>
@@ -213,4 +247,7 @@
      </build>
    </profile>
  </profiles>
  <modules>
    <module>opendj-log-ref</module>
  </modules>
</project>

 opends/resource/log-message-reference.xml

New file
@@ -0,0 +1,67 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
  ! CCPL HEADER START
  !
  ! This work is licensed under the Creative Commons
  ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
  ! To view a copy of this license, visit
  ! http://creativecommons.org/licenses/by-nc-nd/3.0/
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
  ! If applicable, add the following below this CCPL HEADER, with the fields
  ! enclosed by brackets "[]" replaced with your own identifying information:
  !      Portions Copyright [yyyy] [name of copyright owner]
  !
  ! CCPL HEADER END
  !
  !      Copyright 2012 ForgeRock AS
  !    
-->
<appendix xml:id='appendix-log-messages'
 xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
 xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
 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'>
 <title>Log Message Reference</title>
 <indexterm>
  <primary>Logs</primary>
  <secondary>Log Message Reference</secondary>
 </indexterm>

 <para>The section on <link xlink:href="admin-guide#logging"
 xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Server
 Logs</citetitle></link> describes logs. Access and audit logs concern client
 operations rather than OpenDJ directory server and tools, and so are not
 listed here. Instead, this appendix covers severe and fatal error messages
 for the directory server and its tools, such as those logged in
 <filename>/path/to/OpenDJ/logs/errors</filename>, and
 <filename>/path/to/OpenDJ/logs/replication</filename>.</para>

 <!-- <xinclude:include href="log-ref-access-control.xml" /> -->
 <!-- <xinclude:include href="log-ref-admin-tool.xml" /> -->
 <xinclude:include href="log-ref-admin.xml" />
 <xinclude:include href="log-ref-backend.xml" />
 <xinclude:include href="log-ref-config.xml" />
 <xinclude:include href="log-ref-core.xml" />
 <xinclude:include href="log-ref-dsconfig.xml" />
 <xinclude:include href="log-ref-extension.xml" />
 <xinclude:include href="log-ref-jeb.xml" />
 <xinclude:include href="log-ref-log.xml" />
 <xinclude:include href="log-ref-plugin.xml" />
 <xinclude:include href="log-ref-protocol.xml" />
 <!-- <xinclude:include href="log-ref-quicksetup.xml" /> -->
 <xinclude:include href="log-ref-replication.xml" />
 <!-- <xinclude:include href="log-ref-runtime-information.xml" /> -->
 <xinclude:include href="log-ref-schema.xml" />
 <xinclude:include href="log-ref-task.xml" />
 <xinclude:include href="log-ref-tools.xml" />
 <xinclude:include href="log-ref-utility.xml" />
 <!-- <xinclude:include href="log-ref-version.xml" /> -->
</appendix>

 opends/src/build-tools/org/opends/build/tools/GenerateMessageFile.java

@@ -46,9 +46,14 @@
import java.io.PrintWriter;
import java.io.DataOutputStream;
import java.io.IOException;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.HashMap;
import java.util.Properties;
import java.util.List;
import java.util.ArrayList;
import java.util.TreeSet;
import java.util.UnknownFormatConversionException;
import java.util.Calendar;
import java.util.Arrays;
@@ -70,6 +75,7 @@
  private File source;
  private File dest;
  private boolean overwrite;
  private boolean writeLogRef;

  static private final String MESSAGES_FILE_STUB =
          "resource/Messages.java.stub";
@@ -517,6 +523,239 @@
  }

  /**
   * Indicates when true that an XML log message reference should be generated
   * instead of a Java messages file.
   *
   * @param xml
   *          true means write an XML log message reference
   */
  public void setWriteLogRef(boolean xml) {
    this.writeLogRef = xml;
  }

  /**
   * Represents a log reference entry for an individual message.
   */
  private class MessageRefEntry implements Comparable<MessageRefEntry>
  {

    private Severity severity;
    private Integer id;
    private String formatString;

    /**
     * Build log reference entry for an log message.
     *
     * @param category
     * @param severity
     * @param ordinal
     * @param formatString
     */
    public MessageRefEntry(final Category category, final Severity severity,
        final Integer ordinal, final String formatString)
    {
      this.severity = severity;
      this.formatString = formatString;
      id = calculateId(category, severity, ordinal);
    }

    private Integer calculateId(final Category category,
        final Severity severity, final Integer ordinal)
    {
      return new Integer(ordinal | category.getMask() | severity.getMask());
    }

    /**
     * Return a DocBook XML &lt;varlistentry&gt; of this log reference entry.
     * This implementation copies the message string verbatim, and does not
     * interpret format specifiers.
     *
     * @return DocBook XML &lt;varlistentry&gt;.
     */
    public String toString()
    {
      return
          "  <varlistentry xml:id=\"log-ref-" + id.intValue() + "\">" + EOL
          + "   <term>ID: " + id.intValue() + "</term>" + EOL
          + "   <listitem>" + EOL
          + "    <para>Severity: " + severity.name() + "</para>" + EOL
          + "    <para>Message: " + formatString + "</para>" + EOL
          + "   </listitem>" + EOL + "  </varlistentry>" + EOL;
    }

    /**
     * Calls {@link #toString()}.
     */
    public String toXML()
    {
      return toString();
    }

    /**
     * The unique message identifier is calculated using the category, severity,
     * and message ordinal.
     *
     * @return unique message identifier
     */
    public Integer getId()
    {
      return this.id;
    }

    /**
     * Compare message entries by unique identifier.
     *
     * @return See {@link java.lang.Comparable#compareTo(Object)}.
     */
    public int compareTo(MessageRefEntry mre)
    {
      return this.id.compareTo(mre.getId());
    }
  }

  /**
   * One-line descriptions for log reference categories
   */
  static private HashMap<String,String> CATEGORY_DESCRIPTIONS;
  static {
    CATEGORY_DESCRIPTIONS = new HashMap<String,String>();
    CATEGORY_DESCRIPTIONS.put("ACCESS_CONTROL", "Access Control.");
    CATEGORY_DESCRIPTIONS.put("ADMIN", "the administration framework.");
    CATEGORY_DESCRIPTIONS.put("ADMIN_TOOL", "the tool like the offline"
            + " installer and uninstaller.");
    CATEGORY_DESCRIPTIONS.put("BACKEND", "generic backends.");
    CATEGORY_DESCRIPTIONS.put("CONFIG", "configuration handling.");
    CATEGORY_DESCRIPTIONS.put("CORE", "the core server.");
    CATEGORY_DESCRIPTIONS.put("DSCONFIG", "the dsconfig administration tool.");
    CATEGORY_DESCRIPTIONS.put("EXTENSIONS", "server extensions for example,"
            + " extended operations, SASL mechanisms, password storage"
            + " schemes, password validators, and so on).");
    CATEGORY_DESCRIPTIONS.put("JEB", "the JE backend.");
    CATEGORY_DESCRIPTIONS.put("LOG", "the server loggers.");
    CATEGORY_DESCRIPTIONS.put("PLUGIN", "plugin processing.");
    CATEGORY_DESCRIPTIONS.put("PROTOCOL", "connection and protocol handling"
            +  " (for example, ASN.1 and LDAP).");
    CATEGORY_DESCRIPTIONS.put("QUICKSETUP", "quicksetup tools.");
    CATEGORY_DESCRIPTIONS.put("RUNTIME_INFORMATION", "the runtime"
            + " information.");
    CATEGORY_DESCRIPTIONS.put("SCHEMA", "the server schema elements.");
    CATEGORY_DESCRIPTIONS.put("SYNC", "the Synchronization.");
    CATEGORY_DESCRIPTIONS.put("TASK", "tasks.");
    CATEGORY_DESCRIPTIONS.put("THIRD_PARTY", "third-party (including"
            + " user-defined) modules.");
    CATEGORY_DESCRIPTIONS.put("TOOLS", "tools.");
    CATEGORY_DESCRIPTIONS.put("USER_DEFINED", "user-defined modules.");
    CATEGORY_DESCRIPTIONS.put("UTIL", "the general server utilities.");
    CATEGORY_DESCRIPTIONS.put("VERSION", "version information.");
  }

  /**
   * Represents a log reference list of messages for a category.
   */
  private class MessageRefCategory
  {
    private Category category;
    private TreeSet<MessageRefEntry> messages;
    private String description;

    MessageRefCategory(final Category category,
        final TreeSet<MessageRefEntry> messages)
    {
      this.category = category;
      this.messages = messages;
      this.description = getDescription(category);
    }

    private String getDescription(final Category category)
    {
      return "<para>This category concerns messages associated with "
          + CATEGORY_DESCRIPTIONS.get(category.name()) + "</para>" + EOL;
    }

    /**
     * Return a DocBook XML &lt;variablelist&gt; of this log reference category.
     *
     * @return DocBook XML &lt;variablelist&gt;
     */
    public String toString()
    {
      StringBuilder entries = new StringBuilder();
      for (MessageRefEntry entry : messages)
      {
        entries.append(entry.toXML());
      }

      return getVariablelistHead() + entries.toString() + getVariablelistTail();
    }

    /**
     * Calls {@link #toString()}.
     */
    public String toXML()
    {
      return toString();
    }

    private String getXMLPreamble()
    {
      DateFormat df = new SimpleDateFormat("yyyy");
      Date now = new Date();
      String year = df.format(now);

      return new StringBuilder()
        .append("<?xml version=\"1.0\" encoding=\"UTF-8\"?>").append(EOL)
        .append("<!--").append(EOL)
        .append("  ! CCPL HEADER START").append(EOL)
        .append("  !").append(EOL)
        .append("  ! This work is licensed under the Creative Commons").append(EOL)
        .append("  ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.").append(EOL)
        .append("  ! To view a copy of this license, visit").append(EOL)
        .append("  ! http://creativecommons.org/licenses/by-nc-nd/3.0/").append(EOL)
        .append("  ! or send a letter to Creative Commons, 444 Castro Street,").append(EOL)
        .append("  ! Suite 900, Mountain View, California, 94041, USA.").append(EOL)
        .append("  !").append(EOL)
        .append("  ! See the License for the specific language governing permissions").append(EOL)
        .append("  ! and limitations under the License.").append(EOL)
        .append("  !").append(EOL)
        .append("  ! If applicable, add the following below this CCPL HEADER, with the fields").append(EOL)
        .append("  ! enclosed by brackets \"[]\" replaced with your own identifying information:").append(EOL)
        .append("  !      Portions Copyright [yyyy] [name of copyright owner]").append(EOL)
        .append("  !").append(EOL)
        .append("  ! CCPL HEADER END").append(EOL)
        .append("  !").append(EOL)
        .append("  !      Copyright " + year + " ForgeRock AS").append(EOL)
        .append("  !").append(EOL)
        .append("-->").append(EOL)
        .toString();
    }

    private String getBaseElementAttrs()
    {
      return "xmlns='http://docbook.org/ns/docbook'"
          + " version='5.0' xml:lang='en'"
          + " xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'"
          + " 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'";
    }

    private String getVariablelistHead()
    {
      return getXMLPreamble() + " <variablelist xml:id=\"log-ref-"
          + this.category.name() + "\" " + getBaseElementAttrs() + ">" + EOL
          + "  <title>Log Message Category: " + category.name() + "</title>"
          + EOL + "  " + this.description;
    }

    private String getVariablelistTail()
    {
      return " </variablelist>" + EOL;
    }

  }

  /**
   * {@inheritDoc}
   */
  @Override
@@ -555,8 +794,13 @@
      // filename without ".properties"
      filename = filename.substring(0, filename.length()-11);
      // change to src-generated directory keeping package name
      if (writeLogRef) {
        pathname = pathname.replace(getProject().getProperty("msg.dir"),
                                    getProject().getProperty("msg.logref.dir"));
      } else {
      pathname = pathname.replace(getProject().getProperty("msg.dir"),
                                  getProject().getProperty("msg.javagen.dir"));
      }


      // append characters from filename to pathname starting with an uppercase
@@ -575,7 +819,11 @@
          sb.append(c);
        }
      }
      if (writeLogRef) {
        sb.append("Messages.xml");
      } else {
      sb.append("Messages.java");
      }

      setDestJava(new File(sb.toString()));
    }
@@ -612,6 +860,8 @@
      String stubLine;
      Properties properties = new Properties();
      properties.load(new FileInputStream(source));
      TreeSet<MessageRefEntry> messageRefEntries =
          new TreeSet<MessageRefEntry>();
      while (null != (stubLine = stubReader.readLine())) {
        if (stubLine.contains("${MESSAGES}")) {
          Integer globalOrdinal = null;
@@ -722,6 +972,21 @@
              }
            }

            if (writeLogRef) {
              // Document only FATAL_ERROR and SEVERE_ERROR messages.
              if (s.name().equalsIgnoreCase("FATAL_ERROR")
                  || s.name().equalsIgnoreCase("SEVERE_ERROR")) {
                MessageRefEntry entry =
                        new MessageRefEntry(
                                c,
                                s,
                                globalOrdinal != null ?
                                        globalOrdinal :
                                        key.getOrdinal(),
                                formatString.replaceAll("<", "&lt;"));
                messageRefEntries.add(entry);
                }
            } else {
            message.setConstructorArguments(
                    "BASE",
                    quote(key.toString()),
@@ -733,6 +998,7 @@
            );
            destWriter.println(message.toString());
            destWriter.println();
            }

            // Keep track of when we use the generic descriptor
            // so that we can report it later
@@ -741,11 +1007,21 @@
            }
          }

          if (writeLogRef) {
            if (messageRefEntries.isEmpty()) {
              destWriter.println("<!-- No message for this category -->");
            } else {
              MessageRefCategory mrc =
                      new MessageRefCategory(globalCategory, messageRefEntries);
              destWriter.println(mrc.toXML());
            }
          }

          log("  Message Generated:" + keyMap.size(), Project.MSG_VERBOSE);
          log("  MessageDescriptor.ArgN:" + usesOfGenericDescriptor,
                  Project.MSG_VERBOSE);

        } else {
        } else if (!writeLogRef) {
          stubLine = stubLine.replace("${PACKAGE}", getPackage());
          stubLine = stubLine.replace("${CLASS_NAME}",
                  dest.getName().substring(0, dest.getName().length() -
@@ -820,6 +1096,8 @@
  }

  private String getPackage() {
    if (writeLogRef) { return "dummy.package.name"; }

    String destPath = unixifyPath(dest.getAbsolutePath());
    String msgJavaGenDir = unixifyPath(
                                   getProject().getProperty("msg.javagen.dir"));
@@ -951,6 +1229,13 @@
    File source = new File("src/messages/messages/tools.properties");
    File dest = new File("/tmp/org/opends/XXX.java");
    GenerateMessageFile gmf = new GenerateMessageFile();

    if (args.length > 0 && args[0].equalsIgnoreCase("generateMessageReference"))
    {
      dest = new File("/tmp/tools-ref.xml");
      gmf.setWriteLogRef(true);
    }

    gmf.setOverwrite(true);
    gmf.setDestJava(dest);
    gmf.setSourceProps(source);