1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang;
18
19 import java.util.Arrays;
20
21 /**
22 * <p>Thrown to indicate an incomplete argument to a method.
23 * This exception supplements the standard <code>IllegalArgumentException</code>
24 * by providing a more semantically rich description of the problem.</p>
25 *
26 * <p><code>IncompleteArgumentException</code> represents the case where a method takes
27 * in a parameter that has a number of properties, some of which have not been set.
28 * A case might be a search requirements bean that must have three properties set
29 * in order for the method to run, but only one is actually set.
30 * This exception would be used in place of
31 * <code>IllegalArgumentException</code>, yet it still extends it.</p>
32 *
33 * <pre>
34 * public void foo(PersonSearcher search) {
35 * if (search.getSurname() == null ||
36 * search.getForename() == null ||
37 * search.getSex() == null) {
38 * throw new IncompleteArgumentException("search");
39 * }
40 * // do something with the searcher
41 * }
42 * </pre>
43 *
44 * @author Matthew Hawthorne
45 * @since 2.0
46 * @version $Id: IncompleteArgumentException.java 437554 2006-08-28 06:21:41Z bayard $
47 */
48 public class IncompleteArgumentException extends IllegalArgumentException {
49
50 /**
51 * Required for serialization support.
52 *
53 * @see java.io.Serializable
54 */
55 private static final long serialVersionUID = 4954193403612068178L;
56
57 /**
58 * <p>Instantiates with the specified description.</p>
59 *
60 * @param argName a description of the incomplete argument
61 */
62 public IncompleteArgumentException(String argName) {
63 super(argName + " is incomplete.");
64 }
65
66 /**
67 * <p>Instantiates with the specified description.</p>
68 *
69 * @param argName a description of the incomplete argument
70 * @param items an array describing the arguments missing
71 */
72 public IncompleteArgumentException(String argName, String[] items) {
73 super(
74 argName
75 + " is missing the following items: "
76 + safeArrayToString(items));
77 }
78
79 /**
80 * <p>Converts an array to a string without throwing an exception.</p>
81 *
82 * @param array an array
83 * @return the array as a string
84 */
85 private static final String safeArrayToString(Object[] array) {
86 return array == null ? null : Arrays.asList(array).toString();
87 }
88
89 }