1 package com.atlassian.johnson;
2
3 import com.atlassian.johnson.event.Event;
4
5 import java.util.Collection;
6
7 /**
8 * Interface defining a container for Johnson {@link Event}s
9 * <p/>
10 * Johnson maintains <i>exactly one</i> event container, which is accessed statically. As a result, all implementations
11 * of this interface are required to be thread-safe. However, because Johnson may be used to filter all requests to the
12 * application, implementations should be careful in how they achieve that thread-safety. Using heavy synchronisation
13 * techniques may impose significant performance penalties.
14 *
15 * @since 2.0
16 */
17 public interface JohnsonEventContainer
18 {
19 /**
20 * Adds the provided event to the collection.
21 *
22 * @param event the event to add
23 */
24 void addEvent(Event event);
25
26 /**
27 * Retrieves an <i>immutable</i> view of the contained {@link Event}s.
28 *
29 * @return the current events
30 */
31 Collection<Event> getEvents();
32
33 /**
34 * Retrieves a flag indicating whether there are {@link Event}s in the container.
35 * <p/>
36 * This can be thought of as a shortcut for {@code !getEvents().isEmpty()}.
37 *
38 * @return {@code true} if there are events; otherwise, {@code false}
39 */
40 boolean hasEvents();
41
42 /**
43 * Removes the specified {@link Event} from the container, if it can be found.
44 * <p/>
45 * Warning: Due to how {@link Event#equals(Object)} and {@link Event#hashCode()} are implemented, an <i>exact</i>
46 * match on every field is required in order to match an event. As a result, it may be necessary to iterate over
47 * the {@link #getEvents() events} in the collection and remove the event using the exact instance already in the
48 * collection.
49 *
50 * @param event the event to remove
51 */
52 void removeEvent(Event event);
53 }