View Javadoc

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  }