    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    }