View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  package org.apache.commons.configuration.event;
    18
    19  /***
    20   * <p>
    21   * An event class that is used for reporting errors that occurred while
    22   * processing configuration properties.
    23   * </p>
    24   * <p>
    25   * Some configuration implementations (e.g.
    26   * <code>{@link org.apache.commons.configuration.DatabaseConfiguration}</code>
    27   * or <code>{@link org.apache.commons.configuration.JNDIConfiguration}</code>
    28   * use an underlying storage that can throw an exception on each property
    29   * access. In earlier versions of this library such exceptions were logged and
    30   * then silently ignored. This makes it impossible for a client to find out that
    31   * something went wrong.
    32   * </p>
    33   * <p>
    34   * To give clients better control over the handling of errors that occur during
    35   * access of a configuration object a new event listener mechanism specific for
    36   * exceptions is introduced: Clients can register itself at a configuration
    37   * object as an <em>error listener</em> and are then notified about all
    38   * internal errors related to the source configuration object.
    39   * </p>
    40   * <p>
    41   * By inheriting from <code>ConfigurationEvent</code> this event class
    42   * supports all properties that describe an operation on a configuration
    43   * instance. In addition a <code>Throwable</code> object is available
    44   * representing the occurred error. The event's type determines the operation
    45   * that caused the error. Note that depending on the event type and the occurred
    46   * exception not all of the other properties (e.g. name of the affected property
    47   * or its value) may be available.
    48   * </p>
    49   *
    50   * @author <a
    51   * href="http://commons.apache.org/configuration/team-list.html">Commons
    52   * Configuration team</a>
    53   * @version $Id: ConfigurationErrorEvent.java 561230 2007-07-31 04:17:09Z rahul $
    54   * @since 1.4
    55   * @see ConfigurationEvent
    56   */
    57  public class ConfigurationErrorEvent extends ConfigurationEvent
    58  {
    59      /***
    60       * The serial version UID.
    61       */
    62      private static final long serialVersionUID = -7433184493062648409L;
    63
    64      /*** Stores the exception that caused this event. */
    65      private Throwable cause;
    66
    67      /***
    68       * Creates a new instance of <code>ConfigurationErrorEvent</code> and
    69       * initializes it.
    70       *
    71       * @param source the event source
    72       * @param type the event's type
    73       * @param propertyName the name of the affected property
    74       * @param propertyValue the value of the affected property
    75       * @param cause the exception object that caused this event
    76       */
    77      public ConfigurationErrorEvent(Object source, int type,
    78              String propertyName, Object propertyValue, Throwable cause)
    79      {
    80          super(source, type, propertyName, propertyValue, true);
    81          this.cause = cause;
    82      }
    83
    84      /***
    85       * Returns the cause of this error event. This is the <code>Throwable</code>
    86       * object that caused this event to be fired.
    87       *
    88       * @return the cause of this error event
    89       */
    90      public Throwable getCause()
    91      {
    92          return cause;
    93      }
    94  }