com.thesett.common.xml.XmlUtilsException Maven / Gradle / Ivy

Go to download
/*
 * Copyright The Sett Ltd, 2005 to 2014.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.thesett.common.xml;

import java.util.Collection;
import java.util.Comparator;
import java.util.PriorityQueue;

import com.thesett.common.error.UserReadableRuntimeException;

/**
 * XmlUtilsException is used to represent a wide variety of XML related exceptions. For example parsing errors, parser
 * unsupported feature errors, validation errors, malformed xml errors and so on. Generally speaking methods in the
 * {@link XmlUtils} class throw this as a convenience exception to capture non-recoverable error conditions.
 *
 * Recoverable conditions have more specific exception types to represent them.
 *
 * 

 * CRC Card Responsibilities  Collaborations
 * 
 Represent an unrecoverable condition when working with XML utility methods.
 * 
 Act as a container for multiple parsing errors.
 * 
 *
 * @author Rupert Smith
 */
public class XmlUtilsException extends UserReadableRuntimeException
{
    /** Holds any parsing errors associated with this exception, sorted by line number. */
    private Collection parsingErrors;

    /**
     * Creates a new xml utils exception.
     *
     * @param message     The exception message.
     * @param cause       The wrapped exception underlying this one.
     * @param key         A key to look up user readable messages with.
     * @param userMessage The user readable message or data string.
     */
    public XmlUtilsException(String message, Throwable cause, String key, String userMessage)
    {
        super(message, cause, key, userMessage);
    }

    /**
     * Associates a parsing error with this exception.
     *
     * @param error The parsing error.
     */
    public void addParsingError(ParsingError error)
    {
        if (parsingErrors == null)
        {
            parsingErrors = new PriorityQueue(1, new ParsingErrorComparator());
        }

        parsingErrors.add(error);
    }

    /**
     * Gets all the parsing errors associated with this exception, in order of the line numbers where they occurred.
     *
     * @return The parsing errors associated with this exception, in order of the line numbers where they occurred.
     */
    public Collection getParsingErrors()
    {
        return parsingErrors;
    }

    /**
     * Compares parsing errors by line number.
     */
    public static class ParsingErrorComparator implements Comparator
    {
        /**
         * Compares two parsing errors by line number.
         *
         * @param  e1 The first parsing error.
         * @param  e2 The second parsing error.
         *
         * @return A negative integer, zero, or a positive integer as the first argument is less than, equal to, or
         *         greater than the second.
         */
        public int compare(ParsingError e1, ParsingError e2)
        {
            int l1 = e1.getLine();
            int l2 = e2.getLine();

            return (l1 == l2) ? 0 : ((l1 < l2) ? -1 : 1);
        }

        /**
         * Checks if another comparator is the same as this one.
         *
         * @param  o The object to compare to.
         *
         * @return true only if the specified object is also a comparator and it imposes the same ordering as
         *         this comparator.
         */
        public boolean equals(Object o)
        {
            return o instanceof ParsingErrorComparator;
        }
    }
}
Responsibilities	Collaborations *
Represent an unrecoverable condition when working with XML utility methods. *
Act as a container for multiple parsing errors. *