1 package org.djutils.event;
2
3 import org.djutils.exceptions.Throw;
4 import org.djutils.metadata.MetaData;
5
6 /**
7 * Reference implementation of the EventType. The AbstractEventType is the description of a topic used for the subscription to
8 * asynchronous events. Event types are used by EventProducers to show which events they potentially fire. EventTypes are
9 * typically defined as static final fields. In order to prevent name clashes for the EventType, the full name of the class from
10 * which the EventType was defined (usually in the <clinit>) is added to the equals() and hashCode() methods of the
11 * EventType. In that way, EventTypes that are the same will be unique, but EventTypes with just the same name but defined in
12 * different classes will be different. This is the abstract class that can be tailored to any event type. Subclasses that
13 * extend the AbstractEventType are the EventType for regular events, and TimedEventType for timed events.<br>
14 * <br>
15 * Note: the reason why this is important is because <b>remote events</b> that use EventTypes can have <i>multiple versions</i>
16 * of the same public static final EventType: one the is defined in the client, and one that is defined via the network. These
17 * will have <i>different addresses in memory</i> but they share the same class and name info, so equals() will yield true.
18 * <p>
19 * Copyright (c) 2002-2022 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
20 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
21 * distributed under a three-clause BSD-style license, which can be found at
22 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>. This class was
23 * originally part of the DSOL project, see <a href="https://simulation.tudelft.nl/dsol/manual" target="_blank">
24 * https://simulation.tudelft.nl/dsol/manual</a>.
25 * </p>
26 * @author <a href="https://www.linkedin.com/in/peterhmjacobs">Peter Jacobs </a>
27 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
28 */
29 public abstract class AbstractEventType implements EventTypeInterface
30 {
31 /** The default serial version UID for serializable classes. */
32 private static final long serialVersionUID = 20140830L;
33
34 /** The name of the eventType. */
35 private final String name;
36
37 /** Meta data (describes the payload). */
38 private final MetaData metaData;
39
40 /** The class of a valid event, e.g., to indicate that a TimedEvent is expected. */
41 private final Class<? extends EventInterface> validEventType;
42
43 /**
44 * The class name from which the event type construction was called; together with the event name this should lead to a
45 * unique hash, even when the same name is used in different classes.
46 */
47 private String definingClassName;
48
49 /**
50 * Construct a new EventType with an explicit type of event that is considered to be a valid event when the event is
51 * verified. This can, for instance, be used to verify that a TimedEvent is fired instead of an ordinary event.
52 * @param name String; the name of the new eventType. Two values are not appreciated: null and the empty string.
53 * @param metaData MetaData; describes the payload of events of the new EventType;
54 * @param validEventType Class<? extends EventInterface>; the valid class of events
55 */
56 public AbstractEventType(final String name, final MetaData metaData, final Class<? extends EventInterface> validEventType)
57 {
58 Throw.when(name == null || name.equals(""), IllegalArgumentException.class,
59 "EventType name == null || EventType name == \"\"");
60 Throw.whenNull(metaData,
61 "Meta data may not be null (but you could provide the NO_META_DATA value if the payload will be varying)");
62 this.name = name;
63 Throw.whenNull(validEventType, "validEventType may not be null");
64 this.validEventType = validEventType;
65 StackTraceElement[] steArray = new Throwable().getStackTrace();
66 for (StackTraceElement ste : steArray)
67 {
68 if (!(ste.getClassName().endsWith("EventType")))
69 {
70 this.definingClassName = ste.getClassName();
71 break;
72 }
73 }
74 Throw.whenNull(this.definingClassName, "no defining class name found that is not an EventType");
75 this.metaData = metaData;
76 }
77
78 /** {@inheritDoc} */
79 @Override
80 public String getName()
81 {
82 return this.name;
83 }
84
85 /** {@inheritDoc} */
86 @Override
87 public MetaData getMetaData()
88 {
89 return this.metaData;
90 }
91
92 /** {@inheritDoc} */
93 @Override
94 public Class<? extends EventInterface> getValidEventType()
95 {
96 return this.validEventType;
97 }
98
99 /** {@inheritDoc} */
100 @Override
101 public String toString()
102 {
103 return this.name;
104 }
105
106 /** {@inheritDoc} */
107 @Override
108 public int hashCode()
109 {
110 final int prime = 31;
111 int result = 1;
112 result = prime * result + this.definingClassName.hashCode();
113 result = prime * result + this.name.hashCode();
114 return result;
115 }
116
117 /** {@inheritDoc} */
118 @Override
119 @SuppressWarnings("checkstyle:needbraces")
120 public boolean equals(final Object obj)
121 {
122 if (this == obj)
123 return true;
124 if (obj == null)
125 return false;
126 if (getClass() != obj.getClass())
127 return false;
128 AbstractEventType other = (AbstractEventType) obj;
129 if (!this.name.equals(other.name))
130 return false;
131 if (!this.definingClassName.equals(other.definingClassName))
132 return false;
133 return true;
134 }
135
136 }