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 java.util.regex.Pattern;
19
20 import javax.annotation.Nullable;
21
22 /**
23 * Thrown to indicate that a method has been passed a sequence of {@code char} values as argument that does not matches
24 * against the specified pattern. For example, if a method needs a string with a exactly four alphanumeric characters
25 * and is passed with a five characters long string.
26 *
27 * @author André Rouél
28 * @author Dominik Seichter
29 */
30 public class IllegalPatternArgumentException extends RuntimeException {
31
32 private static final long serialVersionUID = -6741481389295600427L;
33
34 /**
35 * Default message to indicate that the a given argument must match against the specified pattern.
36 */
37 protected static final String DEFAULT_MESSAGE = "The passed argument must match against the specified pattern: %s";
38
39 /**
40 * Message to indicate that the the given argument with <em>name</em> must match against the specified pattern.
41 */
42 protected static final String MESSAGE_WITH_NAME = "The passed argument '%s' must match against the specified pattern: %s";
43
44 /**
45 * Placeholder for an unset pattern to format a message human readable
46 */
47 protected static final String NO_PATTERN_PLACEHOLDER = "[not set]";
48
49 /**
50 * Determines the message to be used, depending on the passed argument name. If if the given argument name is
51 * {@code null} or empty {@code DEFAULT_MESSAGE} will be returned, otherwise a formatted {@code MESSAGE_WITH_NAME}
52 * with the passed name and pattern which the argument must match.
53 *
54 * @param argumentName
55 * the name of the passed argument
56 * @param pattern
57 * Pattern, that a string or character sequence should correspond to
58 * @return {@code DEFAULT_MESSAGE} if the given argument name is {@code null} or empty, otherwise a formatted
59 * {@code MESSAGE_WITH_NAME}
60 */
61 private static String determineMessage(@Nullable final String argumentName, @Nullable final Pattern pattern) {
62 return argumentName != null && !argumentName.isEmpty() ? format(argumentName, pattern) : format(pattern);
63 }
64
65 /**
66 * Returns the formatted string {@link IllegalPatternArgumentException#DEFAULT_MESSAGE} with the given pattern which
67 * the argument must match.
68 *
69 * @param argumentName
70 * the name of the passed argument
71 * @param pattern
72 * Pattern, that a string or character sequence should correspond to
73 * @return a formatted string of message with the given argument name
74 */
75 private static String format(@Nullable final Pattern pattern) {
76 return String.format(DEFAULT_MESSAGE, patternToString(pattern));
77 }
78
79 /**
80 * Returns the formatted string {@link IllegalPatternArgumentException#MESSAGE_WITH_NAME} with the given
81 * {@code argumentName} and pattern which the argument must match.
82 *
83 * @param argumentName
84 * the name of the passed argument
85 * @param pattern
86 * Pattern, that a string or character sequence should correspond to
87 * @return a formatted string of message with the given argument name
88 */
89 private static String format(@Nullable final String argumentName, @Nullable final Pattern pattern) {
90 final String p = patternToString(pattern);
91 return String.format(MESSAGE_WITH_NAME, argumentName, p);
92 }
93
94 /**
95 * Converts a {@link Pattern} to a string representation.
96 *
97 * @param pattern
98 * Pattern
99 * @return string representation of a pattern
100 */
101 private static String patternToString(@Nullable final Pattern pattern) {
102 return pattern != null ? pattern.pattern() + " (flags: " + pattern.flags() + ")" : NO_PATTERN_PLACEHOLDER;
103 }
104
105 /**
106 * Constructs an {@code IllegalNullArgumentException} with the default message
107 * {@link IllegalPatternArgumentException#DEFAULT_MESSAGE} including the pattern which the argument must match.
108 *
109 * @param pattern
110 * Pattern, that a string or character sequence should correspond to
111 */
112 public IllegalPatternArgumentException(@Nullable final Pattern pattern) {
113 super(format(pattern));
114 }
115
116 /**
117 * Constructs a new exception with the default message {@link IllegalPatternArgumentException#DEFAULT_MESSAGE}
118 * including the pattern which the argument must match.
119 *
120 * @param pattern
121 * Pattern, that a string or character sequence should correspond to
122 * @param cause
123 * the cause (which is saved for later retrieval by the {@link Throwable#getCause()} method). (A
124 * {@code null} value is permitted, and indicates that the cause is nonexistent or unknown.)
125 */
126 public IllegalPatternArgumentException(@Nullable final Pattern pattern, @Nullable final Throwable cause) {
127 super(format(pattern), cause);
128 }
129
130 /**
131 * Constructs an {@code IllegalNullArgumentException} with the message
132 * {@link IllegalPatternArgumentException#MESSAGE_WITH_NAME} including the given name of the argument as string
133 * representation and pattern which the argument must match.
134 *
135 * @param argumentName
136 * the name of the passed argument
137 * @param pattern
138 * Pattern, that a string or character sequence should correspond to
139 */
140 public IllegalPatternArgumentException(@Nullable final String argumentName, @Nullable final Pattern pattern) {
141 super(determineMessage(argumentName, pattern));
142 }
143
144 /**
145 * Constructs a new exception with the message {@link IllegalPatternArgumentException#MESSAGE_WITH_NAME} including
146 * the given name as string representation, the pattern which the argument must match and cause.
147 *
148 * @param argumentName
149 * the name of the passed argument
150 * @param pattern
151 * Pattern, that a string or character sequence should correspond to
152 * @param cause
153 * the cause (which is saved for later retrieval by the {@link Throwable#getCause()} method). (A
154 * {@code null} value is permitted, and indicates that the cause is nonexistent or unknown.)
155 */
156 public IllegalPatternArgumentException(@Nullable final String argumentName, @Nullable final Pattern pattern,
157 @Nullable final Throwable cause) {
158 super(determineMessage(argumentName, pattern), cause);
159 }
160
161 }