001    /*
002     * Created on Oct 10, 2007
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     *
014     * Copyright @2007-2009 the original author or authors.
015     */
016    package org.fest.assertions;
017    
018    import static org.fest.assertions.Fail.failWithMessage;
019    import static org.fest.assertions.Formatting.format;
020    import static org.fest.assertions.Formatting.valueOf;
021    
022    /**
023     * Understands the base class for all assertion methods for objects and primitives.
024     *
025     * @author Yvonne Wang
026     * @author Alex Ruiz
027     */
028    public abstract class Assert {
029    
030      private Description description;
031      private String errorMessage;
032    
033      /**
034       * Returns the description of the actual value in this assertion.
035       * @return the description of the actual value in this assertion.
036       */
037      public final String description() {
038        return valueOf(description);
039      }
040    
041      /**
042       * Sets the description of the actual value, to be used in as message of any <code>{@link AssertionError}</code>
043       * thrown when an assertion fails.
044       * @param d the new description.
045       */
046      protected final void description(String d) {
047        description(new BasicDescription(d));
048      }
049    
050      /**
051       * Sets the description of the actual value, to be used in as message of any <code>{@link AssertionError}</code>
052       * thrown when an assertion fails.
053       * @param d the new description.
054       */
055      protected final void description(Description d) {
056        this.description = d;
057      }
058    
059      /**
060       * Returns the description of the actual value in this assertion.
061       * @return the description of the actual value in this assertion.
062       * @since 1.2
063       */
064      protected final Description rawDescription() {
065        return description;
066      }
067    
068      /**
069       * Returns the given message formatted as follows:
070       * <pre>
071       * [assertion description] given message.
072       * </pre>
073       * @param message the message to format.
074       * @return the formatted message.
075       */
076      protected final String formattedErrorMessage(String message) {
077        return format(description, message);
078      }
079    
080      /**
081       * Specifies the message to use in case of a failure, replacing the default one.
082       * @param message the new error message.
083       */
084      protected final void replaceDefaultErrorMessagesWith(String message) {
085        errorMessage = message;
086      }
087    
088      /**
089       * Returns the message to use when a failure occurs, if one has been specified.
090       * @return the message to use when a failure occurs, or <code>null</code> if none has been specified.
091       */
092      protected final String customErrorMessage() {
093        return errorMessage;
094      }
095    
096      /**
097       * Throws an <code>{@link AssertionError}</code> only if the the custom message in this assertion object is not
098       * <code>null</code>.
099       * @throws AssertionError only if the custom error message in this assertion object is not <code>null</code>.
100       * @since 1.2
101       */
102      protected final void failIfCustomMessageIsSet() {
103        failWithMessage(customErrorMessage());
104      }
105    
106      /**
107       * Throws an <code>{@link AssertionError}</code> only if the the custom message in this assertion object is not
108       * <code>null</code>.
109       * @param realCause cause of the error.
110       * @throws AssertionError only if the custom error message in this assertion object is not <code>null</code>.
111       * @since 1.2
112       */
113      protected final void failIfCustomMessageIsSet(Throwable realCause) {
114        failWithMessage(customErrorMessage(), realCause);
115      }
116    
117      /**
118       * Fails by throwing an <code>{@link AssertionError}</code>.
119       * <p>
120       * <strong>Note:</strong> This method appears to return <code>{@link AssertionError}</code>, but it is really not the
121       * case, since the exception is thrown and not returned. In version 2.0 the return type of this method will change
122       * to <code>void</code>. Since we cannot create an overloaded version with return type <code>void</code>, we cannot
123       * deprecate this method. Please pretend this method does not return anything :)
124       * </p>
125       * @param reason the reason for the failure, used as the message for the thrown exception.
126       * @return the thrown <code>AssertionError</code>.
127       * @throws AssertionError using the given reason as the message.
128       * @see #failure(String)
129       */
130      protected final AssertionError fail(String reason) {
131        // TODO in 2.0: change return type to 'void'
132        throw failure(reason);
133      }
134    
135      /**
136       * Creates an <code>{@link AssertionError}</code>, adding the description of the actual value to the given message.
137       * @param reason the reason for the failure, used as the message for the thrown exception.
138       * @return the created exception.
139       */
140      protected final AssertionError failure(String reason) {
141        return Fail.failure(formattedErrorMessage(reason));
142      }
143    
144      /**
145       * Fails by throwing an <code>{@link AssertionError}</code>.
146       * @param reason the reason for the failure, used as the message for the thrown exception.
147       * @param cause the root cause of the failure, included in the thrown exception.
148       */
149      protected final void fail(String reason, Throwable cause) {
150        Fail.fail(formattedErrorMessage(reason), cause);
151      }
152    
153      /**
154       * Throws <code>{@link UnsupportedOperationException}</code> if called. It is easy to accidentally call
155       * <code>{@link #equals(Object)}</code> instead of <code>isEqualTo</code>.
156       * @throws UnsupportedOperationException if this method is called.
157       */
158      @Override public final boolean equals(Object obj) {
159        throw new UnsupportedOperationException("'equals' is not supported...maybe you intended to call 'isEqualTo'");
160      }
161    
162      /**
163       * Always returns 1.
164       * @return 1.
165       */
166      @Override public final int hashCode() { return 1; }
167    }