1 /*******************************************************************************
2 * Copyright 2013 André Rouél and Dominik Seichter
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 ******************************************************************************/
16 package net.sf.qualitycheck.exception;
17
18 import javax.annotation.Nullable;
19
20 /**
21 * Thrown to indicate that a method has been passed with an array or a collection which contains a {@code null} element.
22 *
23 * @author André Rouél
24 * @author Dominik Seichter
25 */
26 public class IllegalNullElementsException extends RuntimeException {
27
28 private static final long serialVersionUID = -1957077437070375885L;
29
30 /**
31 * Default message to indicate that a given array or {@code Iterable} argument must not contain {@code null}.
32 */
33 protected static final String DEFAULT_MESSAGE = "The passed argument must not contain elements that are null.";
34
35 /**
36 * Message to indicate that the the given array or {@code Iterable} argument with <em>name</em> must not contain
37 * {@code null}.
38 */
39 protected static final String MESSAGE_WITH_NAME = "The passed argument '%s' must not contain elements that are null.";
40
41 /**
42 * Determines the message to be used, depending on the passed argument name. If if the given argument name is
43 * {@code null} or empty {@code DEFAULT_MESSAGE} will be returned, otherwise a formatted {@code MESSAGE_WITH_NAME}
44 * with the passed name.
45 *
46 * @param argumentName
47 * the name of the passed argument
48 * @return {@code DEFAULT_MESSAGE} if the given argument name is {@code null} or empty, otherwise a formatted
49 * {@code MESSAGE_WITH_NAME}
50 */
51 private static String determineMessage(@Nullable final String argumentName) {
52 return argumentName != null && !argumentName.isEmpty() ? format(argumentName) : DEFAULT_MESSAGE;
53 }
54
55 /**
56 * Returns the formatted string {@link IllegalEmptyArgumentException#MESSAGE_WITH_NAME} with the given
57 * {@code argumentName}.
58 *
59 * @param argumentName
60 * the name of the passed argument
61 * @return a formatted string of message with the given argument name
62 */
63 private static String format(@Nullable final String argumentName) {
64 return String.format(MESSAGE_WITH_NAME, argumentName);
65 }
66
67 /**
68 * Constructs an {@code IllegalNullArgumentException} with the default message
69 * {@link IllegalEmptyArgumentException#DEFAULT_MESSAGE}.
70 */
71 public IllegalNullElementsException() {
72 super(DEFAULT_MESSAGE);
73 }
74
75 /**
76 * Constructs an {@code IllegalNullArgumentException} with the message
77 * {@link IllegalEmptyArgumentException#MESSAGE_WITH_NAME} including the given name of the argument as string
78 * representation.
79 *
80 * @param argumentName
81 * the name of the passed argument
82 */
83 public IllegalNullElementsException(@Nullable final String argumentName) {
84 super(determineMessage(argumentName));
85 }
86
87 /**
88 * Constructs a new exception with the message {@link IllegalEmptyArgumentException#MESSAGE_WITH_NAME} including the
89 * given name as string representation and cause.
90 *
91 * @param argumentName
92 * the name of the passed argument
93 * @param cause
94 * the cause (which is saved for later retrieval by the {@link Throwable#getCause()} method). (A
95 * {@code null} value is permitted, and indicates that the cause is nonexistent or unknown.)
96 */
97 public IllegalNullElementsException(@Nullable final String argumentName, @Nullable final Throwable cause) {
98 super(determineMessage(argumentName), cause);
99 }
100
101 /**
102 * Constructs a new exception with the default message {@link IllegalEmptyArgumentException#DEFAULT_MESSAGE}.
103 *
104 * @param cause
105 * the cause (which is saved for later retrieval by the {@link Throwable#getCause()} method). (A
106 * {@code null} value is permitted, and indicates that the cause is nonexistent or unknown.)
107 */
108 public IllegalNullElementsException(@Nullable final Throwable cause) {
109 super(DEFAULT_MESSAGE, cause);
110 }
111
112 }