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