001/*
002 * ============================================================================
003 * Copyright © 2002-2026 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 org.apiguardian.api.API;
021
022import java.io.Serial;
023import java.io.Serializable;
024import java.util.Optional;
025
026import static org.apiguardian.api.API.Status.STABLE;
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 1158 2026-03-14 16:23:29Z 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     *  @serial
059     */
060    @SuppressWarnings( "OptionalUsedAsFieldOrParameterType" )
061    private final Optional<String> m_Description;
062
063    /**
064     *  The expected result.
065     *
066     *  @serial
067     */
068    @SuppressWarnings( "OptionalUsedAsFieldOrParameterType" )
069    private final Optional<E> m_Expected;
070
071        /*------------------------*\
072    ====** Static Initialisations **===========================================
073        \*------------------------*/
074    /**
075     *  The serial version UID for objects of this class: {@value}.
076     *
077     *  @hidden
078     */
079    @Serial
080    private static final long serialVersionUID = 1L;
081
082        /*--------------*\
083    ====** Constructors **=====================================================
084        \*--------------*/
085    /**
086     *  Creates a new {@code TestDataBase} instance.
087     *
088     *  @param  expected    The expected result for the test; if {@code null}
089     *      the test should fail.
090     */
091    protected TestDataBase( final E expected ) { this( expected, null ); }
092
093    /**
094     *  Creates a new {@code TestDataBase} instance.
095     *
096     *  @param  expected    The expected result for the test; if {@code null}
097     *      the test should fail.
098     *  @param  description The description for this test.
099     */
100    protected TestDataBase( final E expected, final String description )
101    {
102        m_Description = Optional.ofNullable( description );
103        m_Expected = Optional.ofNullable( expected );
104    }   //  TestDataBase()
105
106        /*---------*\
107    ====** Methods **==========================================================
108        \*---------*/
109    /**
110     *  Returns the description for the test.
111     *
112     *  @return An instance of
113     *      {@link Optional}
114     *      that holds the description.
115     */
116    public final Optional<String> description() { return m_Description; }
117
118    /**
119     *  Returns the expected result for the test. An empty return value
120     *  indicates that the test should fail.
121     *
122     *  @return An instance of
123     *      {@link Optional}
124     *      that holds the expected result.
125     */
126    public final Optional<E> expected() { return m_Expected; }
127
128    /**
129     *  Indicates whether the test should fail.
130     *
131     *  @return {@code true} if the test should fail, {@code false} if it
132     *      should be successful.
133     */
134    public final boolean shouldFail() { return m_Expected.isEmpty(); }
135}
136//  class TestDataBase
137
138/*
139 *  End of File
140 */