1 /*
2 * *************************************************************************************************************************************************************
3 *
4 * TheseFoolishThings: Miscellaneous utilities
5 * http://tidalwave.it/projects/thesefoolishthings
6 *
7 * Copyright (C) 2009 - 2025 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
28 import jakarta.annotation.Nonnull;
29 import jakarta.annotation.Nullable;
30 import java.util.Collection;
31
32 /***************************************************************************************************************************************************************
33 *
34 * Notifies that a searched object couldn't be found.
35 *
36 * @author Fabrizio Giudici
37 * @it.tidalwave.javadoc.stable
38 *
39 **************************************************************************************************************************************************************/
40 public class NotFoundException extends Exception
41 {
42 private static final long serialVersionUID = 3453465498093L;
43
44 /***********************************************************************************************************************************************************
45 * Creates an empty exception.
46 **********************************************************************************************************************************************************/
47 public NotFoundException()
48 {
49 }
50
51 /***********************************************************************************************************************************************************
52 * Creates an exception with a message.
53 *
54 * @param message the message
55 **********************************************************************************************************************************************************/
56 public NotFoundException (@Nonnull final String message)
57 {
58 super(message);
59 }
60
61 /***********************************************************************************************************************************************************
62 * Creates an exception with a cause.
63 *
64 * @param cause the cause
65 **********************************************************************************************************************************************************/
66 public NotFoundException (@Nonnull final Throwable cause)
67 {
68 super(cause);
69 }
70
71 /***********************************************************************************************************************************************************
72 * Creates an exception with a message and a cause.
73 *
74 * @param message the message
75 * @param cause the cause
76 **********************************************************************************************************************************************************/
77 public NotFoundException (@Nonnull final String message, @Nonnull final Throwable cause)
78 {
79 super(message, cause);
80 }
81
82 /***********************************************************************************************************************************************************
83 * Throws the {@code NotFoundException} when the passed object is {@code null}. The method returns the object
84 * itself, so it can be used with fluent interfaces.
85 *
86 * @param <T> the type of the object
87 * @param object the object to be tested
88 * @param message the error message to be thrown
89 * @return the object
90 * @throws NotFoundException if the object is null
91 **********************************************************************************************************************************************************/
92 @Nonnull // needed for binary backward compatibility (this method interprets % in message in verbatim mode)
93 public static <T> T throwWhenNull (@Nullable final T object, @Nonnull final String message)
94 throws NotFoundException
95 {
96 if (object == null)
97 {
98 throw new NotFoundException(message);
99 }
100
101 return object;
102 }
103
104 /***********************************************************************************************************************************************************
105 * Throws the {@code NotFoundException} when the passed object is {@code null}. The method returns the object
106 * itself, so it can be used with fluent interfaces.
107 *
108 * @param <T> the type of the object
109 * @param object the object to be tested
110 * @param message the error message to be thrown (formatted as in {@link String#format}
111 * @param args the arguments to format the error message
112 * @return the object
113 * @throws NotFoundException if the object is null
114 **********************************************************************************************************************************************************/
115 @Nonnull
116 public static <T> T throwWhenNull (@Nullable final T object,
117 @Nonnull final String message,
118 @Nonnull final Object... args)
119 throws NotFoundException
120 {
121 if (object == null)
122 {
123 throw new NotFoundException(String.format(message, args));
124 }
125
126 return object;
127 }
128
129 /***********************************************************************************************************************************************************
130 * Throws the {@code NotFoundException} when the passed collection is {@code null} or empty. The method returns the
131 * collection itself, so it can be used with fluent interfaces.
132 *
133 * @param <T> the type of collection items
134 * @param collection the collection to be tested
135 * @param message the error message to be thrown
136 * @return the collection
137 * @throws NotFoundException if the collection is null or empty
138 **********************************************************************************************************************************************************/
139 @Nonnull // needed for binary backward compatibility (this method interprets % in message in verbatim mode)
140 public static <T extends Collection<?>> T throwWhenEmpty (@Nullable final T collection,
141 @Nonnull final String message)
142 throws NotFoundException
143 {
144 if ((collection == null) || collection.isEmpty())
145 {
146 throw new NotFoundException(message);
147 }
148
149 return collection;
150 }
151
152 /***********************************************************************************************************************************************************
153 * Throws the {@code NotFoundException} when the passed collection is {@code null} or empty. The method returns the
154 * collection itself, so it can be used with fluent interfaces.
155 *
156 * @param <T> the type of collection items
157 * @param collection the collection to be tested
158 * @param message the error message to be thrown (formatted as in {@link String#format}
159 * @param args the arguments to format the error message
160 * @return the collection
161 * @throws NotFoundException if the collection is null or empty
162 **********************************************************************************************************************************************************/
163 @Nonnull
164 public static <T extends Collection<?>> T throwWhenEmpty (@Nullable final T collection,
165 @Nonnull final String message,
166 @Nonnull final Object... args)
167 throws NotFoundException
168 {
169 if ((collection == null) || collection.isEmpty())
170 {
171 throw new NotFoundException(String.format(message, args));
172 }
173
174 return collection;
175 }
176 }