javax.jdo.JDOException Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of javax.jdo Show documentation
The Java Data Objects API (JDO) : a standard interface-based Java model abstraction of persistence, developed by the JCP.
There is a newer version: 3.2.1
Show newest version
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
 */

/*
 * JDOException.java
 *
 */

package javax.jdo;

import javax.jdo.spi.I18NHelper;

/** This is the root of all JDO Exceptions.  It contains an optional detail
 * message, an optional nested Throwable array and an optional failed object.
 * @author Craig Russell
 * @version 1.0.2
 */
public class JDOException extends java.lang.RuntimeException {

	private static final long serialVersionUID = 1950979275859696534L;

    /** This exception was generated because of an exception in the runtime library.
     * @serial the nested Throwable array
     */
    Throwable[] nested;
  
    /** This exception may be the result of incorrect parameters supplied to an API.
     * This is the object from which the user can determine the cause of the problem.
     * @serial the failed Object
     */
    Object failed;

    /**
     * The Internationalization message helper.
     */
    private static I18NHelper msg = I18NHelper.getInstance ("javax.jdo.Bundle"); //NOI18N

    /** 
     * Flag indicating whether printStackTrace is being executed.
     */
    private boolean inPrintStackTrace = false;
    
    /**
     * Constructs a new JDOException without a detail message.
     */
    public JDOException() {
    }

    /**
     * Constructs a new JDOException with the specified detail message.
     * @param msg the detail message.
     */
    public JDOException(String msg) {
        super(msg);
    }

    /** Constructs a new JDOException with the specified detail message
     * and nested Throwables.
     * @param msg the detail message.
     * @param nested the nested Throwable[].
     */
    public JDOException(String msg, Throwable[] nested) {
        super(msg);
        this.nested = nested;
    }
  
    /** Constructs a new JDOException with the specified detail message
     * and nested Throwable.
     * @param msg the detail message.
     * @param nested the nested Throwable.
     */
    public JDOException(String msg, Throwable nested) {
        super(msg);
        this.nested = new Throwable[] {nested};
    }
  
    /** Constructs a new JDOException with the specified detail message
     * and failed object.
     * @param msg the detail message.
     * @param failed the failed object.
     */
    public JDOException(String msg, Object failed) {
        super(msg);
        this.failed = failed;
    }
  
    /** Constructs a new JDOException with the specified detail message,
     * nested Throwables, and failed object.
     * @param msg the detail message.
     * @param nested the nested Throwable[].
     * @param failed the failed object.
     */
    public JDOException(String msg, Throwable[] nested, Object failed) {
        super(msg);
        this.nested = nested;
        this.failed = failed;
    }
  
    /** Constructs a new JDOException with the specified detail message,
     * nested Throwable, and failed object.
     * @param msg the detail message.
     * @param nested the nested Throwable.
     * @param failed the failed object.
     */
    public JDOException(String msg, Throwable nested, Object failed) {
        super(msg);
        this.nested = new Throwable[] {nested};
        this.failed = failed;
    }
  
    /** 
     * The exception may include a failed object.
     * @return the failed object.
     */
    public Object getFailedObject() {
        return failed;
    }
  
    /** The exception may have been caused by multiple exceptions in the runtime.
     * If multiple objects caused the problem, each failed object will have
     * its own Exception.
     * @return the nested Throwable array.
     */
    public Throwable[] getNestedExceptions() {
        return nested;
    }
  
    /** Often there is only one nested exception, and this method returns it.
     * If there are more than one, then this method returns the first nested
     * exception. If there is no nested exception, then null is returned.
     * @return the first or only nested Throwable.
     * @since 1.0.1
     */
    public synchronized Throwable getCause() {
        // super.printStackTrace calls getCause to handle the cause. 
        // Returning null prevents the superclass from handling the cause;
        // instead the local implementation of printStackTrace should
        // handle the cause. Otherwise, the cause is printed twice.
        if (nested == null || nested.length == 0 || inPrintStackTrace) {
            return null;
        } else {
            return nested[0];
        }
    }
  
    /** JDK 1.4 includes a new chaining mechanism for Throwable, but since
     * JDO has its own "legacy" chaining mechanism, the "standard" mechanism
     * cannot be used. This method always throws a JDOFatalInternalException.
     * @param cause ignored.
     * @return never.
     */
    public Throwable initCause(Throwable cause) {
        throw new JDOFatalInternalException(msg.msg("ERR_CannotInitCause"));
    }
  
    /** The String representation includes the name of the class,
     * the descriptive comment (if any),
     * the String representation of the failed Object (if any),
     * and the String representation of the nested Throwables (if any).
     * @return the String.
     */
    public synchronized String toString() {
        int len = nested==null?0:nested.length;
        // calculate approximate size of the String to return
        StringBuffer sb = new StringBuffer (10 + 100 * len);
        sb.append (super.toString());
        // include failed object information
        if (failed != null) {
            sb.append ("\n").append (msg.msg ("MSG_FailedObject"));
            String failedToString = null;
            try {
                failedToString = failed.toString();
            } catch (Exception ex) {
                // include the information from the exception thrown by failed.toString
                Object objectId = JDOHelper.getObjectId(failed);
                if (objectId == null) {
                    failedToString = msg.msg("MSG_ExceptionGettingFailedToString", //NOI18N
                                       exceptionToString(ex));
                }
                else {
                    // include the ObjectId information
                    String objectIdToString = null;
                    try {
                        objectIdToString = objectId.toString();
                    }
                    catch (Exception ex2) {
                        objectIdToString = exceptionToString(ex2);
                    }
                    failedToString = msg.msg("MSG_ExceptionGettingFailedToStringObjectId", //NOI18N
                                       exceptionToString(ex), objectIdToString);
                }
            }
            sb.append (failedToString);
        }
        // include nested Throwable information, but only if not called by
        // printStackTrace; the stacktrace will include the cause anyway.
        if (len > 0 && !inPrintStackTrace) {
            sb.append ("\n").append (msg.msg ("MSG_NestedThrowables")).append ("\n");
            Throwable exception = nested[0];
            sb.append (exception==null?"null":exception.toString()); //NOI18N
            for (int i=1; iJDOException and its backtrace to the 
     * standard error output.
     * Print nested Throwables' stack trace as well.
     */
    public void printStackTrace() { 
        printStackTrace (System.err);
    }

    /**
     * Prints this JDOException and its backtrace to the 
     * specified print stream.
     * Print nested Throwables' stack trace as well.
     * @param s PrintStream to use for output
     */
    public synchronized void printStackTrace(java.io.PrintStream s) { 
        int len = nested==null?0:nested.length;
        synchronized (s) {
            inPrintStackTrace = true;
            super.printStackTrace(s);
            if (len > 0) {
                s.println (msg.msg ("MSG_NestedThrowablesStackTrace"));
                for (int i=0; iJDOException and its backtrace to the specified
     * print writer.
     * Print nested Throwables' stack trace as well.
     * @param s PrintWriter to use for output
     */
    public synchronized void printStackTrace(java.io.PrintWriter s) { 
    int len = nested==null?0:nested.length;
        synchronized (s) {
            inPrintStackTrace = true;
            super.printStackTrace(s);
            if (len > 0) {
                s.println (msg.msg ("MSG_NestedThrowablesStackTrace"));
                for (int i=0; i