001/*  Copyright (c) 2000-2010 hamcrest.org
002 */
003package org.hamcrest.core;
004
005import static org.hamcrest.core.IsNot.not;
006import org.hamcrest.Description;
007import org.hamcrest.Matcher;
008import org.hamcrest.Factory;
009import org.hamcrest.BaseMatcher;
010
011/**
012 * Is the value null?
013 */
014public class IsNull<T> extends BaseMatcher<T> {
015    @Override
016    public boolean matches(Object o) {
017        return o == null;
018    }
019
020    @Override
021    public void describeTo(Description description) {
022        description.appendText("null");
023    }
024
025    /**
026     * Creates a matcher that matches if examined object is <code>null</code>.
027     * <p/>
028     * For example:
029     * <pre>assertThat(cheese, is(nullValue())</pre>
030     * 
031     */
032    @Factory
033    public static Matcher<Object> nullValue() {
034        return new IsNull<Object>();
035    }
036
037    /**
038     * A shortcut to the frequently used <code>not(nullValue())</code>.
039     * <p/>
040     * For example:
041     * <pre>assertThat(cheese, is(notNullValue()))</pre>
042     * instead of:
043     * <pre>assertThat(cheese, is(not(nullValue())))</pre>
044     * 
045     */
046    @Factory
047    public static Matcher<Object> notNullValue() {
048        return not(nullValue());
049    }
050
051    /**
052     * Creates a matcher that matches if examined object is <code>null</code>. Accepts a
053     * single dummy argument to facilitate type inference.
054     * <p/>
055     * For example:
056     * <pre>assertThat(cheese, is(nullValue(Cheese.class))</pre>
057     * 
058     * @param type
059     *     dummy parameter used to infer the generic type of the returned matcher
060     */
061    @Factory
062    public static <T> Matcher<T> nullValue(Class<T> type) {
063        return new IsNull<T>();
064    }
065
066    /**
067     * A shortcut to the frequently used <code>not(nullValue(X.class)). Accepts a
068     * single dummy argument to facilitate type inference.</code>.
069     * <p/>
070     * For example:
071     * <pre>assertThat(cheese, is(notNullValue(X.class)))</pre>
072     * instead of:
073     * <pre>assertThat(cheese, is(not(nullValue(X.class))))</pre>
074     * 
075     * @param type
076     *     dummy parameter used to infer the generic type of the returned matcher
077     *  
078     */
079    @Factory
080    public static <T> Matcher<T> notNullValue(Class<T> type) {
081        return not(nullValue(type));
082    }
083}
084