1.1 --- a/openide.util/apichanges.xml Thu Dec 07 18:57:14 2006 +0000
1.2 +++ b/openide.util/apichanges.xml Fri Dec 08 14:38:16 2006 +0000
1.3 @@ -27,6 +27,23 @@
1.4 </apidefs>
1.5 <changes>
1.6
1.7 + <change id="Parameters">
1.8 + <api name="util"/>
1.9 + <summary>Added <code>Parameters</code></summary>
1.10 + <version major="7" minor="6"/>
1.11 + <date day="8" month="12" year="2006"/>
1.12 + <author login="abadea"/>
1.13 + <compatibility addition="yes"/>
1.14 + <description>
1.15 + <p>
1.16 + Added a <code>Parameters</code> class for checking the
1.17 + values of method parameters.
1.18 + </p>
1.19 + </description>
1.20 + <class package="org.openide.util" name="Parameters"/>
1.21 + <issue number="89768"/>
1.22 + </change>
1.23 +
1.24 <change id="NbCollections.iterable">
1.25 <api name="util"/>
1.26 <summary>Added <code>NbCollections.iterable(...)</code> methods</summary>
2.1 --- a/openide.util/nbproject/project.properties Thu Dec 07 18:57:14 2006 +0000
2.2 +++ b/openide.util/nbproject/project.properties Fri Dec 08 14:38:16 2006 +0000
2.3 @@ -19,7 +19,7 @@
2.4 javac.source=1.5
2.5 module.jar.dir=lib
2.6
2.7 -spec.version.base=7.5.0
2.8 +spec.version.base=7.6.0
2.9
2.10 # For XMLSerializer, needed for XMLUtil.write to work w/ namespaces under JDK 1.4:
2.11
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/openide.util/src/org/openide/util/Parameters.java Fri Dec 08 14:38:16 2006 +0000
3.3 @@ -0,0 +1,132 @@
3.4 +/*
3.5 + * The contents of this file are subject to the terms of the Common Development
3.6 + * and Distribution License (the License). You may not use this file except in
3.7 + * compliance with the License.
3.8 + *
3.9 + * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
3.10 + * or http://www.netbeans.org/cddl.txt.
3.11 + *
3.12 + * When distributing Covered Code, include this CDDL Header Notice in each file
3.13 + * and include the License file at http://www.netbeans.org/cddl.txt.
3.14 + * If applicable, add the following below the CDDL Header, with the fields
3.15 + * enclosed by brackets [] replaced by your own identifying information:
3.16 + * "Portions Copyrighted [year] [name of copyright owner]"
3.17 + *
3.18 + * The Original Software is NetBeans. The Initial Developer of the Original
3.19 + * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
3.20 + * Microsystems, Inc. All Rights Reserved.
3.21 + */
3.22 +
3.23 +package org.openide.util;
3.24 +
3.25 +/**
3.26 + * Utilities for checking the values of method parameters.
3.27 + *
3.28 + * Methods in this class generally take the name of
3.29 + * the parameter to check and its value and throw exceptions
3.30 + * with messages according to the method name or just return. For example,
3.31 + * if you have a <code>myMethod()</code> method taking a <code>myParam</code>
3.32 + * parameter whose value must be a Java identifier, you usually check that
3.33 + * by doing:
3.34 + *
3.35 + * <pre>
3.36 + * public void myMethod(String myParam) {
3.37 + * if (!Utilities.isJavaIdentifier(myParam)) {
3.38 + * throw new IllegalArgumentException("The myParam parameter is not a valid Java identifier");
3.39 + * }
3.40 + * }
3.41 + * </pre>
3.42 + *
3.43 + * Using this class you can do the same is a simpler way:
3.44 + *
3.45 + * <pre>
3.46 + * public void myMethod(String myParam) {
3.47 + * Parameters.javaIdentifier("myParam", myParam);
3.48 + * }
3.49 + * </pre>
3.50 + *
3.51 + * @author Andrei Badea
3.52 + * @since org.openide.util 7.6
3.53 + */
3.54 +public class Parameters {
3.55 +
3.56 + private Parameters() {}
3.57 +
3.58 + /**
3.59 + * Asserts the parameter value is not <code>null</code>.
3.60 + *
3.61 + * @param name the parameter name.
3.62 + * @param value the parameter value.
3.63 + * @throws NullPointerException if the parameter value is <code>null</code>.
3.64 + */
3.65 + public static void notNull(CharSequence name, Object value) {
3.66 + if (value == null) {
3.67 + throw new NullPointerException("The " + name + " parameter cannot be null"); // NOI18N
3.68 + }
3.69 + }
3.70 +
3.71 + /**
3.72 + * Asserts the parameter value is neither <code>null</code> nor an empty
3.73 + * character sequence.
3.74 + *
3.75 + * @param name the parameter name.
3.76 + * @param value the parameter value.
3.77 + * @throws NullPointerException if the parameter value is <code>null</code>.
3.78 + * @throws IllegalArgumentException if the parameter value is an empty
3.79 + * character sequence.
3.80 + */
3.81 + public static void notEmpty(CharSequence name, CharSequence value) {
3.82 + notNull(name, value);
3.83 + if (value.length() == 0) {
3.84 + throw new IllegalArgumentException("The " + name + " parameter cannot be an empty character sequence"); // NOI18N
3.85 + }
3.86 + }
3.87 +
3.88 + /**
3.89 + * Asserts the parameter value is not <code>null</code> and it contains
3.90 + * at least one non-whitespace character. Whitespace is defined as by
3.91 + * {@link String#trim}.
3.92 + *
3.93 + * @param name the parameter name.
3.94 + * @param value the parameter value.
3.95 + * @throws NullPointerException if the parameter value is <code>null</code>.
3.96 + * @throws IllegalArgumentException if the parameter value does not
3.97 + * contain at least one non-whitespace character.
3.98 + */
3.99 + public static void notWhitespace(CharSequence name, CharSequence value) {
3.100 + notNull(name, value);
3.101 + if (value.toString().trim().length() == 0) {
3.102 + throw new IllegalArgumentException("The " + name + " parameter must contain at least one non-whitespace character"); // NOI18N
3.103 + }
3.104 + }
3.105 +
3.106 + /**
3.107 + * Asserts the parameter value is not <code>null</code> and it is
3.108 + * a Java identifier.
3.109 + *
3.110 + * @param name the parameter name.
3.111 + * @param value the parameter value.
3.112 + * @throws NullPointerException if the parameter value is <code>null</code>.
3.113 + * @throws IllegalArgumentException if the parameter value is not
3.114 + * a Java identifier.
3.115 + */
3.116 + public static void javaIdentifier(CharSequence name, CharSequence value) {
3.117 + notNull(name, value);
3.118 + javaIdentifierOrNull(name, value);
3.119 + }
3.120 +
3.121 + /**
3.122 + * Asserts the parameter value is either <code>null</code> or a Java
3.123 + * identifier.
3.124 + *
3.125 + * @param name the parameter name.
3.126 + * @param value the parameter value.
3.127 + * @throws IllegalArgumentException if the parameter value is neither
3.128 + * <code>null</code> nor a Java identifier.
3.129 + */
3.130 + public static void javaIdentifierOrNull(CharSequence name, CharSequence value) {
3.131 + if (value != null && !Utilities.isJavaIdentifier(value.toString())) {
3.132 + throw new IllegalArgumentException("The " + name + " parameter ('" + value + "') is not a valid Java identifier"); // NOI18N
3.133 + }
3.134 + }
3.135 +}
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/openide.util/test/unit/src/org/openide/util/ParametersTest.java Fri Dec 08 14:38:16 2006 +0000
4.3 @@ -0,0 +1,100 @@
4.4 +/*
4.5 + * The contents of this file are subject to the terms of the Common Development
4.6 + * and Distribution License (the License). You may not use this file except in
4.7 + * compliance with the License.
4.8 + *
4.9 + * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
4.10 + * or http://www.netbeans.org/cddl.txt.
4.11 + *
4.12 + * When distributing Covered Code, include this CDDL Header Notice in each file
4.13 + * and include the License file at http://www.netbeans.org/cddl.txt.
4.14 + * If applicable, add the following below the CDDL Header, with the fields
4.15 + * enclosed by brackets [] replaced by your own identifying information:
4.16 + * "Portions Copyrighted [year] [name of copyright owner]"
4.17 + *
4.18 + * The Original Software is NetBeans. The Initial Developer of the Original
4.19 + * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
4.20 + * Microsystems, Inc. All Rights Reserved.
4.21 + */
4.22 +
4.23 +package org.openide.util;
4.24 +
4.25 +import java.lang.reflect.InvocationTargetException;
4.26 +import java.lang.reflect.Method;
4.27 +import junit.framework.TestCase;
4.28 +
4.29 +/**
4.30 + *
4.31 + * @author Andrei Badea
4.32 + */
4.33 +public class ParametersTest extends TestCase {
4.34 +
4.35 + public ParametersTest(String testName) {
4.36 + super(testName);
4.37 + }
4.38 +
4.39 + public void testNotNull() throws Exception {
4.40 + assertNPEOnNull(Parameters.class.getMethod("notNull", CharSequence.class, Object.class));
4.41 + Parameters.notNull("param", "");
4.42 + }
4.43 +
4.44 + public void testNotEmpty() throws Exception {
4.45 + assertNPEOnNull(Parameters.class.getMethod("notEmpty", CharSequence.class, CharSequence.class));
4.46 + try {
4.47 + Parameters.notEmpty("param", "");
4.48 + fail("Should have thrown IAE");
4.49 + } catch (IllegalArgumentException e) {}
4.50 + Parameters.notEmpty("param", "foo");
4.51 + }
4.52 +
4.53 + public void testNotWhitespace() throws Exception {
4.54 + assertNPEOnNull(Parameters.class.getMethod("notWhitespace", CharSequence.class, CharSequence.class));
4.55 + try {
4.56 + Parameters.notWhitespace("param", "");
4.57 + fail("Should have thrown IAE");
4.58 + } catch (IllegalArgumentException e) {}
4.59 + try {
4.60 + Parameters.notWhitespace("param", " ");
4.61 + fail("Should have thrown IAE");
4.62 + } catch (IllegalArgumentException e) {}
4.63 + Parameters.notWhitespace("param", " foo ");
4.64 + }
4.65 +
4.66 + public void testJavaIdentifier() throws Exception {
4.67 + assertNPEOnNull(Parameters.class.getMethod("javaIdentifier", CharSequence.class, CharSequence.class));
4.68 + try {
4.69 + Parameters.javaIdentifier("param", "");
4.70 + fail("Should have thrown IAE");
4.71 + } catch (IllegalArgumentException e) {}
4.72 + try {
4.73 + Parameters.javaIdentifier("param", "foo#Method");
4.74 + fail("Should have thrown IAE");
4.75 + } catch (IllegalArgumentException e) {}
4.76 + Parameters.javaIdentifier("param", "fooMethod");
4.77 + }
4.78 +
4.79 + public void testJavaIdentifierOrNull() throws Exception {
4.80 + try {
4.81 + Parameters.javaIdentifierOrNull("param", "");
4.82 + fail("Should have thrown IAE");
4.83 + } catch (IllegalArgumentException e) {}
4.84 + try {
4.85 + Parameters.javaIdentifierOrNull("param", "foo#Method");
4.86 + fail("Should have thrown IAE");
4.87 + } catch (IllegalArgumentException e) {}
4.88 + Parameters.javaIdentifierOrNull("param", null);
4.89 + Parameters.javaIdentifierOrNull("param", "fooMethod");
4.90 + }
4.91 +
4.92 + private void assertNPEOnNull(Method method) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
4.93 + try {
4.94 + method.invoke(null, "param", null);
4.95 + fail("Should have thrown NPE");
4.96 + } catch (InvocationTargetException e) {
4.97 + Throwable target = e.getTargetException();
4.98 + assertEquals(NullPointerException.class, target.getClass());
4.99 + // ensure the NPE was thrown by us, not by the VM
4.100 + assertEquals("The param parameter cannot be null", target.getMessage());
4.101 + }
4.102 + }
4.103 +}