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  }