JarCastingJeasse Asity
Jeasse Asity is a jEaSSE connector for Asity, which allows to add the Server Sent Events feature to your web application no matter what Java web framework you use. Jeasse Asity is based on two libraries:
- jEaSSE: A Server Sent Events (SSE) implementation for Java.
- Asity: An HTTP/WebSocket abstraction layer for Java.
Getting Started
Adding Dependencies
Add the following dependencies to your application. These modules allow to create a SSE application which is framework-agnostic.
<dependency>
<groupId>info.macias</groupId>
<artifactId>jeasse-common</artifactId>
<version>0.11.3</version>
</dependency>
<dependency>
<groupId>kim.donghwan</groupId>
<artifactId>jeasse-asity-core</artifactId>
<version>0.1.0</version>
</dependency>
Add an Asity bridge according to your web framework. This module allows to plug your SSE application into the framework of your choice. Asity supports the following web frameworks as of 3Q 2019.
asity-bridge-vertx3: Vert.x 3asity-bridge-vertx2: Vert.x 2asity-bridge-spring-webmvc4: Spring MVC 4asity-bridge-spring-webflux5: Spring WebFlux 5asity-bridge-servlet3: Java Servlet 3asity-bridge-play2: Play Framework 2asity-bridge-netty4: Netty 4asity-bridge-grizzly2: Grizzly 2asity-bridge-atmosphere2: Atmosphere 2
<dependency>
<groupId>io.cettia.asity</groupId>
<artifactId>asity-bridge-${your.web.framework}</artifactId>
<version>3.0.0</version>
</dependency>
Writing a Web Fragment
A web fragment is a labmda that takes a ServerHttpExchange instance which an abstraction of framework-specific HTTP request-response exchanges.
public class MyJeasseAsityAction implements Action<ServerHttpExchange> {
@Override
public void on(ServerHttpExchange http) {
switch (http.method()) {
case GET:
// Handle GET requests
break;
case POST:
// Handle POST requests
break;
default:
http.setStatus(HttpStatus.METHOD_NOT_ALLOWED).end();
break;
}
}
}
The above web fragment handles only GET and POST requests and responds with 405, Method Not Allowed, for other requests. You'll learn how to plug it into your framework later.
Working with a SSE Connection
To open a SSE connection, when handling GET requests, create an AsityEventTarget with a given ServerHttpExchange which implements jEaSSE's EventTarget interface and call its ok() and open() methods.
EventTarget eventTarget = new AsityEventTarget((ServerHttpExchange) http);
eventTarget.ok().open();
To send an event through a SSE connection, use send(MessageEvent messageEvent) or send(String event, String data) of EventTarget interface.
MessageEvent event = new MessageEvent.Builder().setData("Hello World").build();
eventTarget.send(event);
Working with SSE Connections
jEaSSE provides the EventBroadcast class that streamlines handling of multiple SSE connections. Assume that it's created as a field of the web fragment and shared by each different requests.
EventBroadcast broadcaster = new EventBroadcast();
To open a SSE connection through EventBroadcast and add it as a subscriber, call its addSubscriber(EventTarget) method. You don't need to call EventTarget's ok() and open() methods in this case.
EventTarget eventTarget = new AsityEventTarget(http);
broadcaster.addSubscriber(eventTarget);
To send some events to all the subscribers, call its broadcast(MessageEvent messageEvent) or broadcast(String event, String data) method.
broadcaster.broadcast("message", "Hello World");
Plugging the Web Fragment to Your Web Application
The last step is to plug the web fragment, MyJeasseAsityAction, into your web application using an Asity bridge for the web framework you are using. Here's an example of Servlet 3.
@WebListener
public class ChatServerInitializer implements ServletContextListener {
@Override
public void contextInitialized(ServletContextEvent event) {
MyJeasseAsityAction httpAction = new MyJeasseAsityAction();
ServletContext context = event.getServletContext();
Servlet servlet = new AsityServlet().onhttp(httpAction);
ServletRegistration.Dynamic reg = context.addServlet("chat", servlet);
reg.setAsyncSupported(true);
reg.addMapping("/send");
}
}
asity-bridge-servlet3 module provides the AsityServlet class which extends Servlet's HttpServlet and abstracts Servlet's HttpServletRequest and HttpServletResponse into Asity's ServerHttpExchange. With the AsityServlet, you can feed the web fragment with HTTP request-response exchanges in a Servlet application as above.
Likewise, other Asity bridges provide such adapters per framework so that you can set up web fragments in your webapp with ease. For the details, see the Asity website's Run Anywhere section.
Example
Play around with the following examples to better understand jEaSSE and Asity. Examples require Java 8+ and Maven 3+. Clone or download the repository.
git clone https://github.com/flowersinthesand/jeasse-asity.git
cd jeasse-asity
To run a Servlet 3 example,
cd example-servlet3
mvn jetty:run
To run a Grizzly 2 example,
cd example-girzzly2
mvn package exec:java
To run a Play Framework 2 example,
cd example-play2
sbt run
All examples behave the same. Run one of examples and open a browser to http://localhost:8080/index.html. You'll see a screen similar to the following.
The web fragment of the example, MyJeasseAsityAction, is located at here.
For your information, as you may know, examples borrowed most code from the original example in jEaSSE.
Support
If you have any questions or issues with Jeasse Asity, create an issue in the issue tracker in Github or DM me on Twitter (@flowersits).