package se.l4.vibe.events;

import se.l4.vibe.Exportable;
import se.l4.vibe.Handle;
import se.l4.vibe.internal.EventsImpl;
import se.l4.vibe.probes.Probe;
import se.l4.vibe.sampling.SampledProbe;


/**
 * Event registration, used to register events in a system. The events object
 * is created using a {@link Builder} created via {@link #builder()}.
 *
 * <p>
 * <pre>
 * Events<E> events = Events.builder()
 *   .withSeverity(EventSeverity.INFO)
 *   .build();
 * </pre>
 *
 * @param <T>
 */
public interface Events<T extends EventData>
	extends Exportable
{
	/**
	 * Register a new event using the default severity.
	 *
	 * @param eventData
	 */
	void register(T eventData);

	/**
	 * Register a new event with the specified severity.
	 *
	 * @param severity
	 * @param eventData
	 */
	void register(EventSeverity severity, T eventData);

	/**
	 * Get the default severity for this object.
	 *
	 * @return
	 */
	EventSeverity getDefaultSeverity();

	/**
	 * Add a listener that will receive events.
	 *
	 * @param listener
	 */
	Handle addListener(EventListener<T> listener);

	/**
	 * Remove a listener that will receive events.
	 *
	 * @param listener
	 */
	void removeListener(EventListener<T> listener);

	/**
	 * Get a probe that will return the total amount of events registered.
	 *
	 * @return
	 */
	Probe<Long> getTotalEventsProbe();

	/**
	 * Get a probe that will return the number of events received since it
	 * was last sampled.
	 *
	 * @return
	 */
	SampledProbe<Long> getEventsProbe();

	/**
	 * Start building a new {@link Events}.
	 *
	 * @param <T>
	 * @return
	 */
	static <T extends EventData> Builder<T> builder()
	{
		return new EventsImpl.BuilderImpl<>();
	}

	/**
	 * Builder for instances of {@link Events}.
	 */
	interface Builder<T extends EventData>
	{
		/**
		 * Set the severity of the events.
		 *
		 * @param severity
		 * @return
		 */
		Builder<T> withSeverity(EventSeverity severity);

		/**
		 * Build the instance.
		 *
		 * @return
		 *   instance of {@link Events}
		 */
		Events<T> build();
	}
}

@@ -190,17 +190,16 @@
 Probe;%0A%0A
-%0A
 /**%0A * E
@@ -467,16 +467,693 @@
 pre%3E%0A *%0A
+ * %3Ch2%3ERegister and listen to events%3C/h2%3E%0A *%0A * Events can be registered with %7B@link #register(EventData)%7D to be emitted%0A * with the default severity. %7B@link #register(EventSeverity, EventData)%7D can%0A * be used to emit events with a different severity.%0A *%0A * %3Cp%3E%0A * Use %7B@link #addListener(EventListener)%7D to listen for events being emitted.%0A *%0A * %3Ch2%3EProbes%3C/h2%3E%0A *%0A * Instances contain two probes, one for total events via %7B@link #getTotalEventsProbe()%7D%0A * and one sampled probe via %7B@link #getEventsProbe()%7D. These probes can be%0A * %7B@link se.l4.vibe.Vibe#export(Exportable) exported%7D, used with a%0A * %7B@link se.l4.vibe.sampling.Sampler%7D or %7B@link se.l4.vibe.checks.Check%7D.%0A *%0A
  * @para
@@ -1304,32 +1304,56 @@
 param eventData%0A
+%09 *   data of the event%0A
 %09 */%0A%09void regis
@@ -1458,32 +1458,78 @@
 ity%0A%09 * 
-@param eventData
+  severity to use%0A%09 * @param eventData%0A%09 *   data of the event
 %0A%09 */%0A%09v

Update Events documentation