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 *     https://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.io.Serializable;
020import java.util.HashSet;
021import java.util.Set;
022
023/**
024 * <p>
025 * A class representing an event type.
026 * </p>
027 * <p>
028 * The events produced by <em>Commons Configuration</em> all have a specific type. The event type can be used to
029 * determine the meaning of a specific event. It also acts as filter criterion when event listeners are registered. The
030 * listener is then called only for events of this type or derived types. The events in this library form a natural
031 * hierarchy with base types and more specialized types. By specifying an appropriate event type at listener
032 * registration time, it can be determined on a fine-granular basis which events are propagated to the listener.
033 * </p>
034 * <p>
035 * Note: Users familiar with JavaFX probably recognize this approach to event handling. It allows for generic event
036 * listener interfaces and a natural selection of events to be processed.
037 * </p>
038 *
039 * @param <T> the event associated with this type
040 * @since 2.0
041 */
042public class EventType<T extends Event> implements Serializable {
043
044    /** Serial version UID. */
045    private static final long serialVersionUID = 20150416L;
046
047    /** Constant for the format used by toString(). */
048    private static final String FMT_TO_STRING = "%s [ %s ]";
049
050    /**
051     * Returns a set with all event types that are super types of the specified type. This set contains the direct and
052     * indirect super types and also includes the given type itself. The passed in type may be <strong>null</strong>, then an empty
053     * set is returned.
054     *
055     * @param eventType the event type in question
056     * @return a set with all super event types
057     */
058    public static Set<EventType<?>> fetchSuperEventTypes(final EventType<?> eventType) {
059        final Set<EventType<?>> types = new HashSet<>();
060        EventType<?> currentType = eventType;
061        while (currentType != null) {
062            types.add(currentType);
063            currentType = currentType.getSuperType();
064        }
065        return types;
066    }
067
068    /**
069     * Checks whether an event type is derived from another type. This implementation tests whether {@code baseType} is a
070     * direct or indirect super type of {@code derivedType}. If one of the types is <strong>null</strong>, result is <strong>false</strong>.
071     *
072     * @param derivedType the derived event type
073     * @param baseType the base event type
074     * @return <strong>true</strong> if the derived type is an instance of the base type, <strong>false</strong> otherwise
075     */
076    public static boolean isInstanceOf(final EventType<?> derivedType, final EventType<?> baseType) {
077        EventType<?> currentType = derivedType;
078        while (currentType != null) {
079            if (currentType == baseType) {
080                return true;
081            }
082            currentType = currentType.getSuperType();
083        }
084        return false;
085    }
086
087    /** Stores the super type of this type. */
088    private final EventType<? super T> superType;
089
090    /** A name for this event type. */
091    private final String name;
092
093    /**
094     * Creates a new instance of {@code EventType} and initializes it with the super type and a type name. If no super type
095     * is specified, this is the root event type.
096     *
097     * @param superEventType the super event type
098     * @param typeName the name of this event type
099     */
100    public EventType(final EventType<? super T> superEventType, final String typeName) {
101        superType = superEventType;
102        name = typeName;
103    }
104
105    /**
106     * Gets the name of this event type. The name has no specific semantic meaning. It is just used for debugging
107     * purposes and also part of the string representation of this event type.
108     *
109     * @return the event type name
110     */
111    public String getName() {
112        return name;
113    }
114
115    /**
116     * Gets the super event type. Result is <strong>null</strong> for the root event type.
117     *
118     * @return the super event type
119     */
120    public EventType<? super T> getSuperType() {
121        return superType;
122    }
123
124    /**
125     * Returns a string representation for this object. This method is mainly overridden for debugging purposes. The
126     * returned string contains the name of this event type.
127     *
128     * @return a string for this object
129     */
130    @Override
131    public String toString() {
132        return String.format(FMT_TO_STRING, getClass().getSimpleName(), getName());
133    }
134}