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 * @since 2.0 034 */ 035public class Event extends EventObject 036{ 037 /** 038 * The root event type for all configuration-related events. All specific 039 * event types have this type as super direct (directly or indirectly). 040 */ 041 public static final EventType<Event> ANY = 042 new EventType<>(null, "ANY"); 043 044 /** 045 * Constant for the format used in toString() for a property representation. 046 */ 047 private static final String FMT_PROPERTY = " %s=%s"; 048 049 /** 050 * Constant for the initial buffer size for the generation of the string 051 * representation. 052 */ 053 private static final int BUF_SIZE = 256; 054 055 /** The type of this event. */ 056 private final EventType<? extends Event> eventType; 057 058 /** 059 * Creates a new instance of {@code Event} and sets basic properties. 060 * 061 * @param source the object on which the Event initially occurred (must not 062 * be <b>null</b>) 063 * @param evType the type of this event (must not be <b>null</b>) 064 * @throws IllegalArgumentException if a required parameter is null 065 */ 066 public Event(final Object source, final EventType<? extends Event> evType) 067 { 068 super(source); 069 if (evType == null) 070 { 071 throw new IllegalArgumentException("Event type must not be null!"); 072 } 073 eventType = evType; 074 } 075 076 /** 077 * Returns the type of this event. 078 * 079 * @return the event type 080 */ 081 public EventType<? extends Event> getEventType() 082 { 083 return eventType; 084 } 085 086 /** 087 * Returns a string representation for this object. This string contains the 088 * event class and a list of all properties. 089 * 090 * @return a string for this object 091 */ 092 @Override 093 public String toString() 094 { 095 final StringBuilder buf = new StringBuilder(BUF_SIZE); 096 buf.append(getClass().getSimpleName()); 097 buf.append(" ["); 098 appendPropertyRepresentation(buf, "source", getSource()); 099 appendPropertyRepresentation(buf, "eventType", getEventType()); 100 buf.append(" ]"); 101 return buf.toString(); 102 } 103 104 /** 105 * Helper method for appending a representation for a property to the 106 * overall string representation for this object. This method is called by 107 * {@code toString()} for generating string fragments for the properties of 108 * this class. It can also be used by derived classes which extend the 109 * string representation of this base class. 110 * 111 * @param buf the target buffer 112 * @param property the name of the property 113 * @param value the property value 114 */ 115 protected void appendPropertyRepresentation(final StringBuilder buf, 116 final String property, final Object value) 117 { 118 buf.append(String.format(FMT_PROPERTY, property, String.valueOf(value))); 119 } 120}