}

  /**
   * Adds an annotation to this variable.
   *
   * @param aClazz
   *        The annotation class to annotate the field with
   */
  @Nonnull
  public JAnnotationUse annotate (@Nonnull final AbstractJClass aClazz)
  {
    if (m_aAnnotations == null)
      m_aAnnotations = new ArrayList <> ();
    final JAnnotationUse a = new JAnnotationUse (aClazz);
    m_aAnnotations.add (a);
    return a;
  }

  /**
   * Adds an annotation to this variable.
   *
   * @param aClazz
   *        The annotation class to annotate the field with
   */
  @Nonnull
  public JAnnotationUse annotate (@Nonnull final Class <? extends Annotation> aClazz)
  {
    return annotate (m_aType.owner ().ref (aClazz));
  }

  /**
   * {@link IJAnnotatable#annotations()}
   */
  @Nonnull
  public Collection <JAnnotationUse> annotations ()
  {
    if (m_aAnnotations == null)
      m_aAnnotations = new ArrayList <> ();
    return Collections.unmodifiableList (m_aAnnotations);
  }

                                               @Nonnull final BigDecimal aUpperBoundInclusive)
  {
    notNull (aValue, aName);
    notNull (aLowerBoundInclusive, "LowerBoundInclusive");
    notNull (aUpperBoundInclusive, "UpperBoundInclusive");
    if (isEnabled ())
      if (aValue.compareTo (aLowerBoundInclusive) < 0 || aValue.compareTo (aUpperBoundInclusive) > 0)
        throw new IllegalArgumentException ("The value of '" +
                                            aName.get () +
                                            "' must be >= " +
                                            aLowerBoundInclusive +
                                            " and <= " +
                                            aUpperBoundInclusive +
                                            "! The current value is: " +
                                            aValue);
    return aValue;
  }

  /**
   * Check if
   * <code>nValue &ge; nLowerBoundInclusive &amp;&amp; nValue &le; nUpperBoundInclusive</code>
   *
   * @param aValue
   *        Value
   * @param sName
   *        Name
   * @param aLowerBoundInclusive
   *        Lower bound
   * @param aUpperBoundInclusive
   *        Upper bound
   * @return The value
   */
  public static BigInteger isBetweenInclusive (final BigInteger aValue,

                                               @Nonnull final BigDecimal aUpperBoundExclusive)
  {
    notNull (aValue, aName);
    notNull (aLowerBoundExclusive, "LowerBoundInclusive");
    notNull (aUpperBoundExclusive, "UpperBoundInclusive");
    if (isEnabled ())
      if (aValue.compareTo (aLowerBoundExclusive) <= 0 || aValue.compareTo (aUpperBoundExclusive) >= 0)
        throw new IllegalArgumentException ("The value of '" +
                                            aName.get () +
                                            "' must be > " +
                                            aLowerBoundExclusive +
                                            " and < " +
                                            aUpperBoundExclusive +
                                            "! The current value is: " +
                                            aValue);
    return aValue;
  }

  public static <T> T [] notEmpty (final T [] aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    if (isEnabled ())
      if (aValue.length == 0)
        throw new IllegalArgumentException ("The value of the array '" + aName.get () + "' may not be empty!");
    return aValue;
  }

  /**
   * Check that the passed Array is neither <code>null</code> nor empty.
   *
   * @param aValue
   *        The Array to check.
   * @param sName
   *        The name of the value (e.g. the parameter name)
   * @return The passed value.
   * @throws IllegalArgumentException
   *         if the passed value is empty
   */
  public static boolean [] notEmpty (final boolean [] aValue, final String sName)

    if (m_aAnnotations == null)
      m_aAnnotations = new ArrayList <> ();
    final JAnnotationUse a = new JAnnotationUse (aClazz);
    m_aAnnotations.add (a);
    return a;
  }

  /**
   * Adds an annotation to this variable.
   *
   * @param aClazz
   *        The annotation class to annotate the field with
   */
  @Nonnull
  public JAnnotationUse annotate (@Nonnull final Class <? extends Annotation> aClazz)
  {
    return annotate (m_aType.owner ().ref (aClazz));

    return Collections.emptyIterator ();
  }

  @Override
  public boolean isInterface ()
  {
    return false;
  }

  @Override
  public boolean isAbstract ()
  {
    return false;
  }

  @Override
  @Nonnull
  protected AbstractJClass substituteParams (@Nonnull final JTypeVar [] aVariables,
                                             @Nonnull final List <? extends AbstractJClass> aBindings)
  {

                              final int nExpectedValue,
                              @Nonnull final Supplier <? extends String> aName)
  {
    if (isEnabled ())
      if (nValue != nExpectedValue)
        throw new IllegalArgumentException ("The value of '" +
                                            aName.get () +
                                            "' does not match the expected value. Passed value: " +
                                            nValue +
                                            " -- Expected value: " +
                                            nExpectedValue);
  }

  /**
   * Check that the passed value is the same as the provided expected value
   * using <code>==</code> to check comparison.
   *
   * @param nValue
   *        The First value.
   * @param nExpectedValue
   *        The expected value.
   * @param sName
   *        The name of the value (e.g. the parameter name)
   * @throws IllegalArgumentException
   *         if the passed value is not <code>null</code>.
   */
  public static void isEqual (final long nValue, final long nExpectedValue, final String sName)

    final JEnumConstant rhs = (JEnumConstant) o;
    return isEqual (m_aType.fullName (), rhs.m_aType.fullName ()) && isEqual (m_sName, rhs.m_sName);
  }

  @Override
  public int hashCode ()
  {
    return getHashCode (this, m_aType.fullName (), m_sName);
  }
}

  {
    private static final BitSet ESCAPE = new BitSet (128);

    static
    {
      for (int i = 0; i < 0x20; i++)
        if (i != '\t' && i != '\r' && i != '\n')
          ESCAPE.set (i, true);
    }

  }

  @Nonnull
  public JAnnotationUse annotate (@Nonnull final AbstractJClass aClazz)
  {
    if (m_aAnnotations == null)
      m_aAnnotations = new ArrayList <> ();
    final JAnnotationUse a = new JAnnotationUse (aClazz);
    m_aAnnotations.add (a);
    return a;
  }

  @Nonnull
  public Collection <JAnnotationUse> annotations ()

                                        final int nUpperBoundExclusive)
  {
    if (isEnabled ())
      if (nValue <= nLowerBoundExclusive || nValue >= nUpperBoundExclusive)
        throw new IllegalArgumentException ("The value of '" +
                                            aName.get () +
                                            "' must be > " +
                                            nLowerBoundExclusive +
                                            " and < " +
                                            nUpperBoundExclusive +
                                            "! The current value is: " +
                                            nValue);
    return nValue;
  }

  /**
   * Check if
   * <code>nValue &gt; nLowerBoundInclusive &amp;&amp; nValue &lt; nUpperBoundInclusive</code>
   *
   * @param nValue
   *        Value
   * @param sName
   *        Name
   * @param nLowerBoundExclusive
   *        Lower bound
   * @param nUpperBoundExclusive
   *        Upper bound
   * @return The value
   */
  public static long isBetweenExclusive (final long nValue,

    return this;
  }

  /**
   * Adds a new annotation to the array.
   */
  @Nonnull
  public JAnnotationUse annotate (@Nonnull final Class <? extends Annotation> aClazz)
  {
    return annotate (owner ().ref (aClazz));
  }

  /**
   * Adds a new annotation to the array.
   */
  @Nonnull
  public JAnnotationUse annotate (@Nonnull final AbstractJClass aClazz)
  {

                          aClassToBeWritten.fullName () +
                          ")");

    AbstractJClass aRealReference = aReference;
    if (aRealReference instanceof JAnonymousClass)
    {
      // get the super class of the anonymous class
      aRealReference = ((JAnonymousClass) aRealReference).base ();
    }
    if (aRealReference instanceof JNarrowedClass)
    {
      // Remove the generic arguments
      aRealReference = aRealReference.erasure ();
    }

    // Is it an inner class?
    final AbstractJClass aOuter = aRealReference.outer ();

  public static int isGT0 (final int nValue, @Nonnull final Supplier <? extends String> aName)
  {
    if (isEnabled ())
      if (nValue <= 0)
        throw new IllegalArgumentException ("The value of '" +
                                            aName.get () +
                                            "' must be > 0! The current value is: " +
                                            nValue);
    return nValue;
  }

  public static long isGT0 (final long nValue, final String sName)

  public static int isLT0 (final int nValue, @Nonnull final Supplier <? extends String> aName)
  {
    if (isEnabled ())
      if (nValue >= 0)
        throw new IllegalArgumentException ("The value of '" +
                                            aName.get () +
                                            "' must be < 0! The current value is: " +
                                            nValue);
    return nValue;
  }

  public static long isLT0 (final long nValue, final String sName)

  public static <T extends Collection <?>> T notEmpty (final T aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    if (isEnabled ())
      if (aValue.isEmpty ())
        throw new IllegalArgumentException ("The value of the collection '" + aName.get () + "' may not be empty!");

    f.print ("((").generable (m_aType).print (')').generable (m_aObject).print (')');
  }

  @Override
  public boolean equals (final Object o)
  {
    if (o == this)
      return true;
    if (o == null || getClass () != o.getClass ())
      return false;
    final JCast rhs = (JCast) o;

  public JBreak (@Nullable final JLabel aLabel)
  {
    m_aLabel = aLabel;
  }

  @Nullable
  public JLabel label ()
  {
    return m_aLabel;
  }

  public void state (@Nonnull final JFormatter f)
  {
    if (m_aLabel == null)
      f.print ("break;").newline ();

  }

  //
  // Equality is based on value
  //

  @Override
  public boolean equals (final Object obj)
  {
    if (obj == this)
      return true;
    if (obj == null || !getClass ().equals (obj.getClass ()))
      return false;

    final JArrayClass rhs = (JArrayClass) obj;

          f.print (Double.toString (m_dWhat));
  }

  @Override
  public boolean equals (final Object o)
  {
    if (o == this)
      return true;
    if (o == null || getClass () != o.getClass ())
      return false;
    final JAtomDouble rhs = (JAtomDouble) o;

  }

  @Nonnull
  public JBlock body ()
  {
    if (m_aBody == null)
      m_aBody = new JBlock ();
    return m_aBody;
  }

  public void state (@Nonnull final JFormatter f)
  {
    f.print ("for (");

  public static <T extends Iterable <?>> T notNullNoNullValue (final T aValue,
                                                               @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    noNullValue (aValue, aName);
    return aValue;
  }

  /**
   * Check that the passed map is not <code>null</code> and that no
   * <code>null</code> value is contained.
   *
   * @param <T>
   *        Type to be checked and returned
   * @param aValue
   *        The map to check.
   * @param sName
   *        The name of the value (e.g. the parameter name)
   * @return The passed value.
   * @throws IllegalArgumentException
   *         if the passed value is <code>null</code> or a <code>null</code>
   *         value is contained
   */
  public static <T extends Map <?, ?>> T notNullNoNullValue (final T aValue, final String sName)

  public static <T extends Iterable <?>> T notEmptyNoNullValue (final T aValue,
                                                                @Nonnull final Supplier <? extends String> aName)
  {
    notEmpty (aValue, aName);
    noNullValue (aValue, aName);
    return aValue;
  }

  /**
   * Check that the passed map is neither <code>null</code> nor empty and that
   * no <code>null</code> value is contained.
   *
   * @param <T>
   *        Type to be checked and returned
   * @param aValue
   *        The map to check.
   * @param sName
   *        The name of the value (e.g. the parameter name)
   * @return The passed value.
   * @throws IllegalArgumentException
   *         if the passed value is empty or a <code>null</code> value is
   *         contained
   */
  public static <T extends Map <?, ?>> T notEmptyNoNullValue (final T aValue, final String sName)

    return annotate (m_aType.owner ().ref (aClazz));
  }

  /**
   * {@link IJAnnotatable#annotations()}
   */
  @Nonnull
  public Collection <JAnnotationUse> annotations ()
  {
    if (m_aAnnotations == null)
      m_aAnnotations = new ArrayList <> ();
    return Collections.unmodifiableList (m_aAnnotations);
  }

    for (final Element enclosedElement : element.getEnclosedElements ())
    {
      if (enclosedElement.getKind ().equals (ElementKind.INTERFACE) ||
          enclosedElement.getKind ().equals (ElementKind.CLASS))

  public static void isArrayOfsLen (final Object [] aArray, @Nonnegative final int nOfs, @Nonnegative final int nLen)
  {
    notNull (aArray, "Array");
    _isArrayOfsLen (aArray.length, nOfs, nLen);
  }

  public static void isArrayOfsLen (final boolean [] aArray, @Nonnegative final int nOfs, @Nonnegative final int nLen)

  public void declare (@Nonnull final JFormatter f)
  {
    if (m_aTypeVariables != null && !m_aTypeVariables.isEmpty ())
    {
      f.print ('<');
      int nIndex = 0;
      for (final JTypeVar aTypeVar : m_aTypeVariables.values ())

  }

  @Override
  public boolean equals (final Object o)
  {
    if (o == this)
      return true;
    if (o == null || getClass () != o.getClass ())
      return false;
    final JArray rhs = (JArray) o;

  }

  @Nonnull
  public JBlock body ()
  {
    if (m_aBody == null)
      m_aBody = new JBlock ();
    return m_aBody;
  }

  public void state (@Nonnull final JFormatter f)
  {
    f.print ("do");

                              @Nullable final T aExpectedValue)
  {
    if (isEnabled ())
      if (aValue != aExpectedValue)
        throw new IllegalArgumentException ("The value of '" +
                                            aName.get () +
                                            "' does not match the expected value. Passed value: " +
                                            aValue +
                                            " -- Expected value: " +
                                            aExpectedValue);
    return aValue;
  }

  /**
   * Check that the passed value is the same as the provided expected value
   * using <code>equals</code> to check comparison.
   *
   * @param <T>
   *        Type to be checked and returned
   * @param aValue
   *        The value to check.
   * @param sName
   *        The name of the value (e.g. the parameter name)
   * @param aExpectedValue
   *        The expected value. May be <code>null</code>.
   * @return The passed value and maybe <code>null</code> if the expected value
   *         is null.
   * @throws IllegalArgumentException
   *         if the passed value is not <code>null</code>.
   */
  public static <T> T isEqual (final T aValue, @Nullable final T aExpectedValue, final String sName)

  public static BigDecimal isGE0 (final BigDecimal aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    if (isEnabled ())
      if (aValue.compareTo (BigDecimal.ZERO) < 0)

  public static BigInteger isGE0 (final BigInteger aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    if (isEnabled ())
      if (aValue.compareTo (BigInteger.ZERO) < 0)

  }

  @Nonnull
  public JBlock body ()
  {
    if (m_aBody == null)
      m_aBody = new JBlock ();
    return m_aBody;
  }

  public void state (@Nonnull final JFormatter f)
  {
    f.indent ();

                                m_aAnnotationUse.param (name, _actualEnumConstantValue ((VariableElement) value));
                              }
                              catch (final ClassNotFoundException ex)
                              {
                                Logger.getLogger (Annotator.class.getName ())
                                      .log (Level.WARNING,
                                            "Not processing annotation argument: {0}: {1}",
                                            new Object [] { name, value });

      environment.put (typeVariable.name (), typeVariable);
      for (final TypeMirror type : parameter.getBounds ())
      {
        typeVariable.bound ((AbstractJClass) m_aModelsAdapter.toJType (type, environment));

  public static <T extends Collection <?>> T notEmpty (final T aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    if (isEnabled ())
      if (aValue.isEmpty ())

  public String fullName ()
  {
    if (getOuter () instanceof AbstractJClassContainer <?>)
      return ((AbstractJClassContainer <?>) getOuter ()).fullName () + '.' + name ();

      return componentType.array ();
    }
    catch (final CodeModelBuildingException ex)
    {
      throw new RuntimeCodeModelBuildingException (ex);
    }
    catch (final ErrorTypeFound ex)
    {
      throw new RuntimeErrorTypeFound (ex);
    }
  }

  @Override
  public AbstractJType visitDeclared (final DeclaredType t, final Void p)

  }

  /**
   * Adds a new annotation to the array.
   */
  @Nonnull
  public JAnnotationUse annotate (@Nonnull final Class <? extends Annotation> aClazz)
  {
    return annotate (owner ().ref (aClazz));
  }

  /**
   * Adds a new annotation to the array.
   */
  @Nonnull
  public JAnnotationUse annotate (@Nonnull final AbstractJClass aClazz)

  }

  @Nonnull
  public JBlock body ()
  {
    if (m_aBody == null)
      m_aBody = new JBlock ();
    return m_aBody;
  }

  public void state (@Nonnull final JFormatter f)
  {

    if (m_aAnnotations == null)
      m_aAnnotations = new ArrayList <> ();
    final JAnnotationUse a = new JAnnotationUse (aClazz);
    m_aAnnotations.add (a);
    return a;
  }

  @Nonnull
  public Collection <JAnnotationUse> annotations ()

  public static <T extends Iterable <?>> T noNullValue (final T aValue,
                                                        @Nonnull final Supplier <? extends String> aName)
  {
    if (isEnabled ())
      if (aValue != null)
      {

  public JAnnotationUse paramArray (@Nonnull final String sName, @Nonnull final Enum <?>... aValues)
  {
    paramArray (sName).params (aValues);
    return this;
  }

  /**
   * Adds a member value pair to this annotation
   *
   * @param sName
   *        The simple name for this annotation
   * @param aValue
   *        The {@link JEnumConstant} which is member value for this annotation
   * @return The {@link JAnnotationUse}. More member value pairs can be added to
   *         it using the same or the overloaded methods.
   */
  @Nonnull
  public JAnnotationUse param (@Nonnull final String sName, @Nonnull final JEnumConstant aValue)

  public JDefinedClass getClass (final TypeElement element) throws CodeModelBuildingException, ErrorTypeFound
  {
    final Element enclosingElement = element.getEnclosingElement ();
    if (enclosingElement instanceof PackageElement)
    {
      final PackageElement packageElement = (PackageElement) enclosingElement;

  public static void isArrayOfsLen (final Object [] aArray, @Nonnegative final int nOfs, @Nonnegative final int nLen)
  {
    notNull (aArray, "Array");
    _isArrayOfsLen (aArray.length, nOfs, nLen);
  }

    throw new JErrorClassUsedException (m_sMessage);
  }

  @Override
  public boolean isInterface ()
  {
    return false;
  }

  @Override
  public boolean isAbstract ()
  {
    return false;
  }

  @Override
  public boolean isError ()
  {
    return true;

  }

  @Override
  @Nonnull
  protected AbstractJClass substituteParams (@Nonnull final JTypeVar [] aVariables,
                                             @Nonnull final List <? extends AbstractJClass> aBindings)
  {
    return this;
  }
}

  public static <T extends Iterable <?>> T noNullValue (final T aValue, final String sName)
  {
    return noNullValue (aValue, () -> sName);
  }

  /**
   * Check that the passed iterable contains no <code>null</code> value. But the
   * whole iterable can be <code>null</code> or empty.
   *
   * @param <T>
   *        Type to be checked and returned
   * @param aValue
   *        The collection to check. May be <code>null</code>.
   * @param aName
   *        The name of the value (e.g. the parameter name)
   * @return The passed value. Maybe <code>null</code>.
   * @throws IllegalArgumentException
   *         if the passed value is not empty and a <code>null</code> value is
   *         contained
   */
  @Nullable
  public static <T extends Iterable <?>> T noNullValue (final T aValue,

  public static <T> T [] notNullNoNullValue (final T [] aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    noNullValue (aValue, aName);
    return aValue;
  }

  /**
   * Check that the passed collection is not <code>null</code> and that no
   * <code>null</code> value is contained.
   *
   * @param <T>
   *        Type to be checked and returned
   * @param aValue
   *        The collection to check.
   * @param sName
   *        The name of the value (e.g. the parameter name)
   * @return The passed value.
   * @throws IllegalArgumentException
   *         if the passed value is <code>null</code> or a <code>null</code>
   *         value is contained
   */
  public static <T extends Iterable <?>> T notNullNoNullValue (final T aValue, final String sName)

  public static <T> T [] notEmptyNoNullValue (final T [] aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notEmpty (aValue, aName);
    noNullValue (aValue, aName);
    return aValue;
  }

  /**
   * Check that the passed collection is neither <code>null</code> nor empty and
   * that no <code>null</code> value is contained.
   *
   * @param <T>
   *        Type to be checked and returned
   * @param aValue
   *        The collection to check.
   * @param sName
   *        The name of the value (e.g. the parameter name)
   * @return The passed value.
   * @throws IllegalArgumentException
   *         if the passed value is empty or a <code>null</code> value is
   *         contained
   */
  public static <T extends Iterable <?>> T notEmptyNoNullValue (final T aValue, final String sName)

  public JAnnotationUse param (@Nonnull final String sName, @Nonnull final Enum <?> aValue)
  {
    return _addValue (sName, wrap (aValue));
  }

  @Nonnull
  public JAnnotationUse paramArray (@Nonnull final String sName, @Nonnull final Enum <?>... aValues)

    final JPackage [] pkgs = m_aPackages.values ().toArray (new JPackage [m_aPackages.size ()]);
    // avoid concurrent modification exception
    for (final JPackage pkg : pkgs)

  public JCHashCodeGenerator append (@Nullable final Object x)
  {
    _checkClosed ();
    m_nHC = JCHashCodeCalculator.append (m_nHC, x);
    return this;
  }

  /**
   * Object hash code generation.
   *
   * @param x
   *        Array to add
   * @return this
   */
  @Nonnull
  public JCHashCodeGenerator append (@Nullable final Enum <?> x)

  public static <T extends Collection <?>> T notEmpty (final T aValue, final String sName)
  {
    return notEmpty (aValue, () -> sName);
  }

  /**
   * Check that the passed {@link Collection} is neither <code>null</code> nor
   * empty.
   *
   * @param <T>
   *        Type to be checked and returned
   * @param aValue
   *        The String to check.
   * @param aName
   *        The name of the value (e.g. the parameter name)
   * @return The passed value.
   * @throws IllegalArgumentException
   *         if the passed value is empty
   */
  public static <T extends Collection <?>> T notEmpty (final T aValue, @Nonnull final Supplier <? extends String> aName)

  public static BigDecimal isGE0 (final BigDecimal aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    if (isEnabled ())
      if (aValue.compareTo (BigDecimal.ZERO) < 0)

      return componentType.array ();
    }
    catch (final CodeModelBuildingException ex)
    {
      throw new RuntimeCodeModelBuildingException (ex);
    }
    catch (final ErrorTypeFound ex)
    {
      throw new RuntimeErrorTypeFound (ex);
    }
  }

  public JCHashCodeGenerator append (@Nullable final Enum <?> x)
  {
    _checkClosed ();
    m_nHC = JCHashCodeCalculator.append (m_nHC, x);
    return this;
  }

  /**
   * Array hash code generation.
   *
   * @param x
   *        Array to add
   * @return this
   */
  @Nonnull
  public JCHashCodeGenerator append (@Nullable final boolean [] x)

  public static <T extends CharSequence> T notEmpty (final T aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    if (isEnabled ())
      if (aValue.length () == 0)

  public JCHashCodeGenerator append (@Nullable final Enum <?> x)
  {
    _checkClosed ();
    m_nHC = JCHashCodeCalculator.append (m_nHC, x);
    return this;
  }

  /**
   * Array hash code generation.
   *
   * @param x
   *        Array to add
   * @return this
   */
  @Nonnull
  public JCHashCodeGenerator append (@Nullable final boolean [] x)

  public JCHashCodeGenerator append (@Nullable final boolean [] x)
  {
    _checkClosed ();
    m_nHC = JCHashCodeCalculator.append (m_nHC, x);
    return this;
  }

  /**
   * Array hash code generation.
   *
   * @param x
   *        Array to add
   * @return this
   */
  @Nonnull
  public JCHashCodeGenerator append (@Nullable final byte [] x)

  public static <T> T [] notEmpty (final T [] aValue, @Nonnull final Supplier <? extends String> aName)
  {
    notNull (aValue, aName);
    if (isEnabled ())
      if (aValue.length == 0)

      if (!aValue.equals (aExpectedValue))
        throw new IllegalArgumentException ("The value of '" +
                                            aName.get () +
                                            "' does not match the expected value. Passed value: " +
                                            aValue +
                                            " -- Expected value: " +
                                            aExpectedValue);
    return aValue;
  }

  /**
   * Check that the passed value is the same as the provided expected value
   * using <code>==</code> to check comparison.
   *
   * @param <T>
   *        Type to be checked and returned
   * @param aValue
   *        The value to check.
   * @param sName
   *        The name of the value (e.g. the parameter name)
   * @param aExpectedValue
   *        The expected value. May be <code>null</code>.
   * @return The passed value and maybe <code>null</code> if the expected value
   *         is null.
   * @throws IllegalArgumentException
   *         if the passed value is not <code>null</code>.
   */
  public static <T> T isSame (final T aValue, final String sName, @Nullable final T aExpectedValue)

    return new FilterOutputStream (m_aPS)
    {
      @Override
      public void close ()
      {
        // don't let this stream close
      }
    };
  }

  @Override
  public void close () throws IOException
  {
    m_aPS.close ();