/*
   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;
   import xbn.XBNObject;

/**
   <P>Optionally output text to a variety of destinations, with configuration.</P>

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

   <P>Use this in in any class that implements <A HREF="Debuggable.html">Debuggable</A>.  This Outputter class contains a single <A HREF="OWriter.html">OWriter</A>, and a single <A HREF="OConfig.html">OConfig</A>.</P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class Outputter extends XBNObject  {

   private OWriter oWriter = null;
   private OConfig oConfig = null;

   /**
      <P>Create an Outputter that does nothing.</P>

      <P><I>Equal to <CODE><A HREF="~JD~optr(ow,oc)~EJD~">Outputter</A>((new <A HREF="~JD~owe#owe()~EJD~">OWEmpty</A>()), (new <A HREF="~JD~oc#oc()~EJD~">OConfig</A>()))</CODE></I></P>
    **/
   public Outputter()  {
      this((new OWEmpty()), (new OConfig()));
   }

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

      <P><I>Equal to <CODE><A HREF="~JD~optr(ow,oc)~EJD~">Outputter</A>(o_writer, (new <A HREF="~JD~oc#oc(b)~EJD~">OConfig</A>(true)))</CODE></I></P>
    **/
   public Outputter(OWriter o_writer)  {
      this(o_writer, (new OConfig(true)));
   }

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

      @param  o_writer  Declares the output destination.  May not be null.  See <A HREF="~JD~setOWriter(ow)~EJD~">setOWriter</A> and <A HREF="#getOWriter()">getOWriter</A>.
      @param  o_config  The configuration for this Outputter object.  May not be null.  See <A HREF="~JD~setOConfig(oc)~EJD~">setOConfig</A> and <A HREF="#getOConfig()">getOConfig</A>.
    **/
   public Outputter(OWriter o_writer, OConfig o_config)  {
      setOWriter(o_writer);
      setOConfig(o_config);
   }


   /**
      <P>Get the OWriter object for direct manipulation.</P>

      <P><I>Set with <CODE><A HREF="~JD~setOWriter(ow)~EJD~">setOWriter</A></CODE></I>.</P>
    **/
   public final OWriter getOWriter()  {
      return oWriter;
   }

   /**
      <P>Get the OConfig object for direct manipulation.</P>

      <P><I>Set with <CODE><A HREF="~JD~setOConfig(oc)~EJD~">setOConfig</A></CODE></I>.</P>
    **/
   public final OConfig getOConfig()  {
      return oConfig;
   }

   /**
      <P>Define the destination for output.</P>

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

      @param  o_writer  Object declaring the output destination.  May not be null.
    **/
   public final void setOWriter(OWriter o_writer)  {
      if(o_writer == null)  {
         throwAX("setOWriter:  o_writer is null.");
      }

      oWriter = o_writer;
   }

   /**
      <P>Define the configuration for this Outputter.</P>

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

      @param  o_config  The configuration for this Outputter object.  May not be null.
    **/
   public final void setOConfig(OConfig o_config)  {
      throwAXIfNull(o_config, "o_config", "setOConfig");
      oConfig = o_config;
   }

   /**
      <P>Is this Outputter actually writing it's output?</P>

      <P>Note that this setting is ignored when the <A HREF="#getOWriter()">OWriter</A> is not <A HREF="~JD~ow~EJD~#isActive()">active</A>.</P>

      @return  <CODE><A HREF="#getOConfig()">getOConfig</A>().<A HREF="~JD~oc~EJD~#isOn()">isOn</A>()</CODE>
    **/
   public final boolean isOn()  {
      return getOConfig().isOn();
   }


   /**
      <P>Write a line of output.</P>

      <P>Equal to <CODE><A HREF="~JD~actuallyWriteLine(s,b,b)~EJD~">actuallyWriteLine</A>(s_message, true, true)</CODE></P>
    **/
   public final void write(String s_message)  {
      actuallyWriteLine(s_message, true, true);
   }


   /**
      <P>Write a line of output to the destination.</P>

      <P>Equal to <CODE><A HREF="~JD~actuallyWriteLine(s,b,b)~EJD~">actuallyWriteLine</A>(s_message, false, false)</CODE></P>
    **/
   public final void writeNoln(String s_message)  {
      actuallyWriteLine(s_message, false, false);
   }

   /**
      <P>Write a newline to the destination.</P>

      <P>Equal to <CODE><A HREF="~JD~actuallyWriteLine(s,b,b)~EJD~">actuallyWriteLine</A>(null, false, true)</CODE></P>
    **/
   public final void newln()  {
      actuallyWriteLine(null, false, true);
   }

   /**
      <P>Write a line of output to the destination.</P>

      <P>Equal to <CODE><A HREF="~JD~actuallyWriteLine(s,b,b)~EJD~">actuallyWriteLine</A>(s_message, b_useIndent, true)</CODE></P>
    **/
   public final void write(boolean b_useIndent, String s_message)  {
      actuallyWriteLine(s_message, b_useIndent, true);
   }

   /**
      <P>Write a line of output to the destination.</P>

      <P>Equal to <CODE><A HREF="~JD~actuallyWriteLine(s,b,b)~EJD~">actuallyWriteLine</A>(s_message, b_useIndent, false)</CODE></P>
    **/
   public final void writeNoln(boolean b_useIndent, String s_message)  {
      actuallyWriteLine(s_message, b_useIndent, false);
   }



   /**
      <P>Write a line of output to the destination.</P>

      <H4>What is done in this function?</H4>

      <P>In order:<OL>
         <LI>If either <CODE><A HREF="#getOWriter()">getOWriter</A>.<A HREF="~JD~ow~EJD~#isActive()">isActive</A>()</CODE> or <CODE><A HREF="#getOConfig()">getOConfig</A>().<A HREF="~JD~oc~EJD~#isOn()">isOn</A>()</CODE> equal false, do nothing.  DONE.</LI>
         <LI>If s_message is null and b_newLine is true, then call <CODE><A HREF="#getOWriter()">getOWriter</A>().<A HREF="~JD~ow~EJD~#newln()">newln</A>()</CODE>.  DONE.</LI>
         <LI>Format the message (using <CODE>getOConfig().<A HREF="~JD~oc#getFormatted(b,s)~EJD~">getFormatted</A>(b_useIndent, s_message)</CODE>), and then output it via getOWriter().<A HREF="~JD~ow#write(s)~EJD~">write</A> or getOWriter().<A HREF="~JD~ow#writeNoln(s)~EJD~">writeNoln</A>.</LI>
      </OL></P>

      @param  s_message  The message to output.
      @param  b_useIndent  Should this line of output be preceded by an <A HREF="~JD~mf~EJD~#getIndent()">indentation</A>?  If true, yes, indent.  If false, no indent.
      @param  b_newLine  If true, output using OWriter.write.  If false, use OWriter.writeNoln.
    **/
   public void actuallyWriteLine(String s_message, boolean b_useIndent, boolean b_newLine)  {
      if(!getOWriter().isActive()  ||  !getOConfig().isOn())  {
         return;
      }

      if(s_message == null  &&  b_newLine)  {
         getOWriter().newln();
         return;
      }

      String sMessage = getOConfig().getFormatted(b_useIndent, s_message);

      if(b_newLine)  {
         getOWriter().write(sMessage);

      }  else  {
         getOWriter().writeNoln(sMessage);
      }
   }

   /**
      <P>Get some information about this Ouptutter.</P>
    **/
   public final String toString()  {
      return this.getClass().getName() + ":  [" + getOWriter().toString() + "], [" + getOConfig().toString() + "]";
   }
}