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 }