001/*
002 * ============================================================================
003 * Copyright © 2002-2023 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.exception;
019
020import static java.lang.String.format;
021import static org.apiguardian.api.API.Status.STABLE;
022import static org.tquadrat.foundation.lang.CommonConstants.EMPTY_STRING;
023import static org.tquadrat.foundation.lang.Objects.nonNull;
024
025import java.io.Serial;
026
027import org.apiguardian.api.API;
028import org.tquadrat.foundation.annotation.ClassVersion;
029
030/**
031 *  This is a specialized implementation for the
032 *  {@link IllegalArgumentException}
033 *  that should be used instead of the latter in cases where {@code null} is
034 *  provided as an illegal argument value.
035 *
036 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
037 *  @version $Id: NullArgumentException.java 1060 2023-09-24 19:21:40Z tquadrat $
038 *  @since 0.0.5
039 *
040 *  @UMLGraph.link
041 */
042@ClassVersion( sourceVersion = "$Id: NullArgumentException.java 1060 2023-09-24 19:21:40Z tquadrat $" )
043@API( status = STABLE, since = "0.0.5" )
044public sealed class NullArgumentException extends ValidationException
045    permits BlankArgumentException, EmptyArgumentException
046{
047        /*------------------------*\
048    ====** Static Initialisations **===========================================
049        \*------------------------*/
050    /**
051     *  The serial version UID for objects of this class: {@value}.
052     *
053     *  @hidden
054     */
055    @Serial
056    private static final long serialVersionUID = 1174360235354917591L;
057
058        /*--------------*\
059    ====** Constructors **=====================================================
060        \*--------------*/
061    /**
062     *  Creates a new instance of {@code NullArgumentException}.
063     */
064    public NullArgumentException() { this( null ); }
065
066    /**
067     *  Creates a new instance of {@code NullArgumentException}.
068     *
069     *  @param  argName The name of the argument whose value was provided as
070     *      {@code null}; if {@code null} or the empty String, a
071     *      default message is used that does not use the name of the argument.
072     */
073    public NullArgumentException( final String argName )
074    {
075        this( argName, "Argument '%1$s' must not be null", "Argument must not be null" );
076    }   //  NullArgumentException()
077
078    /**
079     *  Creates a new instance of {@code NullArgumentException}.
080     *
081     *  @param  argName1    The name of the first argument whose value was
082     *      provided as {@code null}.
083     *  @param  argName2    The name of the second argument whose value was
084     *      provided as {@code null}.
085     *
086     *  @see org.tquadrat.foundation.lang.Objects#requireNonNullArgument(Object, Object, String, String)
087     */
088    @API( status = STABLE, since = "0.0.7" )
089    public NullArgumentException( final String argName1, final String argName2 )
090    {
091        this( "'%s' and '%s'".formatted( argName1, argName2 ), "%s are both null", EMPTY_STRING );
092    }   //  NullArgumentException()
093
094    /**
095     *  <p>{@summary Creates a new instance of
096     *  {@code NullArgumentException}.}</p>
097     *  <p>This constructor was introduced for the
098     *  {@link EmptyArgumentException}.</p>
099     *
100     *  @param  argName The name of the argument whose value was provided as
101     *      {@code null}; if {@code null} or the empty String, a
102     *      default message is used that does not use the name of the argument.
103     *  @param  msgName The regular message.
104     *  @param  msgNone The default message.
105     */
106    protected NullArgumentException( final String argName, final String msgName, final String msgNone )
107    {
108        super( nonNull( argName ) && !argName.isEmpty() ? format( msgName, argName ) : msgNone );
109    }   //  NullArgumentException()
110}
111//  class NullArgumentException
112
113/*
114 *  End of File
115 */