/*
   XBN Java:  Generically useful, non-GUI Java code.
   http://sourceforge.net/projects/xbnjava

   Copyright (C) 1997-2003, Jeff Epstein
   All rights reserved.

   Modifications: No

   Redistribution in binary form, with or without modifications, are permitted provided that the following conditions are met:

      * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
      * If modifications are made to source code then this license should indicate that fact in the "Modifications" section above.
      * Neither the author, nor the contributors may be used to endorse or promote products derived from this software without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   [NOTE:  This license contains NO advertising clause.]
 */
package xbn.programs;
   import xbn.XBNObject;
      import xbn.jdlcode.UtilJDLCode;
      import xbn.output.OWFile;
      import xbn.output.Outputter;

      import org.apache.commons.cli.CommandLine;
      import org.apache.commons.cli.OptionBuilder;
      import org.apache.commons.cli.Option;
      import org.apache.commons.cli.Options;


/**
   <P>An application to test and report on the validity of all JavaDoc Link Codes.  A pre-requisite for using this application is to actually put a <a href="~JD~pkgjdlc~EJD~">JavaDoc Link Code</a> into your source code.  This application won't break if you don't have any jdlcodes, it'll  just result in "0 links found, 0 links bad".</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/programs/ReportBadJDLinkCodes.java">ReportBadJDLinkCodes.java</A>.</I></CODE></P>

   <P><I>Although not directly related to JavaDoc links, this application also verifies that all source code links (like right below) point to existing files.</I></P>

   <P>In the report, a valid JavaDoc Link Code is denoted by ".".  An invalid one denoted by "x".  There are many options (command line parameters) for customizing this report.</P>

   <P><I>This process cannot catch errors regarding <A HREF="~JD~jdf~EJD~#hasJDLCsIndirectly()">indirect</A> JavaDoc Link Codes.  Indirect-related errors are only detected by the <CODE>javadoc</CODE> process (using the XBNDoclet).  Unfortunately, there is no easy way to report these errors as a whole.  <CODE>javadoc</CODE> will crash at the first error it finds (indirect or not), and inform you only of <B>it</B>.</I></P>

   <P>This application uses <A HREF="~JD~utiljdlc~EJD~">UtilJDLCode</A>.<A HREF="~JD~utiljdlc#reportJDLinkCodeErrors(s,s,b,s,s,b,b,b,s,ow)~EJD~">reportJDLinkCodeErrors</A> for the actual analysis.</P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class ReportBadJDLinkCodes extends XBNObject  {
   //Define and describe all command line parameters...START
      private static final Option optClassMap = OptionBuilder.withArgName("file")
         .hasArg()
         .isRequired()
         .withDescription("[s_docletClassMapFile]  Doclet Class Map file")
         .create("dcm");
      private static final Option optDirToAnalyze = OptionBuilder.withArgName("dir")
         .hasArg()
         .isRequired()
         .withDescription("[s_dirToAnalyze]  Directory to analyze")
         .create("dir2nlz");
      private static final Option optRelUrl2Cd = OptionBuilder.withArgName("relurldir")
         .hasArg()
         .withDescription("[s_relUrlJDToCodeBases]  Relative url from JavaDoc base to src-in-build")
         .create("rujd2sib");
      private static final Option optSrcBase = OptionBuilder.withArgName("dir")
         .hasArg()
         .withDescription("[s_sourceCodeBaseDir]  Base directory for source code")
         .create("srcbase");
      private static final Option optAnlzJDLCs = OptionBuilder
         .withDescription("[b_analyzeJDLCodes]  Analyze JavaDoc Link Codes")
         .create("nlzjdlcs");
      private static final Option optListSCLs = OptionBuilder
         .withDescription("[b_listAllSCLs]  List all source code links before error report")
         .create("lscl");
      private static final Option optXMsgOTF = OptionBuilder
         .withDescription("[b_printXOnTheFly]  Print exception messages during analysis")
         .create("xotf");
      private static final Option optVrfLnkTrgt = OptionBuilder
         .withDescription("[b_cibJDLCTarget]  Verify link destinations exist")
         .create("vltx");
      private static final Option optPkgPrefx = OptionBuilder.withArgName("str")
         .hasArg()
         .withDescription("[s_pkgPrefix]  The Java package prefix, when analyzing a sub-package directory")
         .create("pkgprefx");
      private static final Option optOutputFile = OptionBuilder.withArgName("file")
         .hasArg()
         .withDescription("[ow_output]  Also send output to this file")
         .create("outfile");

      private static final Options opts = new Options();
   //Define and describe all command line parameters...END

   /**
      <P>Run the application.</P>
    **/
   public static void main(String[] as_cmdLineParams)  {
      sopl("ReportBadJDLinkCodes...START");

      //Prepare, set and get command line parameters...START
         opts.addOption(optClassMap);
         opts.addOption(optDirToAnalyze);
         opts.addOption(optRelUrl2Cd);
         opts.addOption(optSrcBase);
         opts.addOption(optAnlzJDLCs);
         opts.addOption(optListSCLs);
         opts.addOption(optXMsgOTF);
         opts.addOption(optVrfLnkTrgt);
         opts.addOption(optPkgPrefx);
         opts.addOption(optOutputFile);

         UtilCommandLine ucl = new UtilCommandLine(opts, 80,
            "xbn.programs.ReportBadJDLinkCodes",
            null,
            "\nFor documentation on these parameters, see the documentation for UtilJDLCode.reportJDLinkCodeErrors().",
            true);

         CommandLine cl = ucl.getCommandLine(as_cmdLineParams);

         String sDocletClassMap = cl.getOptionValue("dcm");
         boolean bAnalyzeJDLCs = cl.hasOption("nlzjdlcs");
         boolean bReportAllSCLs = cl.hasOption("scl");
         String sSourceCodeBaseDir = cl.getOptionValue("srcbase", null);
         String sRelUrlJDToSourceBases = cl.getOptionValue("rujd2sib");
         boolean bPrintXOnTheFly = cl.hasOption("xotf");
         boolean bVerifyLinkTargetsExist = cl.hasOption("vltx");
         Outputter optr = ucl.getOSDOOrOSDOAndFile("outfile", false);
         String sDirToAnalyze = cl.getOptionValue("dir2nlz");
         String sPkgPrefix = cl.getOptionValue("pkgpref", null);
      //Prepare, set and get command line parameters...END

      (new UtilJDLCode()).reportJDLinkCodeErrors(sDocletClassMap, sDirToAnalyze, bAnalyzeJDLCs, sSourceCodeBaseDir, sRelUrlJDToSourceBases, bReportAllSCLs, bVerifyLinkTargetsExist, bPrintXOnTheFly, sPkgPrefix, optr.getOWriter());

      if(cl.hasOption("outfile"))  {
         optr.write("\n\nOutput written to '" + ((OWFile)optr.getOWriter()).getPath() + "'");
      }

      optr.write("ReportBadJDLinkCodes...END");
   }
}