001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     * 
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.lang;
018    
019    import java.util.Arrays;
020    
021    /**
022     * <p>Thrown to indicate an incomplete argument to a method.
023     * This exception supplements the standard <code>IllegalArgumentException</code>
024     * by providing a more semantically rich description of the problem.</p>
025     * 
026     * <p><code>IncompleteArgumentException</code> represents the case where a method takes
027     * in a parameter that has a number of properties, some of which have not been set.
028     * A case might be a search requirements bean that must have three properties set
029     * in order for the method to run, but only one is actually set.
030     * This exception would be used in place of
031     * <code>IllegalArgumentException</code>, yet it still extends it.</p>
032     * 
033     * <pre>
034     * public void foo(PersonSearcher search) {
035     *   if (search.getSurname() == null ||
036     *       search.getForename() == null ||
037     *       search.getSex() == null) {
038     *     throw new IncompleteArgumentException("search");
039     *   }
040     *   // do something with the searcher
041     * }
042     * </pre>
043     * 
044     * @author Matthew Hawthorne
045     * @since 2.0
046     * @version $Id: IncompleteArgumentException.java 437554 2006-08-28 06:21:41Z bayard $
047     */
048    public class IncompleteArgumentException extends IllegalArgumentException {
049    
050        /**
051         * Required for serialization support.
052         * 
053         * @see java.io.Serializable
054         */
055        private static final long serialVersionUID = 4954193403612068178L;
056    
057        /**
058         * <p>Instantiates with the specified description.</p>
059         * 
060         * @param argName  a description of the incomplete argument
061         */
062        public IncompleteArgumentException(String argName) {
063            super(argName + " is incomplete.");
064        }
065    
066        /**
067         * <p>Instantiates with the specified description.</p>
068         * 
069         * @param argName  a description of the incomplete argument
070         * @param items  an array describing the arguments missing
071         */
072        public IncompleteArgumentException(String argName, String[] items) {
073            super(
074                argName
075                    + " is missing the following items: "
076                    + safeArrayToString(items));
077        }
078    
079        /**
080         * <p>Converts an array to a string without throwing an exception.</p>
081         * 
082         * @param array  an array
083         * @return the array as a string
084         */
085        private static final String safeArrayToString(Object[] array) {
086            return array == null ? null : Arrays.asList(array).toString();
087        }
088    
089    }