001/*
002 * ============================================================================
003 * Copyright © 2002-2024 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.nonNull;
022import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
023
024import java.io.Serial;
025
026import org.apiguardian.api.API;
027import org.tquadrat.foundation.annotation.ClassVersion;
028
029/**
030 *  This implementation of
031 *  {@link Error}
032 *  should be thrown in all cases where an exception was caught that seemed to
033 *  be impossible to be thrown. An example for this is the method
034 *  {@link java.lang.String#getBytes(java.lang.String) String::getBytes( encoding )}
035 *  for the <code>encoding&nbsp;==&nbsp;&quot;UTF-8&quot;</code> that should
036 *  never throw an
037 *  {@link java.io.UnsupportedEncodingException UnsupportedEncodingException}
038 *  because the encoding {@code UTF-8} is mandatory for all implementations of
039 *  Java.<br>
040 *  <br>This is different from the
041 *  {@link UnexpectedExceptionError}
042 *  as that is possible in general, but not in the particular context.
043 *
044 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
045 *  @version $Id: ImpossibleExceptionError.java 1144 2024-09-08 22:35:47Z tquadrat $
046 *  @since 0.0.5
047 *
048 *  @UMLGraph.link
049 */
050@ClassVersion( sourceVersion = "$Id: ImpossibleExceptionError.java 1144 2024-09-08 22:35:47Z tquadrat $" )
051@API( status = STABLE, since = "0.0.5" )
052public final class ImpossibleExceptionError extends UnexpectedExceptionError
053{
054        /*-----------*\
055    ====** Constants **========================================================
056        \*-----------*/
057    /**
058     *  The text for the default message.
059     */
060    public static final String MSG_ImpossibleException = "The Exception '%1$s' was not expected and should never occur in this context";
061
062        /*------------------------*\
063    ====** Static Initialisations **===========================================
064        \*------------------------*/
065    /**
066     *  The serial version UID for objects of this class: {@value}.
067     *
068     *  @hidden
069     */
070    @Serial
071    private static final long serialVersionUID = 2233464685783981770L;
072
073        /*--------------*\
074    ====** Constructors **=====================================================
075        \*--------------*/
076    /**
077     *  Creates a new instance of {@code ImpossibleExceptionError}. The message
078     *  is a constant, only the causing exception can be given.
079     *
080     *  @param  cause   The causing exception.
081     */
082    public ImpossibleExceptionError( final Throwable cause )
083    {
084        super( MSG_ImpossibleException.formatted( requireNonNullArgument( cause, "cause" ).getClass().getName() ) , cause );
085    }   //  ImpossibleExceptionError()
086
087    /**
088     *  Creates a new instance of {@code ImpossibleExceptionError}. This
089     *  constructor should be used in cases where an enhanced message is useful
090     *  or necessary.
091     *
092     *  @param  message The message for the error.
093     *  @param  cause   The causing exception.
094     */
095    public ImpossibleExceptionError( final String message, final Throwable cause )
096    {
097        /*
098         * StringUtils::isNotEmpty is not available here …
099         */
100        super( nonNull( message ) && !message.isEmpty() ? message : MSG_ImpossibleException.formatted( requireNonNullArgument( cause, "cause" ).getClass().getName() ), requireNonNullArgument( cause, "cause" ) );
101    }   //  ImpossibleExceptionError()
102}
103//  class ImpossibleExceptionError
104
105/*
106 *  End of File
107 */