/*
   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.array;
   import xbn.util.XBNLocked;
   import xbn.util.LockOneWay;
   import xbn.util.Utility;

   import java.util.Hashtable;

/**
   <P>Convenience class for creating an AOSLookup.  See <A HREF="~JD~aosl~EJD~">AOSLookup</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/array/AOSLCreator.java">AOSLCreator.java</A>. &nbsp;<B>Example code</B> &nbsp;See the source code for <A HREF="~JD~utila~EJD~">UtilArray</A>.<A HREF="~JD~utila#getAOSLFromPA(pa,b)~EJD~">getAOSLFromPA</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 AOSLCreator extends XBNLocked implements LockOneWay  {
   private VWObject acoAbsolute = null;
   private VWObject acoUnique = null;

   private Hashtable ht = null;
   private AOSLookup aosl = null;

   private boolean bDupStringsOk = false;
   private int iUnqStrCount = -1;
   private boolean bLocked = false;
   private boolean bLastStringUnique = false;
   private boolean bListStrsOnError = false;

   /**
      <P>Create an AOSLCreator with default values.</P>

      <P>Equal to <CODE><A HREF="~JD~aoslc(b)~EJD~">AOSLCreator</A>(true)</CODE></P>
    **/
   public AOSLCreator()  {
      this(true);

   }

   /**
      <P>Create an AOSLCreator.</P>

      <P>Equal to <CODE><A HREF="~JD~aoslc(b,i)~EJD~">AOSLCreator</A>(b_dupStrsOk, -1)</CODE></P>
    **/
   public AOSLCreator(boolean b_dupStrsOk)  {
      this(b_dupStrsOk, -1);

   }

   /**
      <P>Create an AOSLCreator.</P>

      <P>Equal to <CODE><A HREF="~JD~aoslc(b,i)~EJD~">AOSLCreator</A>(true, -1)</CODE></P>
    **/
   public AOSLCreator(int i_unqStrCount)  {
      this(true, i_unqStrCount);

   }

   /**
      <P>Create an AOSLCreator.</P>

      <P>Equal to <CODE><A HREF="~JD~aoslc(b,i,b)~EJD~">AOSLCreator</A>(b_dupStrsOk, i_unqStrCount, true)</CODE></P>
    **/
   public AOSLCreator(boolean b_dupStrsOk, int i_unqStrCount)  {
      this(b_dupStrsOk, i_unqStrCount, true);

   }

   /**
      <P>Create an AOSLCreator.</P>

      <P>Equal to <CODE><A HREF="~JD~aoslc(b,i,b)~EJD~">AOSLCreator</A>(b_dupStrsOk, -1, b_listStrsOnError)</CODE></P>
    **/
   public AOSLCreator(boolean b_dupStrsOk, boolean b_listStrsOnError)  {
      this(b_dupStrsOk, -1, b_listStrsOnError);

   }

   /**
      <P>Create an AOSLCreator.</P>

      <P>Equal to <CODE><A HREF="~JD~aoslc(b,i,b)~EJD~">AOSLCreator</A>(true, i_unqStrCount, b_listStrsOnError)</CODE></P>
    **/
   public AOSLCreator(int i_unqStrCount, boolean b_listStrsOnError)  {
      this(true, i_unqStrCount, b_listStrsOnError);

   }

   /**
      <P>Create an AOSLCreator.</P>

      @param  b_dupStrsOk  Are duplicate strings acceptable?  If true, then yes.  If false, no.  See <A HREF="#areDupStringsOk()">areDupStringsOk</A> and <A HREF="~JD~addString(s)~EJD~">addString</A>.
      @param  i_unqStrCount  How many unique strings will exist in the <A HREF="~JD~aosl~EJD~">AOSLookup</A> (will be added via addString)?  If -1, then the number of unique strings is not known.  Otherwise, may not be less than one.  See <A HREF="#getUnqStrCount()">getUnqStrCount</A> and addString.
      @param  b_listStrsOnError  Should the list of strings be printed in any error messages thrown?  If true, then yes.  If false, no.  See <A HREF="#doListStrsOnError()">doListStrsOnError</A>.
    **/
   public AOSLCreator(boolean b_dupStrsOk, int i_unqStrCount, boolean b_listStrsOnError)  {

      if(i_unqStrCount != -1  &&  i_unqStrCount < 1)  {
         throwAX("constructor:  i_unqStrCount (" + i_unqStrCount + ") must equal -1 (indicating the number of unique strings is unknown) or be greater than zero.");
      }


      if(i_unqStrCount > 0)  {

         ht = new Hashtable(i_unqStrCount, 1);

      }  else  {


         ht = new Hashtable();
      }


      bDupStringsOk = b_dupStrsOk;
      iUnqStrCount = i_unqStrCount;
      bListStrsOnError = b_listStrsOnError;

      acoUnique = new VWObject();
      acoAbsolute = new VWObject();
   }

   /**
      <P>Are duplicate strings okay?</P>

      @return  <B>b_dupStrsOk</B>  Exactly as provided to the <A HREF="~JD~aoslc(b,i,b)~EJD~">constructor</A>.
    **/
   public final boolean areDupStringsOk()  {
      return bDupStringsOk;
   }

   /**
      <P>Is it known how many unique strings <I>will</I> be provided?</P>

      @return  <B>i_unqStrCount</B>  Exactly as provided to the <A HREF="~JD~aoslc(b,i,b)~EJD~">constructor</A>.
    **/
   public final int getUnqStrCount()  {
      return iUnqStrCount;
   }

   /**
      <P>In the case of an error, should the list of strings be presented in the error message?</P>

      <P>This setting, when <A HREF="#getAOSLookup()">getAOSLookup</A> is called, is provided directly to the <A HREF="~JD~aosl~EJD~">AOSLookup</A> <A HREF="~JD~aosl#aosl(aoslh,usap,usap,b,b)~EJD~">constructor</A>.</P>

      @return  <B>b_listStrsOnError</B>  Exactly as provided to the <A HREF="~JD~aoslc(b,i,b)~EJD~">constructor</A>.
    **/
   public final boolean doListStrsOnError()  {
      return bListStrsOnError;
   }

   /**
      <P>Add a new string to the AOSLookup.</P>

      <P>It is expected strings are added in the same order in which they originally existed.  The first string exists at absolute array index zero, the second at array index one, and so on.</P>

      @param  s_tr  The string
      @exception  LockedException  If <A HREF="#isLocked()">isLocked</A> equals true.  This means all strings have been added.
      @exception  AssertException  If...<UL>
         <LI>...<A HREF="#areDupStringsOk()">areDupStringsOk</A> equals false, and s_tr is equal to a string that was previously added.</LI>
         <LI>...<A HREF="#getUnqStrCount()">getUnqStrCount</A> does not equal -1, and the [value of getUnqStrCount]-th unique string is (attempted to be) added.</LI>
      </UL>
    **/
   public final void addString(String s_tr)  {
      throwLXIfLocked(isLocked(), "addString");
      throwAXIfNull(s_tr, "s_tr", "addString");

      UniqueString us = null;

      if(ht.containsKey(s_tr))  {
         bLastStringUnique = false;

         if(!areDupStringsOk())  {
            throwAX("addString:  s_tr at array index " + acoAbsolute.size() + " ('" + s_tr + "') already exists at array index " + ((UniqueString)ht.get(s_tr)).getUnqArrIdx() + ".");
         }
         us = (UniqueString)ht.get(s_tr);
         us.incInstanceCount();

      }  else  {

         //The string does not exist in the Hashtable.  It is unique;
         if(getUnqStrCount() > -1  &&  ht.size() == getUnqStrCount())  {
            throwAX("addString:  s_tr equals '" + s_tr + "' and has not been added (it is unique).  However, getUnqStrCount() equals " + getUnqStrCount() + ", and this addString would result in " + (getUnqStrCount() + 1) + " unique strings.");
         }

         bLastStringUnique = true;
         int iNewUnqArrIdx = ht.size();
         us = (new UniqueString(s_tr, iNewUnqArrIdx));

         acoUnique.add(us);
         ht.put(s_tr, us);
      }

      acoAbsolute.add(us);
   }

   /**
      <P>Was the string-just-added unique?</P>

      @return  <B>true</B>  If the string just <A HREF="~JD~addString(s)~EJD~">added</A> is not equal to any string added before it (or is the first).
      <BR><B>false</B>  If the string just added was a duplicate.
      @exception  AssertException  If no strings have been added (<A HREF="#getCountUnq()">getCountUnq</A> equals zero).
    **/
   public final boolean wasLastStringUnique()  {
      if(getCountUnq() < 1)  {
         throwAX("wasLastStringUnique:  getCountUnq() equals zero.  You must call addString at least once before using this function.");
      }
      return bLastStringUnique;
   }

   /**
      <P>How many <I>unique</I> strings have been added?.  See <A HREF="~JD~addString(s)~EJD~">addString</A>.</P>
    **/
   public final int getCountUnq()  {
      return acoUnique.size();
   }

   /**
      <P>How many <I>total</I> strings have been added?.  See <A HREF="~JD~addString(s)~EJD~">addString</A>.</P>
    **/
   public final int getCountAbs()  {
      return acoAbsolute.size();
   }

   /**
      <P>Get the AOSLookup.</P>
    **/
   public final AOSLookup getAOSLookup()  {
      throwLXIfUnlocked(isLocked(), "getAOSLookup");
      return aosl;
   }

   //Required by LockOneWay...START
      public final void lock()  {

         throwLXIfLocked(isLocked(), "lock");

         if(ht.size() < 1)  {
            throwAX("lock:  Must call addString at least once.");
         }


         AOSLHashtable aoslh = null;
         UniqueStringAP usapAbsolute = null;
         UniqueStringAP usapUnique = null;

         if(getUnqStrCount() == -1)  {
            aoslh = new AOSLHashtable((new Utility()).getOptimizedHT(ht), bFALSE_IN_PRODUCTION);

         }  else if(getCountUnq() != getUnqStrCount())  {
            throwAX("getAOSLookup:  getCountUnq() (" + getCountUnq() + ") is less than the getUnqStrCount() (" + getUnqStrCount() + ")");
         }  else  {
            //The size was provided to us at construction,
            //so the Hashtable was optimized to begin with.
            aoslh = new AOSLHashtable(ht, bFALSE_IN_PRODUCTION);
         }
         ht = null;


         //Create the absolute-to-unique map.
            Object[] ao = acoAbsolute.getAOObject();
            UniqueString[] aUsmd = new UniqueString[ao.length];
            for(int i = 0; i < aUsmd.length; i++)  {

               aUsmd[i] = (UniqueString)ao[i];
            }

            usapAbsolute = (new UniqueStringAP(aUsmd));



         //Create the unique array.
            ao = acoUnique.getAOObject();
            aUsmd = new UniqueString[ao.length];
            for(int i = 0; i < aUsmd.length; i++)  {

               aUsmd[i] = (UniqueString)ao[i];
            }

            usapUnique = (new UniqueStringAP(aUsmd));

         aosl = new AOSLookup(aoslh, usapUnique, usapAbsolute, bFALSE_IN_PRODUCTION, doListStrsOnError());



         bLocked = true;
      }

      public final boolean isLocked()  {

         return bLocked;
      }
   //Required by LockOneWay...END
}