Home | History | Annotate | Download | only in hamcrest 
      1 /*  Copyright (c) 2000-2006 hamcrest.org
      2  */
      3 package org.hamcrest;
      4 
      5 /**
      6  * A matcher over acceptable values.
      7  * A matcher is able to describe itself to give feedback when it fails.
      8  * <p/>
      9  * Matcher implementations should <b>NOT directly implement this interface</b>.
     10  * Instead, <b>extend</b> the {@link BaseMatcher} abstract class,
     11  * which will ensure that the Matcher API can grow to support
     12  * new features and remain compatible with all Matcher implementations.
     13  * <p/>
     14  * For easy access to common Matcher implementations, use the static factory
     15  * methods in {@link CoreMatchers}.
     16  *
     17  * @see CoreMatchers
     18  * @see BaseMatcher
     19  */
     20 @SuppressWarnings({"unused", "UnusedDeclaration"})
     21 public interface Matcher<T> extends SelfDescribing {
     22 
     23     /**
     24      * Evaluates the matcher for argument <var>item</var>.
     25      * <p/>
     26      * This method matches against Object, instead of the generic type T. This is
     27      * because the caller of the Matcher does not know at runtime what the type is
     28      * (because of type erasure with Java generics). It is down to the implementations
     29      * to check the correct type.
     30      *
     31      * @param item the object against which the matcher is evaluated.
     32      * @return <code>true</code> if <var>item</var> matches, otherwise <code>false</code>.
     33      *
     34      * @see BaseMatcher
     35      */
     36     boolean matches(Object item);
     37 
     38     /**
     39      * This method simply acts a friendly reminder not to implement Matcher directly and
     40      * instead extend BaseMatcher. It's easy to ignore JavaDoc, but a bit harder to ignore
     41      * compile errors .
     42      *
     43      * @see Matcher for reasons why.
     44      * @see BaseMatcher
     45      */
     46     void _dont_implement_Matcher___instead_extend_BaseMatcher_();
     47 }
     48