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 org.apiguardian.api.API.Status.STABLE;
021import static org.tquadrat.foundation.lang.Objects.requireNotEmptyArgument;
022
023import java.io.Serial;
024
025import org.apiguardian.api.API;
026import org.tquadrat.foundation.annotation.ClassVersion;
027
028/**
029 *  This is a specialized implementation for the
030 *  {@link IllegalArgumentException}
031 *  that should be used instead of the latter in cases where a
032 *  {@link CharSequence}
033 *  provided as a method argument is too long according to some external
034 *  constraints, like the column definition of a database.
035 *
036 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
037 *  @version $Id: CharSequenceTooLongException.java 1060 2023-09-24 19:21:40Z tquadrat $
038 *  @since 0.0.5
039 *
040 *  @UMLGraph.link
041 */
042@ClassVersion( sourceVersion = "$Id: CharSequenceTooLongException.java 1060 2023-09-24 19:21:40Z tquadrat $" )
043@API( status = STABLE, since = "0.0.5" )
044public final class CharSequenceTooLongException extends ValidationException
045{
046        /*------------------------*\
047    ====** Static Initialisations **===========================================
048        \*------------------------*/
049    /**
050     *  The serial version UID for objects of this class: {@value}.
051     *
052     *  @hidden
053     */
054    @Serial
055    private static final long serialVersionUID = 1174360235354917591L;
056
057        /*--------------*\
058    ====** Constructors **=====================================================
059        \*--------------*/
060    /**
061     *  Creates a new instance of {@code CharSequenceTooLongException}.
062     *
063     *  @param  argName The name of the argument whose value was too long.
064     *  @param  maxLength   The maximum length.
065     */
066    public CharSequenceTooLongException( final String argName, final int maxLength )
067    {
068        super( "The text for argument '%1$s' is too long; the maximum length is %2$d characters".formatted( requireNotEmptyArgument( argName, "argName" ), checkLength( maxLength ) ) );
069    }   //  CharSequenceTooLongException()
070
071    /**
072     *  Creates a new instance of {@code CharSequenceTooLongException}.
073     *
074     *  @param  maxLength   The maximum length.
075     */
076    public CharSequenceTooLongException( final int maxLength )
077    {
078        super( "The text is too long; the maximum length is %d characters".formatted( checkLength( maxLength ) ) );
079    }   //  CharSequenceTooLongException()
080
081        /*---------*\
082    ====** Methods **==========================================================
083        \*---------*/
084    /**
085     *  Checks the given value.
086     *
087     *  @param  maxLength   The provided legal length for a text.
088     *  @return The given value.
089     *  @throws ValidationException The given value was less than 1.
090     */
091    private static int checkLength( final int maxLength ) throws ValidationException
092    {
093        if( maxLength <= 0 ) throw new ValidationException( "The given maximum length is 0 or less than 0: %d".formatted( maxLength ) );
094
095        //---* Done *----------------------------------------------------------
096        return maxLength;
097    }   //  checkLength()
098}
099//  class CharSequenceTooLongException
100
101/*
102 *  End of File
103 */