CompareToTheory

/*
 * Copyright 2008-2013 smartics, Kronseder & Reiner GmbH
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package de.smartics.util.test.theories;

import static org.hamcrest.CoreMatchers.equalTo;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.CoreMatchers.not;
import static org.junit.Assert.assertThat;
import static org.junit.Assume.assumeThat;

import org.junit.Assert;
import org.junit.experimental.theories.Theories;
import org.junit.experimental.theories.Theory;
import org.junit.runner.RunWith;

/* CHECKSTYLE:OFF */
/**
 * Tests theory on comparable instances.
 *
 * @param <T> the type of the comparable to test here.
 * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
 * @version $Revision:591 $
 */
@RunWith(Theories.class)
public abstract class CompareToTheory<T extends Comparable<T>> // NOPMD
/* CHECKSTYLE:ON */
{
  // ********************************* Fields *********************************

  // --- constants ------------------------------------------------------------

  // --- members --------------------------------------------------------------

  // ****************************** Inner Classes *****************************

  // ********************************* Methods ********************************

  // --- prepare --------------------------------------------------------------

  // --- helper ---------------------------------------------------------------

  private static void assumeThatValueIsNotNull(final Object uut)
  {
    assumeThat(uut, is(not(equalTo(null))));
  }

  // CHECKSTYLE:OFF
  /**
   * Determines whether or not the theory should check the
   * {@link Comparable#compareTo(Object)} is consistent with
   * {@link Object#equals(Object)}.
   * <p>
   * Override this method by your subclass.
   * </p>
   *
   * @return <code>true</code> per default.
   */
  protected boolean checkConsistentWithEquals()
  {
    return true;
  }

  // CHECKSTYLE:ON

  private static <T extends Comparable<T>> String thrownMessage(
      final String prefix, final TestAtom<T> atom1, final TestAtom<T> atom2)
  {
    final StringBuilder buffer = new StringBuilder(64);
    buffer.append(prefix).append(" did not throw an exception, while ");
    appendMessage(buffer, atom1.label, atom1.e);
    buffer.append(" and");
    appendMessage(buffer, atom2.label, atom2.e);
    return buffer.toString();
  }

  private static void appendMessage(final StringBuilder buffer,
      final String label, final Exception thrownException)
  {
    buffer.append(label).append(" did ")
        .append(thrownException == null ? "not " : "");
  }

  private static boolean noExceptionThrown(final TestAtom<?>... atoms)
  {
    for (final TestAtom<?> e : atoms)
    {
      if (e.isExceptionThrown())
      {
        return false;
      }
    }
    return true;
  }

  // --- tests ----------------------------------------------------------------

  /**
   * Executes the test and stores the value, be it an exception or the
   * calculated value.
   */
  private static final class TestAtom<T extends Comparable<T>>
  {
    /**
     * A label for reporting failures.
     */
    private final String label;

    /**
     * The result comparing the UUTs.
     */
    private int value;

    /**
     * The exception raised (if any) during the comparing of the UUTs.
     */
    private Exception e;

    private TestAtom(final String label, final T uutX, final T uutY)
    {
      this.label = label;
      try
      {
        this.value = uutX.compareTo(uutY);
      }
      catch (final Exception e)
      {
        this.e = e;
      }
    }

    private boolean isExceptionThrown()
    {
      return e != null;
    }
  }

  // CHECKSTYLE:OFF
  /**
   * Checks the symmetric property of the {@link Comparable#compareTo(Object)}
   * method.
   * <p>
   * <blockquote>
   * <p>
   * The implementor must ensure <tt>sgn(x.compareTo(y)) ==
   * -sgn(y.compareTo(x))</tt> for all <tt>x</tt> and <tt>y</tt>. (This implies
   * that <tt>x.compareTo(y)</tt> must throw an exception iff
   * <tt>y.compareTo(x)</tt> throws an exception.)
   * </p>
   * </blockquote>
   *
   * @param uutX the unit under test to test for symmetry.
   * @param uutY the unit under test to test for symmetry.
   * @see Comparable#compareTo(Object)
   */
  @Theory
  public void compareToIsSymmetric(final T uutX, final T uutY)
  // CHECKSTYLE:ON
  {
    assumeThatValueIsNotNull(uutX);
    assumeThatValueIsNotNull(uutY);

    final TestAtom<T> xToY = new TestAtom<T>("X", uutX, uutY);
    final TestAtom<T> yToX = new TestAtom<T>("Y", uutY, uutX);

    if (noExceptionThrown(xToY, yToX))
    {
      assertThat(xToY.value == -yToX.value, is(true));
    }
    else if (xToY.e != null)
    {
      assertThat("Only X threw an exception.", yToX.e, is(not(equalTo(null))));
    }
    else
    {
      Assert.fail("Only Y threw an exception.");
    }
  }

  /**
   * Checks the transitive property of the {@link Comparable#compareTo(Object)}
   * method.
   * <p>
   * <blockquote>
   * <p>
   * The implementor must also ensure that the relation is transitive:
   * <tt>(x.compareTo(y)&gt;0 &amp;&amp; y.compareTo(z)&gt;0)</tt> implies
   * <tt>x.compareTo(z)&gt;0</tt>.
   * </p>
   * <p>
   * <p>
   * Finally, the implementor must ensure that <tt>x.compareTo(y)==0</tt>
   * implies that <tt>sgn(x.compareTo(z)) == sgn(y.compareTo(z))</tt>, for all
   * <tt>z</tt>.
   * </p>
   * </blockquote>
   *
   * @param uutX the unit under test to test for transitivity.
   * @param uutY the unit under test to test for transitivity.
   * @param uutZ the unit under test to test for transitivity.
   * @see Comparable#compareTo(Object)
   */
  @Theory
  public final void compareToIsTransitive(final T uutX, final T uutY,
      final T uutZ)
  {
    assumeThatValueIsNotNull(uutX);
    assumeThatValueIsNotNull(uutY);

    final TestAtom<T> xToY = new TestAtom<T>("X", uutX, uutY);
    final TestAtom<T> yToZ = new TestAtom<T>("Y", uutY, uutZ);
    final TestAtom<T> xToZ = new TestAtom<T>("Z", uutX, uutZ);

    if (noExceptionThrown(xToY, yToZ, xToZ))
    {
      assumeThat(xToY.value > 0 && yToZ.value > 0, is(equalTo(true)));
      assertThat(xToZ.value > 0, is(equalTo(true)));
    }
    else
    {
      assertThat(thrownMessage("X", yToZ, xToZ), xToY, is(not(equalTo(null))));
      assertThat(thrownMessage("Y", xToY, xToZ), yToZ, is(not(equalTo(null))));
      assertThat(thrownMessage("Z", xToY, yToZ), xToZ, is(not(equalTo(null))));
    }
  }

  /**
   * Checks the optional consistent to equals property of the
   * {@link Comparable#compareTo(Object)} method.
   * <p>
   * <blockquote>
   * <p>
   * It is strongly recommended, but <i>not</i> strictly required that
   * <tt>(x.compareTo(y)==0) == (x.equals(y))</tt>. Generally speaking, any
   * class that implements the <tt>Comparable</tt> interface and violates this
   * condition should clearly indicate this fact. The recommended language is
   * "Note: this class has a natural ordering that is inconsistent with equals."
   * </p>
   * </blockquote>
   *
   * @param uutX the unit under test to test for consistency with equals.
   * @param uutY the unit under test to test for consistency with equals.
   * @see Comparable#compareTo(Object)
   */
  @Theory
  public final void compareToIsConsistentToEquals(final T uutX, final T uutY)
  {
    if (checkConsistentWithEquals())
    {
      assumeThatValueIsNotNull(uutX);

      final TestAtom<T> xToY = new TestAtom<T>("X", uutX, uutY);

      assumeThat(xToY.isExceptionThrown(), is(equalTo(false)));
      assumeThat(xToY.value, is(equalTo(0)));

      assertThat(uutX.equals(uutY), is(equalTo(true)));
    }
  }
}