001/*
002 * ============================================================================
003 * Copyright © 2002-2020 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 * Licensed to the public under the agreements of the GNU Lesser General Public
007 * License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *      http://www.gnu.org/licenses/lgpl.html
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, WITHOUT
013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 * License for the specific language governing permissions and limitations
015 * under the License.
016 */
017
018package org.tquadrat.foundation.testutil;
019
020import static org.apiguardian.api.API.Status.STABLE;
021
022import java.io.Serial;
023import java.io.Serializable;
024import java.util.Optional;
025
026import org.apiguardian.api.API;
027
028/**
029 *  This class is meant as the base class for test data records.
030 *
031 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
032 *  @version $Id: TestDataBase.java 820 2020-12-29 20:34:22Z tquadrat $
033 *  @since 0.1.0
034 *
035 *  @param  <E> The type of the expected result.
036 *
037 *  @UMLGraph.link
038 */
039@SuppressWarnings( {"AbstractClassNeverImplemented", "AbstractClassWithoutAbstractMethods"} )
040@API( status = STABLE, since = "0.0.5" )
041public abstract class TestDataBase<E> implements Serializable
042{
043        /*-----------*\
044    ====** Constants **========================================================
045        \*-----------*/
046    /**
047     *  An empty array of {@code TestDataBase} objects.
048     */
049    @SuppressWarnings( "rawtypes" )
050    public static final TestDataBase [] EMPTY_TestDataBase_ARRAY = new TestDataBase [0];
051
052        /*------------*\
053    ====** Attributes **=======================================================
054        \*------------*/
055    /**
056     *  The optional description of the test.
057     */
058    @SuppressWarnings( "OptionalUsedAsFieldOrParameterType" )
059    private final Optional<String> m_Description;
060
061    /**
062     *  The expected result.
063     */
064    @SuppressWarnings( "OptionalUsedAsFieldOrParameterType" )
065    private final Optional<E> m_Expected;
066
067        /*------------------------*\
068    ====** Static Initialisations **===========================================
069        \*------------------------*/
070    /**
071     *  The serial version UID for objects of this class: {@value}.
072     *
073     *  @hidden
074     */
075    @Serial
076    private static final long serialVersionUID = 1L;
077
078        /*--------------*\
079    ====** Constructors **=====================================================
080        \*--------------*/
081    /**
082     *  Creates a new {@code TestDataBase} instance.
083     *
084     *  @param  expected    The expected result for the test; if {@code null}
085     *      the test should fail.
086     */
087    protected TestDataBase( final E expected ) { this( expected, null ); }
088
089    /**
090     *  Creates a new {@code TestDataBase} instance.
091     *
092     *  @param  expected    The expected result for the test; if {@code null}
093     *      the test should fail.
094     *  @param  description The description for this test.
095     */
096    protected TestDataBase( final E expected, final String description )
097    {
098        m_Description = Optional.ofNullable( description );
099        m_Expected = Optional.ofNullable( expected );
100    }   //  TestDataBase()
101
102        /*---------*\
103    ====** Methods **==========================================================
104        \*---------*/
105    /**
106     *  Returns the description for the test.
107     *
108     *  @return An instance of
109     *      {@link Optional}
110     *      that holds the description.
111     */
112    public final Optional<String> description() { return m_Description; }
113
114    /**
115     *  Returns the expected result for the test. An empty return value
116     *  indicates that the test should fail.
117     *
118     *  @return An instance of
119     *      {@link Optional}
120     *      that holds the expected result.
121     */
122    public final Optional<E> expected() { return m_Expected; }
123
124    /**
125     *  Indicates whether the test should fail.
126     *
127     *  @return {@code true} if the test should fail, {@code false} if it
128     *      should be successful.
129     */
130    public final boolean shouldFail() { return m_Expected.isEmpty(); }
131}
132//  class TestDataBase
133
134/*
135 *  End of File
136 */