javax.xml.xquery.XQException Maven / Gradle / Ivy

Go to download
/*
 * Copyright � 2003, 2004, 2005, 2006, 2007, 2008 Oracle.  All rights reserved.
 */

package javax.xml.xquery;

import java.lang.Exception;

/**
 * An exception that provides information on XQJ, XQuery or other errors
 * reported by an XQJ implementation.
 * 

 * 

 * Each XQException provides several kinds of information:
 * 
 * a string describing the error. This is used as the Java
 * Exception message, available via the method getMessage.
 * the cause of the error. This is used as the Java Exception
 * cause, available via the method getCause.
 * the vendor code identifying the error. Available via the
 * method getVendorCode. Refer to the vendor documentation
 * which specific codes can be returned.
 * a chain of XQException objects. If more than one
 * error occurred the exceptions are referenced via this chain.
 * 
 * 

 * 

 * Note that XQException has a subclass
 * {@link XQQueryException XQQueryException} providing more detailed
 * information about errors that occurred during the processing of a query.
 * An implementation throws a base XQException when an error
 * occurs in the XQJ implementation. Further, implementations are encouraged to
 * use the more detailed XQQueryException in case of an
 * error reported by the XQuery engine.
 * 

 * 

 * It is possible that during the processing of a query that one or more
 * errors could occur, each with their own potential causal relationship.
 * This means that when an XQJ application catches an
 * XQException, there is a possibility that there may be
 * additional XQException objects chained to the original
 * thrown XQException. To access the additional chained
 * XQException objects, an application would recursively
 * invoke getNextException until a null value is
 * returned.
 * 

 * 

 * An XQException may have a causal relationship, which
 * consists of one or more Throwable instances which caused
 * the XQException to be thrown. The application may
 * recursively call the method getCause, until a null
 * value is returned, to navigate the chain of causes.
 */
public class XQException extends Exception {
    private String vendorCode;
    XQException nextException;

    /**
     * Constructs an XQException object with a given message.
     * An optional chain of additional XQException objects may be set
     * subsequently using setNextException.
     *
     * @param message the description of the error. null indicates
     *                that the message string is non existant
     */
    public XQException(String message) {
        super(message);
    }

    /**
     * Constructs an XQException object with a given message
     * and vendor code. An optional chain of additional
     * XQException objects may be set subsequently using
     * setNextException.
     *
     * @param message    the description of the error. null
     *                   indicates that the message string is non existant
     * @param vendorCode a vendor-specific string identifying the error.
     *                   null indicates there is no vendor
     *                   code or it is unknown
     */
    public XQException(String message, String vendorCode) {
        super(message);
        this.vendorCode = vendorCode;
    }

    /**
     * Gets the vendor code associated with this exception or null
     * if none. A vendor code is a vendor-specific string identifying the failure in
     * a computer-comparable manner. For example, "NOCONNECT" if unable to
     * connect or "DIVBYZERO" if division by zero occurred within the XQuery.
     *
     * @return the vendor code string, or null if none available
     */
    public String getVendorCode() {
        return vendorCode;
    }

    /**
     * Returns the next XQException in the chain or
     * null if none.
     *
     * @return the next exception, or null if none
     */
    public XQException getNextException() {
        return nextException;
    }

    /**
     * Adds an XQException to the chain of exceptions.
     *
     * @param next the next exception to be added to the chain
     *             of exceptions
     */
    public void setNextException(XQException next) {
        nextException = next;
    }
}