/*
   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.AssertException;
   import xbn.named.Named;
   import xbn.string.UtilString;
   import xbn.string.padchop.PadChopString;
   import xbn.string.padchop.ConfigPad;

/**
   <P>A JDFile that is explicitely defined it the jdlcode doclet class map configuration file.  See <A HREF="~JD~utiljdlc#getJDCAFromFLR(flr)~EJD~">getJDCAFromFLR</A>.</P>

   <P>Manage a set of JDClasses with <A HREF="~JD~jdca~EJD~">JDCArray</A></P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/jdlcode/JDClass.java">JDClass.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 JDClass extends JDFile implements Named  {
   private UtilString uStr = new UtilString();

   private String sAbbreviation = null;
   private PackageType pType = null;
   private boolean bNameIsAbbrevOrFQCN = false;
   private PadChopString pcsPad = new PadChopString(new ConfigPad(20));

   /**
      <P>Create a JDClass.</P>

      @param  s_abbreviation  The abbreviation assigned to this class.  For example, you might assign "s" to <CODE>java.lang.String</CODE>.  Must contain only letters, digits and underscores.  See <A HREF="#getAbbreviation()">getAbbreviation</A>.
      @param  s_fullyQualifiedClassName  Must conform to the following restrictions:<UL>
         <LI>Must be valid according to the <A HREF="~JD~jdf#jdf(s)~EJD~">super constructor</A></LI>
         <LI>Every <A HREF="~JD~jdf#getPart(i)~EJD~">part</A> must contain only letters, digits and underscores.</LI>
         <LI>The last part may have the special value of "package-summary" or "overview-summary".</LI>
         <LI><A HREF="~JD~jdf#getPart(i)~EJD~">getPart</A>(0) must be valid according to pt_array.<A HREF="~JD~na#doesExist(s)~EJD~">doesExist</A>.</LI>
         <LI><I>If</I> getPart(0) does not exist in pt_array, and <I><A HREF="~JD~jdf~EJD~#getPartCount()">getPartCount</A> equals one <B>and</B> getPart(0) is only lowercase letters</I>, then this JDClass is <A HREF="#isPrimitive()">primitive</A>.</LI>
      </UL>

      @param  pt_array  The PTArray defining all PackageTypes.
    **/
   public JDClass(String s_abbreviation, String s_fullyQualifiedClassName, PTArray pt_array)  {
      super(s_fullyQualifiedClassName);

      throwAXIfBadStr(s_abbreviation, "s_abbreviation", sCNSTR);
      throwAXIfNull(pt_array, "pt_array", sCNSTR);
      if(!uStr.isLetterDigitUnderscore(s_abbreviation))  {
         throwAX("constructor:  s_abbreviation ('" + s_abbreviation + "') may only contain letters, digits and underscores.");
      }

      if(s_abbreviation.length() > 20)  {
         throwAX("constructor:  The length of the abbreviation must range 1..20.  Currently " + s_abbreviation.length() + ".  s_abbreviation='" + s_abbreviation + "'.");
      }

      for(int i = 0; i < getPartCount(); i++)  {
         boolean bLDU = uStr.isLetterDigitUnderscore(getPart(i));
         if(!bLDU)  {
            if(i < (getPartCount() - 1)  ||
               	(!getPart(i).equals("package-summary")  &&
               	 !getPart(i).equals("overview-summary")))  {
               throwAX("constructor:  The fully qualified class name  '" + s_fullyQualifiedClassName + "' may only contain letters, digits, underscores and periods.  Part at array index " + i + " contains illegal characters.  Note the only exception to this rule is when the file name (the last part) is 'overview-summary' or 'package-summary'.");
            }
         }
      }

      sAbbreviation = s_abbreviation;

      try  {
         pType = pt_array.getPackageType(getPart(0));
      }  catch(AssertException ax)  {
         throwAX("constructor:  Attempting to get the PackageType of this JDClass:  " + ax.toString());
      }

      if(pType != null)  {
         pType.setFound();

      }  else  {
         if(getPartCount() > 1)  {
            throwAX("contructor:  The prefix of this class name (prefix='" + getPart(0) + "', s_fullyQualifiedClassName='" + s_fullyQualifiedClassName + "') is not equal to any existing PackageType.  Primitive types may only contain lowercase letters.");
         }
      }

      bNameIsAbbrevOrFQCN = true;
   }

   /**
      <P>Get the abbreviation assigned to this JDClass.</P>

      @return  <B>s_abbreviation</B>, exactly as provided to the <A HREF="~JD~jdc#jdc(s,s,pta)~EJD~">constructor</A>.
    **/
   public String getAbbreviation()  {
      return sAbbreviation;
   }

   /**
      <P>Determine what the name of this JDClass should be.</P>

      <P><I>Get with <CODE><A HREF="#isNameAbbrevOrFQCN()">isNameAbbrevOrFQCN</A></CODE></I></P>

      @param  b_abbrevOrFQCN  If true, then name should be the <A HREF="#getAbbreviation()">abbreviation</A>.  If false, the name should be the <A HREF="~JD~jdf#jdf(s)~EJD~">fully qualified class name.</A>
    **/
   public void setNameAbbrevOrFQCN(boolean b_abbrevOrFQCN)  {
      bNameIsAbbrevOrFQCN = b_abbrevOrFQCN;
   }

   /**
      <P>What is the name of this JDClass?.  The abbreviation or the fully qualified class name?</P>

      <P><I>Set with <CODE><A HREF="#setNameAbbrevOrFQCN(boolean)">setNameAbbrevOrFQCN</A></CODE></I></P>

      @return  <B>true</B>  If the name is the <A HREF="#getAbbreviation()">abbreviation</A>.
      <BR><B>false</B>  If the name is the <A HREF="~JD~jdf#jdf(s)~EJD~">fully qualified class name.</A>
    **/
   public boolean isNameAbbrevOrFQCN()  {
      return bNameIsAbbrevOrFQCN;
   }

   /**
      <P>Get theh name of this JDClass.</P>

      @return  <CODE><A HREF="#getAbbreviation()">getAbbreviation</A>()</CODE>  if <A HREF="#isNameAbbrevOrFQCN()">isNameAbbrevOrFQCN</A> is true.
      <BR><CODE><A HREF="~JD~jdf#getList(s)~EJD~">getList</A>(".")</CODE>  if isNameAbbrevOrFQCN is false.
    **/
   public String getName()  {
      if(isNameAbbrevOrFQCN())  {
         return getAbbreviation();
      }

      return getList(".");
   }

   /**
      <P>Get the PackageType of this JDClass.</P>

      @return  <B>null</B>  If this JDClass is <A HREF="#isPrimitive()">primitive</A>.
      <BR><B>a PackageType object</B>  If this JDClass is <A HREF="#isLocal()">local</A> or <A HREF="#isExternal()">external</A>.
    **/
   public PackageType getPackageType()  {
      return pType;
   }

   /**
      <P>Get the PackageType prefix of this JDClass.</P>

      @return  <B>"primitive"</B>  If this JDClass is <A HREF="#isPrimitive()">primitive</A>.
      <BR><CODE><A HREF="#getPackageType()">getPackageType</A>().<A HREF="~JD~pt~EJD~#getPrefix()">getPrefix</A>()</CODE>  If this JDClass is <A HREF="#isLocal()">local</A> or <A HREF="#isExternal()">external</A>.
    **/
   public String getPackageTypePrefix()  {
      if(isPrimitive())  {
         return "primitive";
      }

      return getPackageType().getPrefix();
   }

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

      @return  <CODE>(<A HREF="#getPackageType()">getPackageType</A>() == null)</CODE>
    **/
   public boolean isPrimitive()  {
      return (getPackageType() == null);
   }

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

      @return  <B>true</B>  If both <A HREF="#isPrimitive()">isPrimitive</A> and <CODE><A HREF="#getPackageType()">getPackageType</A>().<A HREF="~JD~pt~EJD~#isExternal()">isExternal</A>()</CODE> equal false.
    **/
   public boolean isLocal()  {
      if(isPrimitive())  {
         return false;
      }

      return !getPackageType().isExternal();
   }

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

      @return  <B>true</B>  If <A HREF="#isPrimitive()">isPrimitive</A> equals false and <CODE><A HREF="#getPackageType()">getPackageType</A>().<A HREF="~JD~pt~EJD~#isExternal()">isExternal</A>()</CODE> equals true.
    **/
   public boolean isExternal()  {
      if(isPrimitive())  {
         return false;
      }

      return getPackageType().isExternal();
   }

   /**
      <P>Get the external url for this JDClass.</P>

      @return  <CODE><A HREF="#getPackageType()">getPackageType</A>().<A HREF="~JD~pt~EJD~#getExternalUrl()">getExternalUrl</A>()</CODE>
      @exception  AssertException  if <A HREF="#isExternal()">isExternal</A> equals false.
    **/
   public String getExternalUrl()  {
      if(!isExternal())  {
         throwAX("getExternalUrl:  isExternal() equals false.  The package type of this JDClass is either primitive or local.");
      }

      return getPackageType().getExternalUrl();
   }

   /**
      <P>Get some information about this JDClass.</P>
    **/
   public String toString()  {
      return pcsPad.get(getAbbreviation()) + super.toString();
   }
}