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.configuration2.event;
18  
19  import java.util.EventObject;
20  
21  /**
22   * <p>
23   * The base class for all events generated by this library.
24   * </p>
25   * <p>
26   * The events produced by objects in this library are arranged in an inheritance hierarchy. This base class defines some
27   * basic properties common to all configuration events. Especially, an event has an {@link EventType} which describes
28   * its semantics. The event type can also be used for filtering for events or for defining event listeners on a
29   * fine-grained basis.
30   * </p>
31   *
32   * @since 2.0
33   */
34  public class Event extends EventObject {
35  
36      /**
37       * The root event type for all configuration-related events. All specific event types have this type as super direct
38       * (directly or indirectly).
39       */
40      public static final EventType<Event> ANY = new EventType<>(null, "ANY");
41  
42      private static final long serialVersionUID = -8168310049858198944L;
43  
44      /**
45       * Constant for the format used in toString() for a property representation.
46       */
47      private static final String FMT_PROPERTY = " %s=%s";
48  
49      /**
50       * Constant for the initial buffer size for the generation of the string representation.
51       */
52      private static final int BUF_SIZE = 256;
53  
54      /** The type of this event. */
55      private final EventType<? extends Event> eventType;
56  
57      /**
58       * Creates a new instance of {@code Event} and sets basic properties.
59       *
60       * @param source the object on which the Event initially occurred (must not be <strong>null</strong>)
61       * @param evType the type of this event (must not be <strong>null</strong>)
62       * @throws IllegalArgumentException if a required parameter is null
63       */
64      public Event(final Object source, final EventType<? extends Event> evType) {
65          super(source);
66          if (evType == null) {
67              throw new IllegalArgumentException("Event type must not be null!");
68          }
69          eventType = evType;
70      }
71  
72      /**
73       * Helper method for appending a representation for a property to the overall string representation for this object.
74       * This method is called by {@code toString()} for generating string fragments for the properties of this class. It can
75       * also be used by derived classes which extend the string representation of this base class.
76       *
77       * @param buf the target buffer
78       * @param property the name of the property
79       * @param value the property value
80       */
81      protected void appendPropertyRepresentation(final StringBuilder buf, final String property, final Object value) {
82          buf.append(String.format(FMT_PROPERTY, property, String.valueOf(value)));
83      }
84  
85      /**
86       * Gets the type of this event.
87       *
88       * @return the event type
89       */
90      public EventType<? extends Event> getEventType() {
91          return eventType;
92      }
93  
94      /**
95       * Returns a string representation for this object. This string contains the event class and a list of all properties.
96       *
97       * @return a string for this object
98       */
99      @Override
100     public String toString() {
101         final StringBuilder buf = new StringBuilder(BUF_SIZE);
102         buf.append(getClass().getSimpleName());
103         buf.append(" [");
104         appendPropertyRepresentation(buf, "source", getSource());
105         appendPropertyRepresentation(buf, "eventType", getEventType());
106         buf.append(" ]");
107         return buf.toString();
108     }
109 }