001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * 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 is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.assertions;
014
015import java.io.*;
016
017import org.apache.juneau.internal.*;
018
019/**
020 * Parent class of all fluent assertion calls.
021 *
022 * <p>
023 * Defines a {@link #returns()} method that returns an original object.
024 * Assertion test methods that pass use this method to return to the origin of the call.
025 *
026 * <h5 class='figure'>Example:</h5>
027 * <p class='bjava'>
028 *    <jc>// Create a basic REST client with JSON support and download a bean.</jc>
029 *    MyPojo <jv>myPojo</jv> = ...;
030 *    MyTestedBean <jv>myTestedBean</jv> = ...;
031 *
032 *    Assertion <jv>assertion</jv> = <jk>new</jk> FluentBeanAssertion&lt;MyPojo,MyTestedBean&gt;(<jv>myPojo</jv>, <jv>myTestedBean</jv>);
033 *    <jv>myPojo</jv> = <jv>assertion</jv>.test(<jv>x</jv> -&gt; <jv>x</jv>.getMyProperty().equals(<js>"foo"</js>));  <jc>// Returns myPojo after test.</jc>
034 * </p>
035 * <p>
036 * For subclasses such as {@link IntegerAssertion}, the return object is simply itself so that multiple tests
037 * can be performed using the same assertion.
038 * <h5 class='figure'>Example:</h5>
039 * <p class='bjava'>
040 *    <jk>public class</jk> IntegerAssertion <jk>extends</jk> FluentIntegerAssertion&lt;IntegerAssertion&gt; {
041 *    ...
042 *    }
043 *
044 *    Assertion <jv>assertion</jv> = <jk>new</jk> IntegerAssertion(123);
045 *    <jv>assertion</jv>
046 *       .isNotNull()
047 *       .isGt(100)
048 *  ;
049 * </p>
050 *
051 *
052 * <h5 class='section'>Test Methods:</h5>
053 * <p>
054 * <ul class='javatree'>
055 *    <li>None
056 * </ul>
057  *
058 * <h5 class='section'>Transform Methods:</h5>
059 * <p>
060 * <ul class='javatree'>
061 *    <li>None
062 * </ul>
063 *
064 * <h5 class='section'>Configuration Methods:</h5>
065 * <p>
066 * <ul class='javatree'>
067 *    <li class='jc'>{@link Assertion}
068 *    <ul class='javatreec'>
069 *       <li class='jm'>{@link Assertion#setMsg(String, Object...) setMsg(String, Object...)}
070 *       <li class='jm'>{@link Assertion#setOut(PrintStream) setOut(PrintStream)}
071 *       <li class='jm'>{@link Assertion#setSilent() setSilent()}
072 *       <li class='jm'>{@link Assertion#setStdOut() setStdOut()}
073 *       <li class='jm'>{@link Assertion#setThrowable(Class) setThrowable(Class)}
074 *    </ul>
075 * </ul>
076 *
077 * <h5 class='section'>See Also:</h5><ul>
078 *    <li class='link'><a class="doclink" href="../../../../index.html#ja.Overview">Overview &gt; juneau-assertions &gt; Overview</a>
079 * </ul>
080 *
081 * @param <R> The return type.
082 */
083@FluentSetters(returns="FluentAssertion<R>")
084public abstract class FluentAssertion<R> extends Assertion {
085
086   //-----------------------------------------------------------------------------------------------------------------
087   // Instance
088   //-----------------------------------------------------------------------------------------------------------------
089
090   private final R returns;
091
092   /**
093    * Constructor.
094    *
095    * @param creator
096    *    The assertion that created this assertion.
097    *    <br>Should be <jk>null</jk> if this is the top-level assertion.
098    * @param returns
099    *    The object to return after a test method is called.
100    *    <br>If <jk>null</jk>, the test method returns this object allowing multiple test method calls to be
101    * used on the same assertion.
102    */
103   protected FluentAssertion(Assertion creator, R returns) {
104      super(creator);
105      this.returns = returns;
106   }
107
108   //-----------------------------------------------------------------------------------------------------------------
109   // Fluent setters
110   //-----------------------------------------------------------------------------------------------------------------
111
112   // <FluentSetters>
113
114   @Override /* GENERATED - org.apache.juneau.assertions.Assertion */
115   public FluentAssertion<R> setMsg(String msg, Object...args) {
116      super.setMsg(msg, args);
117      return this;
118   }
119
120   @Override /* GENERATED - org.apache.juneau.assertions.Assertion */
121   public FluentAssertion<R> setOut(PrintStream value) {
122      super.setOut(value);
123      return this;
124   }
125
126   @Override /* GENERATED - org.apache.juneau.assertions.Assertion */
127   public FluentAssertion<R> setSilent() {
128      super.setSilent();
129      return this;
130   }
131
132   @Override /* GENERATED - org.apache.juneau.assertions.Assertion */
133   public FluentAssertion<R> setStdOut() {
134      super.setStdOut();
135      return this;
136   }
137
138   @Override /* GENERATED - org.apache.juneau.assertions.Assertion */
139   public FluentAssertion<R> setThrowable(Class<? extends java.lang.RuntimeException> value) {
140      super.setThrowable(value);
141      return this;
142   }
143
144   // </FluentSetters>
145
146   //-----------------------------------------------------------------------------------------------------------------
147   // Utility methods
148   //-----------------------------------------------------------------------------------------------------------------
149
150   /**
151    * Returns the object that the fluent methods on this class should return.
152    *
153    * @return The response object.
154    */
155   @SuppressWarnings("unchecked")
156   protected R returns() {
157      return returns != null ? returns : (R)this;
158   }
159
160}