/*--  $Id: Verifier.java,v 1.55 2007/11/10 05:28:59 jhunter Exp $ Copyright (C) 2000-2007 Jason Hunter & Brett McLaughlin. All rights reserved.  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:  1. Redistributions of source code must retain the above copyright    notice, this list of conditions, and the following disclaimer.  2. Redistributions in binary form must reproduce the above copyright    notice, this list of conditions, and the disclaimer that follows     these conditions in the documentation and/or other materials     provided with the distribution. 3. The name "JDOM" must not be used to endorse or promote products    derived from this software without prior written permission.  For    written permission, please contact <request_AT_jdom_DOT_org>.  4. Products derived from this software may not be called "JDOM", nor    may "JDOM" appear in their name, without prior written permission    from the JDOM Project Management <request_AT_jdom_DOT_org>.  In addition, we request (but do not require) that you include in the  end-user documentation provided with the redistribution and/or in the  software itself an acknowledgement equivalent to the following:     "This product includes software developed by the      JDOM Project (http://www.jdom.org/)." Alternatively, the acknowledgment may be graphical using the logos  available at http://www.jdom.org/images/logos. THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This software consists of voluntary contributions made by many  individuals on behalf of the JDOM Project and was originally  created by Jason Hunter <jhunter_AT_jdom_DOT_org> and Brett McLaughlin <brett_AT_jdom_DOT_org>.  For more information on the JDOM Project, please see <http://www.jdom.org/>.  */package org.jdom;import java.util.*;/** * A utility class to handle well-formedness checks on names, data, and other * verification tasks for JDOM. The class is final and may not be subclassed. * * @version $Revision: 1.55 $, $Date: 2007/11/10 05:28:59 $ * @author  Brett McLaughlin * @author  Elliotte Rusty Harold * @author  Jason Hunter * @author  Bradley S. Huffman */final public class Verifier {    private static final String CVS_ID =       "@(#) $RCSfile: Verifier.java,v $ $Revision: 1.55 $ $Date: 2007/11/10 05:28:59 $ $Name: jdom_1_1 $";    /**     * Ensure instantation cannot occur.     */    private Verifier() { }    /**     * This will check the supplied name to see if it is legal for use as     * a JDOM <code>{@link Element}</code> name.     *     * @param name <code>String</code> name to check.     * @return <code>String</code> reason name is illegal, or     *         <code>null</code> if name is OK.     */    public static String checkElementName(String name) {        // Check basic XML name rules first        String reason;        if ((reason = checkXMLName(name)) != null) {            return reason;        }        // No colons allowed, since elements handle this internally        if (name.indexOf(":") != -1) {            return "Element names cannot contain colons";        }        // If we got here, everything is OK        return null;    }    /**     * This will check the supplied name to see if it is legal for use as     * a JDOM <code>{@link Attribute}</code> name.     *     * @param name <code>String</code> name to check.     * @return <code>String</code> reason name is illegal, or     *         <code>null</code> if name is OK.     */    public static String checkAttributeName(String name) {        // Check basic XML name rules first        String reason;        if ((reason = checkXMLName(name)) != null) {            return reason;        }        // No colons are allowed, since attributes handle this internally        if (name.indexOf(":") != -1) {            return "Attribute names cannot contain colons";        }        // Attribute names may not be xmlns since we do this internally too        if (name.equals("xmlns")) {            return "An Attribute name may not be \"xmlns\"; " +                   "use the Namespace class to manage namespaces";        }        // If we got here, everything is OK        return null;    }        /**     * This will check the supplied string to see if it only contains     * characters allowed by the XML 1.0 specification. The C0 controls     * (e.g. null, vertical tab, formfeed, etc.) are specifically excluded     * except for carriage return, linefeed, and the horizontal tab.     * Surrogates are also excluded.      * <p>     * This method is useful for checking element content and attribute     * values. Note that characters      * like " and &lt; are allowed in attribute values and element content.      * They will simply be escaped as &quot; or &lt;      * when the value is serialized.      * </p>     *     * @param text <code>String</code> value to check.     * @return <code>String</code> reason name is illegal, or     *         <code>null</code> if name is OK.     */    public static String checkCharacterData(String text) {        if (text == null) {            return "A null is not a legal XML value";        }        // Do check        for (int i = 0, len = text.length(); i<len; i++) {            int ch = text.charAt(i);                        // Check if high part of a surrogate pair            if (ch >= 0xD800 && ch <= 0xDBFF) {                // Check if next char is the low-surrogate                i++;                if (i < len) {                    char low = text.charAt(i);                    if (low < 0xDC00 || low > 0xDFFF) {                        return "Illegal Surrogate Pair";                    }                    // It's a good pair, calculate the true value of                    // the character to then fall thru to isXMLCharacter                    ch = 0x10000 + (ch - 0xD800) * 0x400 + (low - 0xDC00);                }                else {                    return "Surrogate Pair Truncated";                }            }            if (!isXMLCharacter(ch)) {                // Likely this character can't be easily displayed                // because it's a control so we use it'd hexadecimal                 // representation in the reason.                return ("0x" + Integer.toHexString(ch) +                        " is not a legal XML character");            }        }        // If we got here, everything is OK        return null;    }    /**     * This will check the supplied data to see if it is legal for use as     * JDOM <code>{@link CDATA}</code>.     *     * @param data <code>String</code> data to check.     * @return <code>String</code> reason data is illegal, or     *         <code>null</code> is name is OK.     */    public static String checkCDATASection(String data) {        String reason = null;        if ((reason = checkCharacterData(data)) != null) {            return reason;        }        if (data.indexOf("]]>") != -1) {            return "CDATA cannot internally contain a CDATA ending " +                   "delimiter (]]>)";        }        // If we got here, everything is OK        return null;    }    /**     * This will check the supplied name to see if it is legal for use as     * a JDOM <code>{@link Namespace}</code> prefix.     *     * @param prefix <code>String</code> prefix to check.     * @return <code>String</code> reason name is illegal, or     *         <code>null</code> if name is OK.     */    public static String checkNamespacePrefix(String prefix) {        // Manually do rules, since URIs can be null or empty        if ((prefix == null) || (prefix.equals(""))) {            return null;        }        // Cannot start with a number        char first = prefix.charAt(0);        if (isXMLDigit(first)) {            return "Namespace prefixes cannot begin with a number";        }        // Cannot start with a $        if (first == '$') {            return "Namespace prefixes cannot begin with a dollar sign ($)";        }        // Cannot start with a -        if (first == '-') {            return "Namespace prefixes cannot begin with a hyphen (-)";        }        // Cannot start with a .        if (first == '.') {            return "Namespace prefixes cannot begin with a period (.)";        }        // Cannot start with "xml" in any character case        if (prefix.toLowerCase().startsWith("xml")) {            return "Namespace prefixes cannot begin with " +                   "\"xml\" in any combination of case";        }        // Ensure legal content        for (int i=0, len = prefix.length(); i<len; i++) {            char c = prefix.charAt(i);            if (!isXMLNameCharacter(c)) {                return "Namespace prefixes cannot contain the character \"" +                        c + "\"";            }        }        // No colons allowed        if (prefix.indexOf(":") != -1) {            return "Namespace prefixes cannot contain colons";        }        // If we got here, everything is OK        return null;    }    /**     * This will check the supplied name to see if it is legal for use as     * a JDOM <code>{@link Namespace}</code> URI.     *     * @param uri <code>String</code> URI to check.     * @return <code>String</code> reason name is illegal, or     *         <code>null</code> if name is OK.     */    public static String checkNamespaceURI(String uri) {        // Manually do rules, since URIs can be null or empty        if ((uri == null) || (uri.equals(""))) {            return null;        }        // Cannot start with a number        char first = uri.charAt(0);        if (Character.isDigit(first)) {            return "Namespace URIs cannot begin with a number";        }        // Cannot start with a $        if (first == '$') {            return "Namespace URIs cannot begin with a dollar sign ($)";        }        // Cannot start with a -        if (first == '-') {            return "Namespace URIs cannot begin with a hyphen (-)";        }        // If we got here, everything is OK        return null;    }    /**     * Check if two namespaces collide.     *     * @param namespace <code>Namespace</code> to check.     * @param other <code>Namespace</code> to check against.     * @return <code>String</code> reason for collision, or     *         <code>null</code> if no collision.