    001    /*  Copyright (c) 2000-2006 hamcrest.org
    002     */
    003    package org.hamcrest;
    004
    005    /**
    006     * A matcher over acceptable values.
    007     * A matcher is able to describe itself to give feedback when it fails.
    008     * <p/>
    009     * Matcher implementations should <b>NOT directly implement this interface</b>.
    010     * Instead, <b>extend</b> the {@link BaseMatcher} abstract class,
    011     * which will ensure that the Matcher API can grow to support
    012     * new features and remain compatible with all Matcher implementations.
    013     * <p/>
    014     * For easy access to common Matcher implementations, use the static factory
    015     * methods in {@link CoreMatchers}.
    016     * <p/>
    017     * N.B. Well designed matchers should be immutable.
    018     *
    019     * @see CoreMatchers
    020     * @see BaseMatcher
    021     */
    022    public interface Matcher<T> extends SelfDescribing {
    023
    024        /**
    025         * Evaluates the matcher for argument <var>item</var>.
    026         * <p/>
    027         * This method matches against Object, instead of the generic type T. This is
    028         * because the caller of the Matcher does not know at runtime what the type is
    029         * (because of type erasure with Java generics). It is down to the implementations
    030         * to check the correct type.
    031         *
    032         * @param item the object against which the matcher is evaluated.
    033         * @return <code>true</code> if <var>item</var> matches, otherwise <code>false</code>.
    034         *
    035         * @see BaseMatcher
    036         */
    037        boolean matches(Object item);
    038
    039        /**
    040         * Generate a description of why the matcher has not accepted the item.
    041         * The description will be part of a larger description of why a matching
    042         * failed, so it should be concise.
    043         * This method assumes that <code>matches(item)</code> is false, but
    044         * will not check this.
    045         *
    046         * @param item The item that the Matcher has rejected.
    047         * @param mismatchDescription
    048         *     The description to be built or appended to.
    049         */
    050        void describeMismatch(Object item, Description mismatchDescription);
    051
    052        /**
    053         * This method simply acts a friendly reminder not to implement Matcher directly and
    054         * instead extend BaseMatcher. It's easy to ignore JavaDoc, but a bit harder to ignore
    055         * compile errors .
    056         *
    057         * @see Matcher for reasons why.
    058         * @see BaseMatcher
    059         * @deprecated to make
    060         */
    061        @Deprecated
    062        void _dont_implement_Matcher___instead_extend_BaseMatcher_();
    063    }