1  /*
     2   * Copyright the original author or authors.
     3   * 
     4   * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
     5   * you may not use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   * 
     8   *      http://www.mozilla.org/MPL/MPL-1.1.html
     9   * 
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  
    17  import org.as2lib.env.except.Throwable;
    18  import org.as2lib.env.except.AbstractThrowable;
    19  
    20  /**
    21   * {@code Exception} is a default implementation of the {@code Throwable}
    22   * interface.
    23   *
    24   * <p>It differs from the {@link FatalException} class in that it marks the
    25   * throwable as not-fatal. That means it differs from a {@code FatalException} in
    26   * its fatality.
    27   *
    28   * <p>It also uses the {@code Logger.error} method to log itself, while the
    29   * {@code FatalException} class uses the {@code Logger.fatal} method.
    30   *
    31   * <p>Example:
    32   * <code>
    33   *   throw new Exception("This is a detailed message that explains the problem.", this, arguments);
    34   * <code>
    35   *
    36   * <p>The above example is supposed to be in a method, that has been declared on a
    37   * class.
    38   *
    39   * <p>Note that you normally do not throw instances of this class directly. It is
    40   * better to sub-class it, that means to create a custom exception, that explains
    41   * its purpose more closely by its name, and throw this exception instead.
    42   *
    43   * <p>If you are building a framework that shall be reused it is also helpful to
    44   * built a exception inheritance hierarchy, where you have one base class. You can
    45   * then categorize different exceptions by their inheritance hierarchy. This
    46   * enables you to catch all exceptions from your whole framework or only from
    47   * specific parts of your framework.
    48   *
    49   * <p>For a detailed explanation on how to use throwables, what this exception
    50   * framework offers you and how to work appropriately with throwables take a look
    51   * at the class documentation of the {@code Throwable} interface.
    52   *
    53   * @author Simon Wacker
    54   */
    55  class org.as2lib.env.except.Exception extends AbstractThrowable implements Throwable {
    56  	
    57  	/**
    58  	 * Constructs a new {@code Exception} instance.
    59  	 *
    60  	 * <p>All arguments are allowed to be {@code null} or {@code undefined}. But if one
    61  	 * is, the string representation returned by the {@code toString} method will not
    62  	 * be complete.
    63  	 *
    64  	 * <p>The {@code args} array should be the internal arguments array of the method
    65  	 * that throws the throwable. The internal arguments array exists in every method
    66  	 * and contains its parameters, the callee method and the caller method. You can
    67  	 * refernce it in every method using the name {@code "arguments"}.
    68  	 *
    69  	 * @param message the message that describes the problem in detail
    70  	 * @param thrower the object that declares the method that throws this exception
    71  	 * @param args the arguments of the throwing method
    72  	 */
    73  	public function Exception(message:String, thrower, args:Array) {
    74  		super (message, thrower, args);
    75  	}
    76  	
    77  	/**
    78  	 * Returns the string representation of this exception.
    79  	 *
    80  	 * <p>If you do not call this method out of another method, it also executes
    81  	 * the {@code error} method on the logger returned by the
    82  	 * {@link AbstractThrowable#getLogger} method passing {@code this} because it
    83  	 * thinks that the virtual machine called this method.
    84  	 * 
    85  	 * <p>The string representation is obtained via the invocation of the
    86  	 * {@link AbstractThrowable#doToString} method that uses the stringifier returned
    87  	 * by the static {@link AbstractThrowable#getStringifier} method.
    88  	 *
    89  	 * <p>If you want to change the appearance of all exceptions set a new stringifier
    90  	 * via the static {@link AbstractThrowable#setStringifier} method.
    91  	 *
    92  	 * <p>If you only want to change the string representation of one exception and
    93  	 * its sub-classes overwrite the {@code doToString} method in your custom
    94  	 * exception.
    95  	 *
    96  	 * <p>Do not overwrite this method because you will lose the functionality that
    97  	 * invokes the logger when the exception has not been caught and has now reached
    98  	 * the final 'level', the virtual machine, that invokes this method.
    99  	 *
   100  	 * @return the string representation of this fatal exception
   101  	 */
   102  	public function toString():String {
   103  		if (!arguments.caller) {
   104  			if (getLogger().isErrorEnabled()) {
   105  				getLogger().error(this);
   106  			}
   107  		}
   108  		return doToString();
   109  	}
   110  	
   111  }
as2api