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 }