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