/*
   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.jdlcode;
   import xbn.XBNObject;
   import xbn.array.APString;
   import xbn.array.BinarySearchData;
   import xbn.array.primitive.PASString;

   import java.util.StringTokenizer;
   import java.io.File;

/**
   <P>Represents a single JavaDoc (html) file that may or may not contain JavaDoc Link Codes.</P>

   <P>JDFiles can have JavaDoc Link Codes <A HREF="#hasJDLCsDirectly()">directly</A>, <A HREF="#hasJDLCsIndirectly()">indirectly</A> or <A HREF="#hasNoJDLCodes()">not at all</A>.</P>

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

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class JDFile extends XBNObject  {
   //ENTIRE strings used four or more times.
      private static final String sPD = ".";

   private static final String[] asNO_LINKS = new String[]  {"allclasses-frame", "help-doc", "index", "overview-frame", "overview-tree", "package-frame", "package-list", "package-tree", "packages", "serialized-form"};
   private static final String[] asLINKS_INDIRECT = new String[]  {"deprecated-list", "index-1", "index-10", "index-11", "index-12", "index-13", "index-14", "index-15", "index-16", "index-17", "index-18", "index-19", "index-2", "index-20", "index-21", "index-22", "index-23", "index-24", "index-25", "index-26", "index-3", "index-4", "index-5", "index-6", "index-7", "index-8", "index-9"};

   private final APString apsNO_LINKS = new APString(asNO_LINKS);
   private final APString apsLINKS_INDIRECT = new APString(asLINKS_INDIRECT);

   private final BinarySearchData bsdNO_LINKS = new BinarySearchData(apsNO_LINKS.getLength(), true);
   private final BinarySearchData bsdLINKS_INDIRECT = new BinarySearchData(apsLINKS_INDIRECT.getLength(), true);


   private String[] asFile = null;
   private PASString pass = null;
   private PASString passPkgOnly = null;
   private boolean bLnksDrct = false;
   private boolean bLnksIndrct = false;

   /**
      <P>Create a JDFile from the path/filename combination found in HTMLStandardWriter.  It is expected that this constructor <I>only</I> be called by HTMLStandardWriter, via the "javadoc" process.</P>

      @param  s_relDir  The relative url directory to the class or html file.  For example, if <CODE>xbn.jdlcode.UtilJDLCode</CODE> is a class in your class map configuration text file, then this variable should equal <CODE>"xbn/jdlcode"</CODE>.  Another example:  The file <CODE>c:\\home\\my_javadoc\\index-files\\index-1.html</CODE> has a relative url directory of <CODE>index-files</CODE>
      @param  s_fileName  The name of the class or html file. For example, if <CODE>xbn.jdlcode.UtilJDLCode</CODE> is in your class map, then this variable should equal <CODE>"UtilJDLCode"</CODE>.  Another example:  The file <CODE>c:\\home\\my_javadoc\\index-files\\index-1.html</CODE> has a file name of <CODE>index-1.html</CODE>
    **/
   public JDFile(String s_relDir, String s_fileName)  {

      throwAXIfNull(s_relDir, "s_relDir", sCNSTR);
      throwAXIfBadStr(s_fileName, "s_fileName", sCNSTR);

      boolean bEndsInHtml = s_fileName.endsWith(".html");
      if(!s_fileName.equals("package-list")  &&  !bEndsInHtml  &&
         	!s_fileName.equals("stylesheet.css"))  {
         throwAX("constructor:  It is expected that this constructor be called directly from HtmlStandardWriter.   If it were, then s_fileName would either equal 'package-list', 'stylesheet.css' or end with '.html'.  Currently '" + s_fileName + "'.  Extra information...s_relDir='" + s_relDir + "'.");
      }

      if(bEndsInHtml)  {
         //This ends with ".html".  Delete this postfix.
         //".html".length() = 5
         s_fileName = s_fileName.substring(0, (s_fileName.length() - 5));
      }

      //Split the directory name into an array.

      if(s_relDir.length() < 1)  {
         asFile = new String[] {s_fileName};

      }  else  {
         StringTokenizer st = new StringTokenizer(s_relDir, File.separator);
         createPartArray(st, s_fileName);
      }

      //Should this be locked?
      pass = new PASString(asFile, false);

      defineLinkState(getFileName());
   }

   /**
      <P>Create a JDFile from the fully qualified class name, as found in the class map configuration file.

      @param  s_fqClassName  The fully qualified name to a JavaDoc html file, divided by dots, minus the ".html".  For example:  <CODE>xbn.array.VWObject</CODE> or <CODE>index-files.index-1</CODE>.  Must...<UL>
         <LI>...be non-null, and at least one character in length.</LI>
         <LI>...not start or end with a period.</LI>
         <LI>...not end with ".html".</LI>
         <LI>...not contain "..".</LI>
         <LI>...be less than or equal to 100 characters in length.</LI>
      </UL>

    **/
   public JDFile(String s_fqClassName)  {
      throwAXIfBadStr(s_fqClassName, "s_fqClassName", sCNSTR);

      if(s_fqClassName.startsWith(sPD)  ||
         	s_fqClassName.endsWith(sPD)) {
         throwAX("constructor:  s_fqClassName ('" + s_fqClassName + "') must not start or end with a period ('.').");
      }

      if(s_fqClassName.endsWith(".html")) {
         throwAX("constructor:  s_fqClassName ('" + s_fqClassName + "') must not end with '.html'.");
      }

      if(s_fqClassName.indexOf("..") != -1) {
         throwAX("constructor:  '..' found in s_fqClassName ('" + s_fqClassName + "') at index " + s_fqClassName.indexOf("..") + sPD);
      }

      if(s_fqClassName.length() > 100)  {
         throwAX("constructor:  The length of s_fqClassName ('" + s_fqClassName + "') must have between 1 and 100 characters, inclusive.  Currently " + s_fqClassName.length() + sPD);
      }

      StringTokenizer st = new StringTokenizer(s_fqClassName, sPD);

      createPartArray(st, null);

      //Why is this not locked?
      pass = new PASString(asFile, false);

      defineLinkState(getFileName());
   }

   /**
      <P>How many parts exist in the name of this JDClass?</P>

      <P>Each part is divided by a period.  For example, <CODE>xbn.XBNObject</CODE> has two parts, and <CODE>xbn.jdlcode.JDFile</CODE> has three.</P>
    **/
   public final int getPartCount()  {
      return asFile.length;
   }

   /**
      <P>How many directories are there in the file represented by this JDFile?</P>

      @return  <CODE>(<A HREF="#getPartCount()">getPartCount</A>() - 1)</CODE>
    **/
   public final int getDirCount()  {
      return (getPartCount() - 1);
   }

   /**
      <P>Get the part at the requested array index.</P>

      @param  i_dx  The array index for the (private, internal) string array of parts.  Must range zero..(<A HREF="#getPartCount()">getPartCount</A>() - 1).
    **/
   public final String getPart(int i_dx)  {
      try  {
         return pass.getString(i_dx);
      }  catch(ArrayIndexOutOfBoundsException aioobx)  {
         throwAX("getPart:  i_dx (" + i_dx + ") is invalid.  getPartCount()" + getPartCount() + sPD);
      }

      //Never reached.  Needed for compile.
      return null;
   }

   /**
      <P>Get the name of this JDFile.</P>

      @return  <CODE><A HREF="#getPart(int)">getPart</A>(<A HREF="#getPartCount()">getPartCount</A>() - 1)</CODE>
    **/
    public final String getFileName()  {
       return getPart(getPartCount() - 1);
    }


   /**
      <P>Get an PASString representing the part names.  This PASString object is created once, at constructor time.</P>
    **/
   public PASString getPASString()  {
      return pass;
   }

   /**
      <P>Get an PASString representing all the part names, except the final part (the file name itself).</P>

      <P>This PASString object is created once, when this function is first called.</P>
    **/
   public PASString getPASSPackage()  {
      if(passPkgOnly == null)  {
         String[] asPkgOnly = new String[getDirCount()];

         for(int i = 0; i < asPkgOnly.length; i++)  {
            asPkgOnly[i] = pass.getString(i);
         }

         passPkgOnly = new PASString(asPkgOnly, true);
      }

      return passPkgOnly;
   }

   /**
      <P>Get a list of all part names, with the requested divider string.</P>

      @param  s_divider  The dividing string.  May not be null.
      @return  Assuming this array of parts:  <CODE>{"xbn", "jdlcode", "JDFile"}</CODE>, if s_divider equals...<UL>
         <LI>...".": &nbsp;<B><CODE>xbn.jdlcode.JDFile</CODE></B></LI>
         <LI>..."/": &nbsp;<B><CODE>xbn/jdlcode/JDFile</CODE></B></LI>
         <LI>..."bla": &nbsp;<B><CODE>jeffybladocletblaJDFile</CODE></B></LI>
      </UL>

      <P>Specifically, this returns <CODE><A HREF="#getPASString()">getPASString</A>().<A HREF="~JD~pa#getList(s)~EJD~">getList</A>(s_divider)</CODE></P>

    **/
   public String getList(String s_divider)  {
      return getPASString().getList(s_divider);
   }

   /**
      <P>Get a list of the package name for this JDFile (all parts but the last, which is the file name).</P>

      @param  s_divider  The dividing string.  May not be null.
      @return  Assuming this array of parts:  <CODE>{"xbn", "jdlcode", "JDFile"}</CODE>, if s_divider equals...<UL>
         <LI>...".": &nbsp;<B><CODE>xbn.jdlcode</CODE></B></LI>
         <LI>..."/": &nbsp;<B><CODE>xbn/jdlcode</CODE></B></LI>
         <LI>..."bla": &nbsp;<B><CODE>jeffybladoclet</CODE></B></LI>
      </UL>

      <P>Specifically, this returns <CODE><A HREF="#getPASSPackage()">getPASSPackage</A>().<A HREF="~JD~pa#getList(s)~EJD~">getList</A>(s_divider)</CODE></P>
    **/
   public String getPackageList(String s_divider)  {
      return getPASSPackage().getList(s_divider);
   }

   /**
      <P>Get the prefix for this JDFile.</P>

      @return  <B>""</B>  If <A HREF="#getDirCount()">getDirCount</A> equals zero.
      <BR><CODE><A HREF="#getPart(int)">getPart</A>(0)</CODE>  If otherwise.
    **/
   public String getPackagePrefix()  {
      if(getDirCount() == 0)  {
         return sES;
      }

      return getPart(0);
   }

   /**
      <P>Is the provided JDFile in the same package as <I>this</I> JDFile?.</P>

      @param  jd_file  The JDFile, whose package should be declared to <I>this</I> JDFile's package.  May not be null.
      @return  <CODE>jd_file.<A HREF="~JD~getPackageList(s)~EJD~">getPackageList</A>(".").<A HREF="~JD~s#equals(o)~EJD~">equals</A>(getPackageList("."))</CODE>
    **/
   public boolean isInSamePackageAs(JDFile jd_file)  {
      try  {
         return jd_file.getPackageList(sPD).equals(getPackageList(sPD));
      }  catch(NullPointerException npx)  {
         throwAX("isInSamePkg:  jd_file is null.");
      }

      //Never reached.  Required for compile.
      return false;
   }

   /**
      <P>Is this JDFile local?</P>

      <P>See <A HREF="#isPrimitive()">isPrimitive</A> and <A HREF="#isExternal()">isExternal</A>.</P>

      <H5>What does local mean?</H5>

      <P>Let's say you generate your JavaDoc into <CODE>C:\\my_java_code\\javadoc\\</CODE>, and the following three directories--after running the JavaDoc command--exist in it:  "index-files", "xbn", "random_java_pkg".  index-files is a directory created automatically by JavaDoc.  xbn and random_java_pkg are the directories in which the documentation for <I>my</I> packages are held.  So the xbn.* and random_java_pkg.* packages are local.</P>

      @return  <B>true</B>  All JDFiles are local.
    **/
   public boolean isLocal()  {
      return true;
   }

   /**
      <P>Is this JDFile primitive?</P>

      <P>See <A HREF="#isLocal()">isLocal</A> and <A HREF="#isExternal()">isExternal</A>.</P>

      <H5>What does primitive mean?</H5>

      <P>int, char, long, float, ...</P>

      <P>For the sake of Javadoc, primitive variables cannot be linked to, nor from.  There are no JavaDoc html pages existing for these primitive types.</P>

      @return  <B>false</B>  All JDFiles are local.
    **/
   public boolean isPrimitive()  {
      return false;
   }

   /**
      <P>Is this JDFile external?</P>

      <P>See <A HREF="#isLocal()">isLocal</A> and <A HREF="#isPrimitive()">isPrimitive</A>.</P>

      <H5>What does external mean?</H5>

      <P>All packages that are not local, but are defined in the class map configuration text file--even if you never link to that package in your documentation.</P>


      @return  <B>false</B>  All JDFiles are local.
    **/
   public boolean isExternal()  {
      return false;
   }

   /**
      <P>Get some information about this JDFile.</P>
    **/
   public String toString()  {
      return getList(sPD);
   }

   /**
      <P>Does this JDFile contain <I>no</I> JavaDoc Link Codes?</P>

      <P>If the <A HREF="#getFileName()">name</A> of this file exists in <A HREF="#getAPSLinkPagesNONE()">getAPSLinkPagesNONE</A>, then this is a file that is not editable at all by you (the Java programmer).  Rather, this file is created solely by the <CODE>javadoc</CODE> process.  Therefore, this page cannot contain nor display any JavaDoc Link Codes, either <A HREF="#hasJDLCsDirectly()">directly</A> or <A HREF="#hasJDLCsIndirectly()">indirectly</A>.</P>

      <P>JDFiles with no JavaDoc Link Codes cannot be analyzed by <A HREF="~JD~utiljdlc~EJD~">UtilJDLCode</A>.<A HREF="~JD~utiljdlc#crashIfBadTarget(jdf,slc,jdca,b)~EJD~">crashIfBadTarget</A>.</P>

      @return  <CODE>(!<A HREF="#hasJDLCsDirectly()">hasJDLCsDirectly</A>()  &amp;&amp;  !<A HREF="#hasJDLCsIndirectly()">hasJDLCsIndirectly</A>())</CODE>
    **/
   public final boolean hasNoJDLCodes()  {
      return (!hasJDLCsDirectly()  &&  !hasJDLCsIndirectly());
   }

   /**
      <P>Is it possible for this JDFile to contain JavaDoc Link Codes "directly"?</P>

      <P>If the <A HREF="#getFileName()">name</A> of this file does <I>not</I> exist in either <A HREF="#getAPSLinkPagesNONE()">getAPSLinkPagesNONE</A> or <A HREF="#getAPSLinkPagesINDIRECT()">getAPSLinkPagesINDIRECT</A>, then this JDFile represents one of the actual "*.java" or "package.html" files in your packages.  It therefore can contain JavaDoc Link Codes in it.</P>

      <H4>For example</H4>

      <P><A HREF="~JD~vwo~EJD~">This link</A> was written by me in <A HREF="../../../CODE/xbn/jdlcode/JDFile.java">JDFile.java</A>, has this JavaDoc Link Code as the url:</P>

      <P><CODE>\~JD\~vwo\~EJD\~</CODE></P>

      <P>It is displayed in this file (JDFile.html), "directly", with the resulting relative url:</P>

      <P><CODE>~JD~vwo~EJD~</CODE></P>

      <H4>Direct and Indirect</H4>

      <P>JDFiles that have JavaDoc Link Codes directly can also display them <A HREF="#hasJDLCsIndirectly()">indirectly</A>.  For example, <A HREF="../../../CODE/xbn/template/Template.java">Template.java</A> has no documentation written in it for getName().  However, <A HREF="~JD~t~EJD~">Template.html</A> inherits the documentation for this function from <A HREF="~JD~n~EJD~">Named</A>.<A HREF="~JD~n~EJD~#getName()">getName</A>.  Note that Template.html#<A HREF="~JD~t~EJD~#getName()">getName</A> says "Description copied from...".</P>

      <P>Technically speaking:  When <CODE>[yourJDFile].hasJDLCsDirectly()</CODE> equals true, <CODE>[yourJDFile].hasJDLCsIndirectly()</CODE> also (always) equals true.</P>

      <H4><CODE>UtilJDLCode.crashIfBadTarget()</CODE></H4>

      <P>You can ensure that indirect JavaDoc Link Codes are pointing to a target that actually exists, by using <A HREF="~JD~utiljdlc~EJD~">UtilJDLCode</A>.<A HREF="~JD~utiljdlc#crashIfBadTarget(jdf,slc,jdca,b)~EJD~">crashIfBadTarget</A>.  This function is optionally called by the <CODE>javadoc</CODE> and <A HREF="~JD~rbjdlc~EJD~">ReportBadJDLinkCodes</A> processes.</P>

      <P><I>The <A HREF="~JD~slc~EJD~">SplitLinkCode</A> <A HREF="~JD~slc#slc(s)~EJD~">constructor</A> also validates JavaDoc Link Codes, but only to ensure proper formatting.</I></P>

      <P><TABLE ALIGN="center" BORDER="1" CELLSPACING="0" CELLPADDING="2" WIDTH="100%" BGCOLOR="#FFFFFF"><TR ALIGN="left" VALIGN="middle">
         <TD><B>Process</B></TD>
         <TD><B>How to turn target validation on</B></TD>
         <TD><B>How to turn it off</B></TD>
      </TR><TR>
         <TD><CODE>javadoc</CODE></TD>
         <TD>Go into <A HREF="../../../CODE/etcetera/javadoc/xbn_doclet/HtmlStandardWriter.java">HtmlStandardWriter.java</A>, change the second-to-last boolean (the third-to-last overall) parameter of "<A HREF="~JD~utiljdlc#getJavadocLine(s,jdf,jdca,b,b,tlao)~EJD~">getJavadocLine</A>" to true, and recompile (sorry, no convenient method at this point..).</TD>
         <TD>Change the second-to-last boolean parameter of "getJavadocLine" to false and recompile.</TD>
      </TR><TR>
         <TD><CODE>ReportBadJDLinkCodes</CODE></TD>
         <TD>When you run ReportBadJDLinkCodes, set the third command-line parameter ("ENSURE_LINK_TARGETS_EXIST") to "true".</TD>
         <TD>Set the third command-line parameter to "false".</TD>
      </TR></TABLE></P>

      <P>Validating direct JavaDoc Link Codes has precedence over <A HREF="#hasJDLCsIndirectly()">indirect</A>.  When direct ones are validated (via either process, or the crashIfBadTarget function) indirect ones <I>may</I> be validated.  When direct ones are not being validated, it is not possible to validate indirect ones.</P>

      @return  <B>true</B>  If it is possible for the html file (as represented by this JDFile) to have JavaDoc Link Codes directly.
      <BR><B>false</B>  If it is not possible.
    **/
   public final boolean hasJDLCsDirectly()  {
      return bLnksDrct;
   }
   /**
      <P>Is it possible for this JDFile contain JavaDoc Link Codes "indirectly" (<I>Examples:  <A HREF="~JD~jdf#getList(s)~EJD~">good</A> and <A HREF="#getList(java.lang.String)">bad</A></I>)?</P>

      <!-- GOOD CATCH, MY FRIEND:  The "bad" link is actually hard-coded, and not a JavaDoc Link Code.  If it were, then the javadoc process would crash when attempting to generate index-8.html.  :'  ) -->

      <P>If the <A HREF="#getFileName()">name</A> of this file exists in <A HREF="#getAPSLinkPagesINDIRECT()">getAPSLinkPagesINDIRECT</A>, then this is a file that is both...<UL>
         <LI>...not editable at all by you (the Java programmer).  Rather, this file is created solely by the <CODE>javadoc</CODE> process.</LI>
         <LI>...<I>is</I> a page that displays JavaDoc Link Codes indirectly.  "Indirectly", meaning the links are displayed in this page, but only as a reference to the page in which it actually (directly) exists.</LI>
      </UL></P>

      <H4>For example</H4>

      <P>The "good" and "bad" example links above were written in <A HREF="../../../CODE/xbn/jdlcode/JDFile.java">JDFile.java</A>, having these urls:</P>

      <P><B>Good:</B>  <CODE>\~JD\~jdf#getList(s)\~EJD\~</CODE>
      <BR><B>Bad:</B>  <CODE>\~JD\~getList(s)\~EJD\~</CODE></P>

      <P>These are displayed in this file (JDFile.html), "directly", with the urls:</P>

      <P><B>Good:</B>  <CODE>~JD~jdf#getList(s)~EJD~</CODE>
      <BR><B>Bad:</B>  <CODE>#getList(java.lang.String)</CODE></P>

      <P>These same links are also displayed "indirectly" in the <A HREF="../../index-files/index-8.html">"H" index</A> page, with these urls:</P>

      <P><B>Good:</B>  <CODE>../xbn/jdlcode/JDFile.html#getList(java.lang.String)</CODE>
      <BR><B>Bad:</B>  <CODE>#getList(java.lang.String)</CODE></P>

      <P><I>The "good" link works in both JDFile.html and the "H" index page.  The "bad" one <B>works</B> in JDFile (this class, <B>this</B> function's first sentence of documentation), but <B>not</B> the "H" index.</I></P>

      <P>All JavaDoc Link Codes existing in the first sentence of a JavaDoc Block (as the "good" and "bad" links are in this) are also displayed in index and, potentially, deprecated pages.  Therefore, to prevent errors such as demonstrated with the "bad" link, ensure that you provide the class prefix to every first-sentence JavaDoc Link Code.</P>

      <H4>Indirect and Direct</H4>

      <P>When <CODE>[yourJDFile].hasJDLCsIndirectly()</CODE> equals true, <CODE>[yourJDFile].<A HREF="#hasJDLCsDirectly()">hasJDLCsDirectly</A>()</CODE> may equal true or false.</P>

      <P>JDFiles that have JavaDoc Link Codes indirectly may or may not have them directly.  For example, as described in the documentation for hasJDLCsDirectly, Template.html has both indirect and direct.  However, all index pages have only indirect.</P>

      <H4><CODE>UtilJDLCode.crashIfBadTarget()</CODE></H4>

      <P>You can ensure that indirect JavaDoc Link Codes are pointing to a target that actually exists, by using <A HREF="~JD~utiljdlc~EJD~">UtilJDLCode</A>.<A HREF="~JD~utiljdlc#crashIfBadTarget(jdf,slc,jdca,b)~EJD~">crashIfBadTarget</A>.  This function is optionally called by the <CODE>javadoc</CODE> process.</P>

      <P><I>The <A HREF="~JD~slc~EJD~">SplitLinkCode</A> <A HREF="~JD~slc#slc(s)~EJD~">constructor</A> also validates JavaDoc Link Codes, but only to ensure proper formatting.</I></P>

      <P>Since these JDFiles contain no JavaDoc Link Codes directly, you may or may not want the targets verified.</P>

      <P><TABLE ALIGN="center" BORDER="1" CELLSPACING="0" CELLPADDING="2" WIDTH="100%" BGCOLOR="#FFFFFF"><TR ALIGN="left" VALIGN="middle">
         <TD><B>Process</B></TD>
         <TD><B>How to turn target validation on</B></TD>
         <TD><B>How to turn it off</B></TD>
      </TR><TR>
         <TD><CODE>javadoc</CODE></TD>
         <TD>Go into <A HREF="../../../CODE/etcetera/javadoc/xbn_doclet/HtmlStandardWriter.java">HtmlStandardWriter.java</A>, change the last boolean (the second-to-last overall) parameter of "<A HREF="~JD~utiljdlc#getJavadocLine(s,jdf,jdca,b,b,tlao)~EJD~">getJavadocLine</A>" to false, and recompile (sorry, no convenient method at this point..).</TD>
         <TD>Change the last boolean parameter of "getJavadocLine" to true and recompile.</TD>
      </TR><TR>
         <TD><CODE><A HREF="~JD~rbjdlc~EJD~">ReportBadJDLinkCodes</A></CODE></TD>
         <TD><I>N/A.  Indirect JavaDoc Link Codes cannot be checked by this process</I></TD>
         <TD>&nbsp;</TD>
      </TR></TABLE></P>

      <P><I>This table assumes direct JavaDoc Link Codes <B>are</B> being validated.</I></P>

      <P>Validating <A HREF="#hasJDLCsDirectly()">direct</A> JavaDoc Link Codes has precedence over indirect.  When direct ones are being validated (via either process) indirect ones <I>may</I> be validated.  When direct ones are not being validated, it is not possible to validate indirect ones.</P>

      @return  <B>true</B>  If it is possible for the html file (as represented by this JDFile) to display JavaDoc Link Codes indirectly.
      <BR><B>false</B>  If it is not possible.
    **/
   public final boolean hasJDLCsIndirectly()  {
      return bLnksIndrct;
   }

   /**
      <P>Get the names for all JavaDoc html files that have/display no JavaDoc Link Codes at all.</P>

      <P>See <A HREF="#hasNoJDLCodes()">hasNoJDLCodes</A>.</P>

      @return  <CODE>new <A HREF="~JD~aps#aps(s[])~EJD~">APString</A>(new <A HREF="~JD~s~EJD~">String</A>[]  {"allclasses-frame", "help-doc", "index", "overview-frame", "overview-tree", "package-frame", "package-list", "package-tree", "packages", "serialized-form"}</CODE>

      <P><I>The <A HREF="~JD~aps~EJD~">APString</A> is created only once.</I></P>
    **/
   public final APString getAPSLinkPagesNONE()  {
      return apsNO_LINKS;
   }

   /**
      <P>Get the names for all JavaDoc html files that only display JavaDoc Link Codes indirectly.</P>

      <P>See <A HREF="#hasJDLCsIndirectly()">hasJDLCsIndirectly</A>.</P>

      @return  <CODE>new <A HREF="~JD~aps#aps(s[])~EJD~">APString</A>(new <A HREF="~JD~s~EJD~">String</A>[]  {"deprecated-list", "index-1", "index-10", "index-11", "index-12", "index-13", "index-14", "index-15", "index-16", "index-17", "index-18", "index-19", "index-2", "index-20", "index-21", "index-22", "index-23", "index-24", "index-25", "index-26", "index-3", "index-4", "index-5", "index-6", "index-7", "index-8", "index-9"}</CODE>

      <P><I>The <A HREF="~JD~aps~EJD~">APString</A> is created only once.</I></P>
    **/
   public final APString getAPSLinkPagesINDIRECT()  {
      return apsLINKS_INDIRECT;
   }


   /**
      <P>Does the provided JDFile represent the same file as <I>this</I> JDFile?</P>

      @param  jd_file  The JDFile to compare <I>this</I> against.  May not be null.
      @return  <B>true</B>  If jd_file and <I>this</I>...<UL>
         <LI>...have the same <a href="#getPartCount()">part counts</A>.</LI>
         <LI>...and every <A HREF="~JD~getPart(i)~EJD~">getPart</A>(x) is equal to jd_file.getPart(x).</LI>
      </UL>
      <BR><B>false</B>  If otherwise.
    **/
   public final boolean equals(JDFile jd_file)  {
      try  {
         if(jd_file.getPartCount() != getPartCount())  {
            return false;
         }
      }  catch(NullPointerException npx)  {
         throwAX("equals:  jd_file is null.");
      }
      //The part counts are equal.

      for(int i = 0; i < getPartCount(); i++)  {
         if(!getPart(i).equals(jd_file.getPart(i)))  {
            return false;
         }
      }

      //All parts are equal!
      return true;
   }


   private void createPartArray(StringTokenizer st_okenizer, String s_fileName)  {
      int iArrayLength = st_okenizer.countTokens();
      if(s_fileName != null)  {
         iArrayLength++;
      }

      asFile = new String[iArrayLength];

      int i = 0;
      while(st_okenizer.hasMoreTokens())  {
         String sPart = st_okenizer.nextToken();
         asFile[i++] = sPart;
      }

      if(s_fileName != null)  {
         asFile[asFile.length - 1] = s_fileName;
      }
   }

   private final void defineLinkState(String s_pageName)  {
      if(getBSDIdx(s_pageName, bsdNO_LINKS, asNO_LINKS))  {
         bLnksDrct = false;
         bLnksIndrct = false;

      }  else if(getBSDIdx(s_pageName, bsdLINKS_INDIRECT, asLINKS_INDIRECT))  {
         bLnksIndrct = true;

      }  else  {
         bLnksDrct = true;
      }
   }

   private final boolean getBSDIdx(String s_pageName, BinarySearchData binary_searchData, String[] as_linkPageNames)  {
      binary_searchData.reset();

      while(binary_searchData.getIdxMiddle() != -1)  {
         String sMiddle = as_linkPageNames[binary_searchData.getIdxMiddle()];

         int iComparison = s_pageName.compareTo(sMiddle);
         if(iComparison == 0)  {
            return true;
         }

         binary_searchData.prepareForNextSearch(iComparison < 0);
      }

      return false;
   }
}