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