javax.jdo.JDOException Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jdo-api Show documentation
The Java Data Objects (JDO) API is a standard interface-based Java model abstraction of persistence, developed as Java Specification Request 243 under the auspices of the Java Community Process.
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 {
  
  /** 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