NotFoundException.java

  1. /*
  2.  * *********************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 2023 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
  12.  * the License. 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
  17.  * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
  18.  * specific language governing permissions and limitations under the License.
  19.  *
  20.  * *********************************************************************************************************************
  21.  *
  22.  * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
  23.  * git clone https://github.com/tidalwave-it/thesefoolishthings-src
  24.  *
  25.  * *********************************************************************************************************************
  26.  */
  27. package it.tidalwave.util;

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

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

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

  50.     /*******************************************************************************************************************
  51.      *
  52.      * Creates an exception with a message.
  53.      *
  54.      * @param  message            the message
  55.      *
  56.      ******************************************************************************************************************/
  57.     public NotFoundException (@Nonnull final String message)
  58.       {
  59.         super(message);
  60.       }

  61.     /*******************************************************************************************************************
  62.      *
  63.      * Creates an exception with a cause.
  64.      *
  65.      * @param  cause              the cause
  66.      *
  67.      ******************************************************************************************************************/
  68.     public NotFoundException (@Nonnull final Throwable cause)
  69.       {
  70.         super(cause);
  71.       }

  72.     /*******************************************************************************************************************
  73.      *
  74.      * Creates an exception with a message and a cause.
  75.      *
  76.      * @param  message            the message
  77.      * @param  cause              the cause
  78.      *
  79.      ******************************************************************************************************************/
  80.     public NotFoundException (@Nonnull final String message, @Nonnull final Throwable cause)
  81.       {
  82.         super(message, cause);
  83.       }

  84.     /*******************************************************************************************************************
  85.      *
  86.      * Throws the {@code NotFoundException} when the passed object is {@code null}. The method returns the object
  87.      * itself, so it can be used with fluent interfaces.
  88.      *
  89.      * @param  <T>                the type of the object
  90.      * @param  object             the object to be tested
  91.      * @param  message            the error message to be thrown
  92.      * @return                    the object
  93.      * @throws NotFoundException  if the object is null
  94.      *
  95.      ******************************************************************************************************************/
  96.     @Nonnull // needed for binary backward compatibility (this method interprets % in message in verbatim mode)
  97.     public static <T> T throwWhenNull (@Nullable final T object, @Nonnull final String message)
  98.       throws NotFoundException
  99.       {
  100.         if (object == null)
  101.           {
  102.             throw new NotFoundException(message);
  103.           }

  104.         return object;
  105.       }

  106.     /*******************************************************************************************************************
  107.      *
  108.      * Throws the {@code NotFoundException} when the passed object is {@code null}. The method returns the object
  109.      * itself, so it can be used with fluent interfaces.
  110.      *
  111.      * @param  <T>                the type of the object
  112.      * @param  object             the object to be tested
  113.      * @param  message            the error message to be thrown (formatted as in {@link String#format}
  114.      * @param  args               the arguments to format the error message
  115.      * @return                    the object
  116.      * @throws NotFoundException  if the object is null
  117.      *
  118.      ******************************************************************************************************************/
  119.     @Nonnull
  120.     public static <T> T throwWhenNull (@Nullable final T object,
  121.                                        @Nonnull final String message,
  122.                                        @Nonnull final Object... args)
  123.       throws NotFoundException
  124.       {
  125.         if (object == null)
  126.           {
  127.             throw new NotFoundException(String.format(message, args));
  128.           }

  129.         return object;
  130.       }

  131.     /*******************************************************************************************************************
  132.      *
  133.      * Throws the {@code NotFoundException} when the passed collection is {@code null} or empty. The method returns the
  134.      * collection itself, so it can be used with fluent interfaces.
  135.      *
  136.      * @param  <T>                the type of collection items
  137.      * @param  collection         the collection to be tested
  138.      * @param  message            the error message to be thrown
  139.      * @return                    the collection
  140.      * @throws NotFoundException  if the collection is null or empty
  141.      *
  142.      ******************************************************************************************************************/
  143.     @Nonnull // needed for binary backward compatibility (this method interprets % in message in verbatim mode)
  144.     public static <T extends Collection<?>> T throwWhenEmpty (@Nullable final T collection,
  145.                                                               @Nonnull final String message)
  146.       throws NotFoundException
  147.       {
  148.         if ((collection == null) || collection.isEmpty())
  149.           {
  150.             throw new NotFoundException(message);
  151.           }

  152.         return collection;
  153.       }

  154.     /*******************************************************************************************************************
  155.      *
  156.      * Throws the {@code NotFoundException} when the passed collection is {@code null} or empty. The method returns the
  157.      * collection itself, so it can be used with fluent interfaces.
  158.      *
  159.      * @param  <T>                the type of collection items
  160.      * @param  collection         the collection to be tested
  161.      * @param  message            the error message to be thrown (formatted as in {@link String#format}
  162.      * @param  args               the arguments to format the error message
  163.      * @return                    the collection
  164.      * @throws NotFoundException  if the collection is null or empty
  165.      *
  166.      ******************************************************************************************************************/
  167.     @Nonnull
  168.     public static <T extends Collection<?>> T throwWhenEmpty (@Nullable final T collection,
  169.                                                               @Nonnull final String message,
  170.                                                               @Nonnull final Object... args)
  171.       throws NotFoundException
  172.       {
  173.         if ((collection == null) || collection.isEmpty())
  174.           {
  175.             throw new NotFoundException(String.format(message, args));
  176.           }

  177.         return collection;
  178.       }
  179.   }