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 <b>null</b>) 61 * @param evType the type of this event (must not be <b>null</b>) 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 * Gets the type of this event. 74 * 75 * @return the event type 76 */ 77 public EventType<? extends Event> getEventType() { 78 return eventType; 79 } 80 81 /** 82 * Returns a string representation for this object. This string contains the event class and a list of all properties. 83 * 84 * @return a string for this object 85 */ 86 @Override 87 public String toString() { 88 final StringBuilder buf = new StringBuilder(BUF_SIZE); 89 buf.append(getClass().getSimpleName()); 90 buf.append(" ["); 91 appendPropertyRepresentation(buf, "source", getSource()); 92 appendPropertyRepresentation(buf, "eventType", getEventType()); 93 buf.append(" ]"); 94 return buf.toString(); 95 } 96 97 /** 98 * Helper method for appending a representation for a property to the overall string representation for this object. 99 * This method is called by {@code toString()} for generating string fragments for the properties of this class. It can 100 * also be used by derived classes which extend the string representation of this base class. 101 * 102 * @param buf the target buffer 103 * @param property the name of the property 104 * @param value the property value 105 */ 106 protected void appendPropertyRepresentation(final StringBuilder buf, final String property, final Object value) { 107 buf.append(String.format(FMT_PROPERTY, property, String.valueOf(value))); 108 } 109 }