verifier.java

一个用于搜索本地文件内容的小型搜索引擎

/*-- 

 $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.