1 //
2 // ========================================================================
3 // Copyright (c) 1995-2015 Mort Bay Consulting Pty. Ltd.
4 // ------------------------------------------------------------------------
5 // All rights reserved. This program and the accompanying materials
6 // are made available under the terms of the Eclipse Public License v1.0
7 // and Apache License v2.0 which accompanies this distribution.
8 //
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
11 //
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
14 //
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
17 //
18
19 package org.eclipse.jetty.servlets;
20
21 import java.io.IOException;
22
23 /**
24 * <p>{@link EventSource} is the passive half of an event source connection, as defined by the
25 * <a href="http://www.w3.org/TR/eventsource/">EventSource Specification</a>.</p>
26 * <p>{@link EventSource.Emitter} is the active half of the connection and allows to operate on the connection.</p>
27 * <p>{@link EventSource} allows applications to be notified of events happening on the connection;
28 * two events are being notified: the opening of the event source connection, where method
29 * {@link EventSource#onOpen(Emitter)} is invoked, and the closing of the event source connection,
30 * where method {@link EventSource#onClose()} is invoked.</p>
31 *
32 * @see EventSourceServlet
33 */
34 public interface EventSource
35 {
36 /**
37 * <p>Callback method invoked when an event source connection is opened.</p>
38 *
39 * @param emitter the {@link Emitter} instance that allows to operate on the connection
40 * @throws IOException if the implementation of the method throws such exception
41 */
42 public void onOpen(Emitter emitter) throws IOException;
43
44 /**
45 * <p>Callback method invoked when an event source connection is closed.</p>
46 */
47 public void onClose();
48
49 /**
50 * <p>{@link Emitter} is the active half of an event source connection, and allows applications
51 * to operate on the connection by sending events, data or comments, or by closing the connection.</p>
52 * <p>An {@link Emitter} instance will be created for each new event source connection.</p>
53 * <p>{@link Emitter} instances are fully thread safe and can be used from multiple threads.</p>
54 */
55 public interface Emitter
56 {
57 /**
58 * <p>Sends a named event with data to the client.</p>
59 * <p>When invoked as: <code>event("foo", "bar")</code>, the client will receive the lines:</p>
60 * <pre>
61 * event: foo
62 * data: bar
63 * </pre>
64 *
65 * @param name the event name
66 * @param data the data to be sent
67 * @throws IOException if an I/O failure occurred
68 * @see #data(String)
69 */
70 public void event(String name, String data) throws IOException;
71
72 /**
73 * <p>Sends a default event with data to the client.</p>
74 * <p>When invoked as: <code>data("baz")</code>, the client will receive the line:</p>
75 * <pre>
76 * data: baz
77 * </pre>
78 * <p>When invoked as: <code>data("foo\r\nbar\rbaz\nbax")</code>, the client will receive the lines:</p>
79 * <pre>
80 * data: foo
81 * data: bar
82 * data: baz
83 * data: bax
84 * </pre>
85 *
86 * @param data the data to be sent
87 * @throws IOException if an I/O failure occurred
88 */
89 public void data(String data) throws IOException;
90
91 /**
92 * <p>Sends a comment to the client.</p>
93 * <p>When invoked as: <code>comment("foo")</code>, the client will receive the line:</p>
94 * <pre>
95 * : foo
96 * </pre>
97 *
98 * @param comment the comment to send
99 * @throws IOException if an I/O failure occurred
100 */
101 public void comment(String comment) throws IOException;
102
103 /**
104 * <p>Closes this event source connection.</p>
105 */
106 public void close();
107 }
108 }