/*
   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.output;

/**
   <P>The base class for an OWriter that can wrap around objects like java.io.OutputStreams and java.io.Writer.  See <A HREF="~JD~os~EJD~">OutputStream</A> and <A HREF="~JD~w~EJD~">Writer</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/output/OWWrapper.java">OWWrapper.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 abstract class OWWrapper extends OWriter  {

   private boolean bSuppressFinalizeIOX = false;
   private boolean bFlushCloseInFinalize = false;
   private boolean bAutoFlush = false;

   /**
      <P>Create a OWWrapper with default settings.</P>

      <P>Equal to <CODE><A HREF="~JD~oww(b,b,b)~EJD~">OWWrapper</A>(false, false, false)</CODE></P>
    **/
   public OWWrapper()  {
      this(false, false, false);
   }

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

      <P>Equal to <CODE><A HREF="~JD~oww(b,b)~EJD~">OWWrapper</A>(b_autoFlush, true)</CODE></P>
    **/
   public OWWrapper(boolean b_autoFlush)  {
      this(b_autoFlush, true);
   }

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

      <P>Equal to <CODE><A HREF="~JD~oww(b,b,b)~EJD~">OWWrapper</A>(b_autoFlush, true, b_suppressFinalizeIOX)</CODE></P>
    **/
   public OWWrapper(boolean b_autoFlush, boolean b_suppressFinalizeIOX)  {
      this(b_autoFlush, true, b_suppressFinalizeIOX);
   }

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

      @param  b_autoFlush  Should the stream be flushed after every output?  Passed directly to <A HREF="#setAutoFlush(boolean)">setAutoFlush</A>.
      @param  b_closeInFinalize  Should the [writer/stream] be closed in <A HREF="#finalize()">finalize</A>?  Passed directly to <A HREF="#setFlushCloseInFinalize(boolean)">setFlushCloseInFinalize</A>.
      @param  b_suppressFinalizeIOX  Should IOExceptions in finalize be suppressed?  Passed directly to <A HREF="#setSuppressFinalizeIOX(boolean)">setSuppressFinalizeIOX</A>.
    **/
   public OWWrapper(boolean b_autoFlush, boolean b_closeInFinalize, boolean b_suppressFinalizeIOX)  {
      setAutoFlush(b_autoFlush);
      setFlushCloseInFinalize(b_closeInFinalize);
      setSuppressFinalizeIOX(b_suppressFinalizeIOX);
   }

   /**
      <P>When this class is finalized, should the [writer/stream] be flushed and closed?.  See <A HREF="#doFlushCloseInFinalize()">doFlushCloseInFinalize</A>.</P>

      @param  b_closeInFinalize  If true, the [writer/stream] will be closed during <A HREF="#finalize()">finalize</A>.  If false,  If it will not be closed.
    **/
   public final void setFlushCloseInFinalize(boolean b_closeInFinalize)  {
      bFlushCloseInFinalize = b_closeInFinalize;
   }

   /**
      <P>Should the [writer/stream] be flushed and closed in finalize?.  See <A HREF="#setFlushCloseInFinalize(boolean)">setFlushCloseInFinalize</A>.</P>

      <P>Note that this setting does not affect flushing.  No matter what, the stream is flushed, before (potentially) being closed.</P>

      @return  <B>true</B>  If the [writer/stream] will be closed during <A HREF="#finalize()">finalize</A>.
      <BR><B>false</B>  If it will not be closed.
    **/
   public boolean doFlushCloseInFinalize()  {
      return bFlushCloseInFinalize;
   }


   /**
      <P>Define if flush should be called at the end of every write function.</P>

      <P><I>Get with <CODE><A HREF="~JD~oww~EJD~#doSuppressFinalizeIOX()">doSuppressFinalizeIOX</A></CODE></I></P>

      @param b_suppressFinalizeIOX  If true, do suppress any IOException that should occur in finalize.  If false, don't.
    **/
   public final void setAutoFlush(boolean b_autoFlush)  {
      bAutoFlush = b_autoFlush;
   }

   /**
      <P>Define if an IOException should be suppressed, should one occur in finalize.</P>

      <P><I>Get with <CODE><A HREF="~JD~oww~EJD~#doSuppressFinalizeIOX()">doSuppressFinalizeIOX</A></CODE></I></P>

      @param b_suppressFinalizeIOX  If true, do suppress <A HREF="~JD~iox~EJD~">IOExceptions</A> that occur in finalize.  If false, don't.
    **/
   public final void setSuppressFinalizeIOX(boolean b_suppressFinalizeIOX)  {
      bSuppressFinalizeIOX = b_suppressFinalizeIOX;
   }


   /**
      <P>Should the [writer/stream] be automatically flushed, after each output?</P>

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

      <P>Regardless of this setting, flush is always called in <A HREF="#finalize()">finalize</A>.</P>

      @return  <B>b_autoFlush</B> exactly as provided to setAutoFlush.  If...<UL>
         <LI>...<B>true:</B>  Call [writer/stream].<A HREF="~JD~os~EJD~#flush()">flush</A> at the end of every call to <A HREF="~JD~write(s)~EJD~">write</A>, <A HREF="~JD~writeNoln(s)~EJD~">writeNoln</A> and <A HREF="#newln()">newln</A>.</LI>
         <LI>...<B>false:</B>  The only way flush is called is to do so <A HREF="#flush()">manually</A>.</LI>
      </UL>
    **/
   public boolean doAutoFlush()  {
      return bAutoFlush;
   }

   /**
      <P>If an IOException should occur in finalize, should it be suppressed?</P>

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

      @return  <B>b_suppressFinalizeIOX</B> exactly as provided to setSuppressFinalizeIOX.  If...<UL>
         <LI>...<B>true:</B>  If an <A HREF="~JD~iox~EJD~">IOException</A> occurs in the middle of <A HREF="#finalize()">finalize</A>, it is suppressed.  In other words, you'll never know the error occurred.</LI>
         <LI>...<B>false:</B>  If an IOException occurs in the middle of finalize, throw an <A HREF="~JD~ax~EJD~">AssertException</A>, <I>saying</I> that an IOException was thrown.</LI>
      </UL>
    **/
   public boolean doSuppressFinalizeIOX()  {
      return bSuppressFinalizeIOX;
   }

   /**
      <P>Write a line of output to the [writer/stream] via println(java.lang.String).</P>

      <P>After output is written, if <A HREF="~JD~oww~EJD~#doAutoFlush()">doAutoFlush</A> equals true, call <A HREF="#flush()">flush</A>.</P>

      @param  s_message  The message to output.
      @exception  AssertException  If an <A HREF="~JD~iox~EJD~">IOException</A> is thrown for any reason.
    **/
   public abstract void write(String s_message);

   /**
      <P>Write a line of output to the [writer/stream] via print(java.lang.String).</P>

      <P>After output is written, if <A HREF="~JD~oww~EJD~#doAutoFlush()">doAutoFlush</A> equals true, call <A HREF="#flush()">flush</A>.</P>

      @param  s_message  The message to output.
      @exception  AssertException  If an <A HREF="~JD~iox~EJD~">IOException</A> is thrown for any reason.
    **/
   public abstract void writeNoln(String s_message);

   /**
      <P>Write a newline only, to the [writer/stream] via println().</P>

      <P>After output is written, if <A HREF="~JD~oww~EJD~#doAutoFlush()">doAutoFlush</A> equals true, call <A HREF="#flush()">flush</A>.</P>

      @param  s_message  The message to output.
      @exception  AssertException  If an <A HREF="~JD~iox~EJD~">IOException</A> is thrown for any reason.
    **/
   public abstract void newln();

   /**
      <P>Manually flush the [writer/stream] by calling flush().</P>
    **/
   public abstract void flush();

   /**
      <P>Flush, close and then null the [writer/stream].</P>

      <P>flush and close (only if <A HREF="~JD~oww~EJD~#doFlushCloseInFinalize()">doFlushCloseInFinalize</A> equals true).</P>

      <P><I>Note:  The OWWrapper version of this function must be overridden by you--in order to actually flush and close the [writer/stream], and you must call this function (via super.finalize()) in your implementation.</I></P>

      @exception  AssertException  If <A HREF="~JD~oww~EJD~#doSuppressFinalizeIOX()">doSuppressFinalizeIOX</A> is true <I>and</I> an <A HREF="~JD~iox~EJD~">IOException</A> is thrown for any reason.  Note that java.lang.<A HREF="~JD~o~EJD~">Object</A>.<A HREF="~JD~o~EJD~#finalize()">finalize</A> is definitely called, even in the event of an IOException.
    **/
   protected void finalize() throws Throwable  {
      super.finalize();
   }
}