001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.configuration2.event; 018 019import java.util.EventObject; 020 021/** 022 * <p> 023 * The base class for all events generated by this library. 024 * </p> 025 * <p> 026 * The events produced by objects in this library are arranged in an inheritance 027 * hierarchy. This base class defines some basic properties common to all 028 * configuration events. Especially, an event has an {@link EventType} which 029 * describes its semantics. The event type can also be used for filtering for 030 * events or for defining event listeners on a fine-grained basis. 031 * </p> 032 * 033 * @version $Id: Event.java 1842194 2018-09-27 22:24:23Z ggregory $ 034 * @since 2.0 035 */ 036public class Event extends EventObject 037{ 038 /** 039 * The root event type for all configuration-related events. All specific 040 * event types have this type as super direct (directly or indirectly). 041 */ 042 public static final EventType<Event> ANY = 043 new EventType<>(null, "ANY"); 044 045 /** 046 * Constant for the format used in toString() for a property representation. 047 */ 048 private static final String FMT_PROPERTY = " %s=%s"; 049 050 /** 051 * Constant for the initial buffer size for the generation of the string 052 * representation. 053 */ 054 private static final int BUF_SIZE = 256; 055 056 /** The type of this event. */ 057 private final EventType<? extends Event> eventType; 058 059 /** 060 * Creates a new instance of {@code Event} and sets basic properties. 061 * 062 * @param source the object on which the Event initially occurred (must not 063 * be <b>null</b>) 064 * @param evType the type of this event (must not be <b>null</b>) 065 * @throws IllegalArgumentException if a required parameter is null 066 */ 067 public Event(final Object source, final EventType<? extends Event> evType) 068 { 069 super(source); 070 if (evType == null) 071 { 072 throw new IllegalArgumentException("Event type must not be null!"); 073 } 074 eventType = evType; 075 } 076 077 /** 078 * Returns the type of this event. 079 * 080 * @return the event type 081 */ 082 public EventType<? extends Event> getEventType() 083 { 084 return eventType; 085 } 086 087 /** 088 * Returns a string representation for this object. This string contains the 089 * event class and a list of all properties. 090 * 091 * @return a string for this object 092 */ 093 @Override 094 public String toString() 095 { 096 final StringBuilder buf = new StringBuilder(BUF_SIZE); 097 buf.append(getClass().getSimpleName()); 098 buf.append(" ["); 099 appendPropertyRepresentation(buf, "source", getSource()); 100 appendPropertyRepresentation(buf, "eventType", getEventType()); 101 buf.append(" ]"); 102 return buf.toString(); 103 } 104 105 /** 106 * Helper method for appending a representation for a property to the 107 * overall string representation for this object. This method is called by 108 * {@code toString()} for generating string fragments for the properties of 109 * this class. It can also be used by derived classes which extend the 110 * string representation of this base class. 111 * 112 * @param buf the target buffer 113 * @param property the name of the property 114 * @param value the property value 115 */ 116 protected void appendPropertyRepresentation(final StringBuilder buf, 117 final String property, final Object value) 118 { 119 buf.append(String.format(FMT_PROPERTY, property, String.valueOf(value))); 120 } 121}