NotFoundException.java

  1. /*
  2.  * *************************************************************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 2024 by Tidalwave s.a.s. (http://tidalwave.it)
  8.  *
  9.  * *************************************************************************************************************************************************************
  10.  *
  11.  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
  12.  * You may obtain a copy of the License at
  13.  *
  14.  *     http://www.apache.org/licenses/LICENSE-2.0
  15.  *
  16.  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
  17.  * CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License.
  18.  *
  19.  * *************************************************************************************************************************************************************
  20.  *
  21.  * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
  22.  * git clone https://github.com/tidalwave-it/thesefoolishthings-src
  23.  *
  24.  * *************************************************************************************************************************************************************
  25.  */
  26. package it.tidalwave.util;

  27. import javax.annotation.Nonnull;
  28. import javax.annotation.Nullable;
  29. import java.util.Collection;

  30. /***************************************************************************************************************************************************************
  31.  *
  32.  * Notifies that a searched object couldn't be found.
  33.  *
  34.  * @author  Fabrizio Giudici
  35.  * @it.tidalwave.javadoc.stable
  36.  *
  37.  **************************************************************************************************************************************************************/
  38. public class NotFoundException extends Exception
  39.   {
  40.     private static final long serialVersionUID = 3453465498093L;

  41.     /***********************************************************************************************************************************************************
  42.      * Creates an empty exception.
  43.      **********************************************************************************************************************************************************/
  44.     public NotFoundException()
  45.       {
  46.       }

  47.     /***********************************************************************************************************************************************************
  48.      * Creates an exception with a message.
  49.      *
  50.      * @param  message            the message
  51.      **********************************************************************************************************************************************************/
  52.     public NotFoundException (@Nonnull final String message)
  53.       {
  54.         super(message);
  55.       }

  56.     /***********************************************************************************************************************************************************
  57.      * Creates an exception with a cause.
  58.      *
  59.      * @param  cause              the cause
  60.      **********************************************************************************************************************************************************/
  61.     public NotFoundException (@Nonnull final Throwable cause)
  62.       {
  63.         super(cause);
  64.       }

  65.     /***********************************************************************************************************************************************************
  66.      * Creates an exception with a message and a cause.
  67.      *
  68.      * @param  message            the message
  69.      * @param  cause              the cause
  70.      **********************************************************************************************************************************************************/
  71.     public NotFoundException (@Nonnull final String message, @Nonnull final Throwable cause)
  72.       {
  73.         super(message, cause);
  74.       }

  75.     /***********************************************************************************************************************************************************
  76.      * Throws the {@code NotFoundException} when the passed object is {@code null}. The method returns the object
  77.      * itself, so it can be used with fluent interfaces.
  78.      *
  79.      * @param  <T>                the type of the object
  80.      * @param  object             the object to be tested
  81.      * @param  message            the error message to be thrown
  82.      * @return                    the object
  83.      * @throws NotFoundException  if the object is null
  84.      **********************************************************************************************************************************************************/
  85.     @Nonnull // needed for binary backward compatibility (this method interprets % in message in verbatim mode)
  86.     public static <T> T throwWhenNull (@Nullable final T object, @Nonnull final String message)
  87.       throws NotFoundException
  88.       {
  89.         if (object == null)
  90.           {
  91.             throw new NotFoundException(message);
  92.           }

  93.         return object;
  94.       }

  95.     /***********************************************************************************************************************************************************
  96.      * Throws the {@code NotFoundException} when the passed object is {@code null}. The method returns the object
  97.      * itself, so it can be used with fluent interfaces.
  98.      *
  99.      * @param  <T>                the type of the object
  100.      * @param  object             the object to be tested
  101.      * @param  message            the error message to be thrown (formatted as in {@link String#format}
  102.      * @param  args               the arguments to format the error message
  103.      * @return                    the object
  104.      * @throws NotFoundException  if the object is null
  105.      **********************************************************************************************************************************************************/
  106.     @Nonnull
  107.     public static <T> T throwWhenNull (@Nullable final T object,
  108.                                        @Nonnull final String message,
  109.                                        @Nonnull final Object... args)
  110.       throws NotFoundException
  111.       {
  112.         if (object == null)
  113.           {
  114.             throw new NotFoundException(String.format(message, args));
  115.           }

  116.         return object;
  117.       }

  118.     /***********************************************************************************************************************************************************
  119.      * Throws the {@code NotFoundException} when the passed collection is {@code null} or empty. The method returns the
  120.      * collection itself, so it can be used with fluent interfaces.
  121.      *
  122.      * @param  <T>                the type of collection items
  123.      * @param  collection         the collection to be tested
  124.      * @param  message            the error message to be thrown
  125.      * @return                    the collection
  126.      * @throws NotFoundException  if the collection is null or empty
  127.      **********************************************************************************************************************************************************/
  128.     @Nonnull // needed for binary backward compatibility (this method interprets % in message in verbatim mode)
  129.     public static <T extends Collection<?>> T throwWhenEmpty (@Nullable final T collection,
  130.                                                               @Nonnull final String message)
  131.       throws NotFoundException
  132.       {
  133.         if ((collection == null) || collection.isEmpty())
  134.           {
  135.             throw new NotFoundException(message);
  136.           }

  137.         return collection;
  138.       }

  139.     /***********************************************************************************************************************************************************
  140.      * Throws the {@code NotFoundException} when the passed collection is {@code null} or empty. The method returns the
  141.      * collection itself, so it can be used with fluent interfaces.
  142.      *
  143.      * @param  <T>                the type of collection items
  144.      * @param  collection         the collection to be tested
  145.      * @param  message            the error message to be thrown (formatted as in {@link String#format}
  146.      * @param  args               the arguments to format the error message
  147.      * @return                    the collection
  148.      * @throws NotFoundException  if the collection is null or empty
  149.      **********************************************************************************************************************************************************/
  150.     @Nonnull
  151.     public static <T extends Collection<?>> T throwWhenEmpty (@Nullable final T collection,
  152.                                                               @Nonnull final String message,
  153.                                                               @Nonnull final Object... args)
  154.       throws NotFoundException
  155.       {
  156.         if ((collection == null) || collection.isEmpty())
  157.           {
  158.             throw new NotFoundException(String.format(message, args));
  159.           }

  160.         return collection;
  161.       }
  162.   }