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.exception;
019
020import static java.lang.String.format;
021import static org.apiguardian.api.API.Status.DEPRECATED;
022import static org.apiguardian.api.API.Status.STABLE;
023import static org.tquadrat.foundation.lang.Objects.nonNull;
024import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
025
026import java.io.Serial;
027
028import org.apiguardian.api.API;
029import org.tquadrat.foundation.annotation.ClassVersion;
030
031/**
032 *  <p>{@summary This implementation of
033 *  {@link Error}
034 *  should be thrown in all cases where an unexpected exception was caught.}
035 *  Unlike an
036 *  {@link ImpossibleExceptionError},
037 *  the exception is <i>possible</i>, but not expected – probably because the
038 *  programmer has taken (at least thought to have &hellip;) appropriate
039 *  precautions against its occurrence. An example for this could be an
040 *  implementation of
041 *  {@link Object#clone() clone()}
042 *  for a particular class: with implementing that method (and declaring the
043 *  interface
044 *  {@link Cloneable}
045 *  &hellip;), instances of that class do support cloning and therefore that
046 *  exception should not be thrown. Unfortunately, changes somewhere else in
047 *  the source might prevent one of the attributes of the respective class from
048 *  being cloned, so that exception could be thrown again &hellip;</p>
049 *  <p>Another example could be this code sequence:
050 *  <div class="source-container"><pre>…
051 *  final var file = new File( … );
052 *  if( file.exists() )
053 *  {
054 *      try( final var inputStream = new FileInputStream( file ) )
055 *      {
056 *          …
057 *      }
058 *      catch( final FileNotFoundException e )
059 *      {
060 *          throw new UnexpectedExceptionError( e );
061 *      }
062 *  }</pre></div>
063 *  <p>Although the code checked that the file exists, it could have vanished
064 *  <i>unexpectedly</i> just before it was opened.</p>
065 *
066 *  @author Thomas Thrien - thomas.thrien@tquadrat.org
067 *  @version $Id: UnexpectedExceptionError.java 1293 2026-10-16 13:12:15Z tquadrat $
068 *  @since 0.0.5
069 *
070 *  @UMLGraph.link
071 *
072 *  @deprecated Basically, this exception was renamed to
073 *      {@link UnlikelyExceptionError}
074 *      because that name matches the intention better than the original name.
075 */
076@ClassVersion( sourceVersion = "$Id: UnexpectedExceptionError.java 1293 2026-10-16 13:12:15Z tquadrat $" )
077@API( status = DEPRECATED, since = "0.0.5" )
078@Deprecated( since = "0.25.15", forRemoval = true )
079/*public*/ final class UnexpectedExceptionError extends AssertionError
080{
081        /*-----------*\
082    ====** Constants **========================================================
083        \*-----------*/
084    /**
085     *  The message for this exception.
086     */
087    private static final String MSG_UnexpectedException = "The Exception '%1$s' was not expected to occur in this context";
088
089        /*------------------------*\
090    ====** Static Initialisations **===========================================
091        \*------------------------*/
092    /**
093     *  The serial version UID for objects of this class: {@value}.
094     *
095     *  @hidden
096     */
097    @Serial
098    private static final long serialVersionUID = 2233464685783981770L;
099
100        /*--------------*\
101    ====** Constructors **=====================================================
102        \*--------------*/
103    /**
104     *  <p>{@summary {@constructor}} The message is a constant, only
105     *  the causing exception can be given.</p>
106     *
107     *  @param  cause   The causing exception.
108     */
109    public UnexpectedExceptionError( final Throwable cause )
110    {
111        super( format( MSG_UnexpectedException, requireNonNullArgument( cause, "cause" ).getClass().getName() ) , cause );
112    }   //  UnexpectedExceptionError()
113
114    /**
115     *  <p>{@summary {@constructor}} This constructor should be used in
116     *  cases where an enhanced message is useful or necessary.</p>
117     *
118     *  @param  message The message for the error.
119     *  @param  cause   The causing exception.
120     */
121    public UnexpectedExceptionError( final String message, final Throwable cause )
122    {
123        super( nonNull( message ) && !message.isEmpty() ? message : format( MSG_UnexpectedException, requireNonNullArgument( cause, "cause" ).getClass().getName() ), requireNonNullArgument( cause, "cause" ) );
124    }   //  UnexpectedExceptionError()
125}
126//  class UnexpectedExceptionError
127
128/*
129 *  End of File
130 */