01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * 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
49: IllegalArgumentException {
50:
51: /**
52: * Required for serialization support.
53: *
54: * @see java.io.Serializable
55: */
56: private static final long serialVersionUID = 4954193403612068178L;
57:
58: /**
59: * <p>Instantiates with the specified description.</p>
60: *
61: * @param argName a description of the incomplete argument
62: */
63: public IncompleteArgumentException(String argName) {
64: super (argName + " is incomplete.");
65: }
66:
67: /**
68: * <p>Instantiates with the specified description.</p>
69: *
70: * @param argName a description of the incomplete argument
71: * @param items an array describing the arguments missing
72: */
73: public IncompleteArgumentException(String argName, String[] items) {
74: super (argName + " is missing the following items: "
75: + safeArrayToString(items));
76: }
77:
78: /**
79: * <p>Converts an array to a string without throwing an exception.</p>
80: *
81: * @param array an array
82: * @return the array as a string
83: */
84: private static final String safeArrayToString(Object[] array) {
85: return array == null ? null : Arrays.asList(array).toString();
86: }
87:
88: }
|