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

/**
   <P>Classes implementing LockOneWay indicate their values may be locked.</P>

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

   <P>After the value is locked, it may not be altered again.  A value may be locked at any time, but may not be unlocked.</P>

   <P>If you allow lcking to occur in the constructor of your LockOneWay object, remember to set any values *before* locking.  Also, consider nullifying any obects no longer needed, such as "rule" objects used to validate potential sets.  Since sets are no longer allowed once locked, there's no need for the rule objects anymore.  Possible exception is if the rule object would be needed for cloning, unless the cloned object would also be locked.</P>


<P><CODE>&nbsp; &nbsp;//REQUIRED BY xbn.util.LockOneWay...START
<BR>&nbsp; &nbsp;&nbsp; &nbsp;public void lock()&nbsp; {
<BR>&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;bLocked = true;
<BR>&nbsp; &nbsp;&nbsp; &nbsp;}
<BR>&nbsp; &nbsp;&nbsp; &nbsp;public boolean isLocked()&nbsp; {
<BR>&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;return bLocked;
<BR>&nbsp; &nbsp;&nbsp; &nbsp;}
<BR>&nbsp; &nbsp;//REQUIRED BY xbn.util.LockOneWay...END</CODE></P>

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

   /**
      <P>Lock the value, forbidding further sets.  There is no way to unlock the value, so consider this function a "one way ticket".</P>

      <P>It is recommended to crash if the value is already locked (<A HREF="#isLocked()">isLocked</A> is true).  You must crash in your class' "set" functions when isLocked is true.</P>

      @exception  AssertException  If isLocked is true.
    **/
   void lock();


   /**
      <P>Is the value locked?</P>

      @return  <B>true</B>  If <A HREF="#lock()">lock</A> has been called at some moment before now.  This indicates that the value is locked and may no longer be altered.
      <BR><B>false</B>  If lock has not yet been called.  This indicates that the value may still be altered.
    **/
   boolean isLocked();
}