Package org.apache.commons.configuration2.event

# Class ConfigurationErrorEvent

java.lang.Object
java.util.EventObject
org.apache.commons.configuration2.event.Event
org.apache.commons.configuration2.event.ConfigurationErrorEvent

All Implemented Interfaces:
  `Serializable`

public class ConfigurationErrorEvent extends Event

An event class that is used for reporting errors that occurred while processing configuration properties.

Some configuration implementations (for example `DatabaseConfiguration` or `JNDIConfiguration` use an underlying storage that can throw an exception on each property access. In earlier versions of this library such exceptions were logged and then silently ignored. This makes it impossible for a client to find out that something went wrong.

To give clients better control over the handling of errors that might occur while interacting with a configuration object, a specialized error event type is introduced. Clients can register as listeners of this event type at a configuration object and are then notified about all internal errors related to the source configuration object.

This class defines similar properties to the `ConfigurationEvent` class. This makes it possible to find out which operation was performed on a configuration causing this error event. In addition, a `Throwable` object is available representing the occurred error. Note that depending on the event type and the occurred exception not all of the other properties (for example name of the affected property or its value) may be available.

Since:
  1.4
See Also:
  - `ConfigurationEvent`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final EventType<ConfigurationErrorEvent>`
  `ANY`
  Constant for the common event type for all error events.
  `static final EventType<ConfigurationErrorEvent>`
  `READ`
  Constant for the event type indicating a read error.
  `static final EventType<ConfigurationErrorEvent>`
  `WRITE`
  Constant for the event type indicating a write error.

  ### Fields inherited from class java.util.EventObject

  `source`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ConfigurationErrorEvent(Object source, EventType<? extends ConfigurationErrorEvent> eventType, EventType<?> operationType, String propName, Object propValue, Throwable cause)`
  Creates a new instance of `ConfigurationErrorEvent` and sets all its properties.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Throwable`
  `getCause()`
  Gets the cause of this error event.
  `EventType<?>`
  `getErrorOperationType()`
  Gets the `EventType` of the operation which caused this error.
  `String`
  `getPropertyName()`
  Gets the name of the property that was accessed when this error occurred.
  `Object`
  `getPropertyValue()`
  Gets the value of the property that was accessed when this error occurred.

  ### Methods inherited from class org.apache.commons.configuration2.event.Event

  `appendPropertyRepresentation, getEventType, toString`

  ### Methods inherited from class java.util.EventObject

  `getSource`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### ANY

    public static final EventType<ConfigurationErrorEvent> ANY
    Constant for the common event type for all error events. Specific types for error events use this type as super type.
    Since:
      2.0

  - ### READ

    public static final EventType<ConfigurationErrorEvent> READ
    Constant for the event type indicating a read error. Errors of this type are generated if the underlying data store throws an exception when reading a property.
    Since:
      2.0

  - ### WRITE

    public static final EventType<ConfigurationErrorEvent> WRITE
    Constant for the event type indicating a write error. Errors of this type are generate if the underlying data store throws an exception when updating data.
    Since:
      2.0

- ## Constructor Details

  - ### ConfigurationErrorEvent

    public ConfigurationErrorEvent(Object source, EventType<? extends ConfigurationErrorEvent> eventType, EventType<?> operationType, String propName, Object propValue, Throwable cause)
    Creates a new instance of `ConfigurationErrorEvent` and sets all its properties.
    Parameters:
      `source` - the event source
      `eventType` - the type of this event
      `operationType` - the event type of the operation causing this error
      `propName` - the name of the affected property
      `propValue` - the value of the affected property
      `cause` - the exception object that caused this event

- ## Method Details

  - ### getCause

    public Throwable getCause()
    Gets the cause of this error event. This is the `Throwable` object that caused this event to be fired.
    Returns:
      the cause of this error event

  - ### getErrorOperationType

    public EventType<?> getErrorOperationType()
    Gets the `EventType` of the operation which caused this error.
    Returns:
      the event type of the operation causing this error

  - ### getPropertyName

    public String getPropertyName()
    Gets the name of the property that was accessed when this error occurred.
    Returns:
      the property name related to this error (may be null)

  - ### getPropertyValue

    public Object getPropertyValue()
    Gets the value of the property that was accessed when this error occurred.
    Returns:
      the property value related this error (may be null)