Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tareqk/jesse

Server side event framework built on Java EE APIs
https://github.com/tareqk/jesse

Last synced: 11 days ago
JSON representation

Server side event framework built on Java EE APIs

Awesome Lists containing this project

README 

        
[![Maven Central](https://img.shields.io/maven-central/v/me.kisoft/jesse.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22me.kisoft%22%20AND%20a:%22jesse%22)

# Jesse



Jesse stands for **J**ava **E**nterprise **S**erver **S**ide **E**vents. It is a framework built using JEE APIs to provide server-side event capability in a JEE web application.



# Getting Started



## Adding It to your project



Add This to your dependencies :



```xml



    

        me.kisoft

        jesse

    



```

## Setup

You need to add some entries into your web.xml



```xml



    

        {Servlet Name}

        me.kisoft.jesse.JesseServlet

        1

        true

    

    

        {Servlet Name}

        {URI mapping}

    



```



If you would like to use your own implementation of the SseSessionManager, then you need to add the following init params to your servlet defenition



```xml



    

        me.kisoft.jesse.session.manager

        {Class name of session manager}

    



```



You can also set the interval for the Keep-Alive, by using this paramter



```xml



    

        me.kisoft.jesse.session.keepalive.interval

        {interval in secconds}

    



```



You can also specify the domains that are allowed to access the event stream, by setting this parameter. Otherwise, it defaults to the domain that made the request(effectively all domains)



```xml



    

        me.kisoft.jesse.session.domains

        {comma,separated,domain,names}

    



```



Aditionally, you can add mappers for MediaTypes, by adding this to the web.xml



```xml



    

        me.kisoft.jesse.feature

        {comma,seperated,features,class,names}

    



```

You can add your own custom mappers by implementing the ```MapperFeature``` interface.



For example,this is a complete configuration with a custom session manager and the Jackson Mapper



```xml



    

         EventStream Endpoint 

        me.kisoft.jesse.JesseServlet

        

            me.kisoft.jesse.session.manager

            me.kisoft.core.sse.BusrSessionManager

        

        

            me.kisoft.jesse.session.keepalive.enabled

            true

         

         

            me.kisoft.jesse.feature

            me.kisoft.jesse.feature.JacksonMapperFeature

        

         1

         true

    

    

         EventStream Endpoint 

        /event/*

    



```



And Thats it! you are now ready to go



# Usage



## Sending Sse Events



```java



 DefaultSessionManager.broadcastAll(SseEvent.getBuilder()

                            .event("test")

                            .id(33)

                            .retry(500)

                            .mediaType(MediaType.APPLICATION_JSON)

                            .data(notificationData)

                            .build())



```



Lets break this code down



``` DefaultSessionManager ``` is the default implementation of the session manager, which is used by default if no custom SessionManager is provided.

It stores all active sessions in a list, and you can broadcast events to groups of sessions, individual sessions, or all sessions.



``` SseEventBuilder ``` is a utility class to build a new ``` SseEvent ```. ```event("test")``` sets the type of the event to "test", ```mediaType(MediaType.APPLICATION_JSON)``` sets the media type to JSON,  ``` id(33) ``` sets the event id to "33",  ``` retry(500) ``` sets the retry interval to 500ms, ``` data(notificationData) ``` sends notification as the event data, and ``` build() ``` creates the ``` SseEvent ``` based on the previous functions. The resulting event would be



```

id: 33

event: test

retry: 500

data:  {"parameter1":"value1","parameter2":"value2",.....,"parametern":"valuen"}



```



## Custom Session Managers



a custom session manager can be created by extending the ``` SseSessionManager ``` class.

By default, the sessions are not stored anywhere, so it is up to you to store them in whatever way you see fit.



The following methods are mandatory to implement



``` onOpen(SseSession sseSession) throws WebApplicationExceptoion ``` : This method is called when a new session is opened. ``` WebApplicationException ``` will terminate this session with the corrseponding Http Response code.



``` onClose(SseSession sseSession) throws WebApplicationExceptoion ``` : This method is called when a session is being closed. will terminate this session. Should not throw any exceptions



``` onError(SseSession sseSession)``` : This method is called if there is an error during opening the session. It should be used for logging/checking if resources were cleared.



## Custom Feature Mapping



a custom feature mapper can be created by implementing the ```MapperFeature``` interface. As a note, feature registration is global for Jesse, meaning that all your SseSessions will use the same mapper modules. You need to

implement these functions



``` serialize(Object object) throws WebApplicationException``` converts the Object into a String form for this mapper feature.



``` getMediaTypeString() ``` returns the String representation of the ```MediaType``` that the Mapper will handle.



``` getMediaType() ``` returns the JAX-RS MediaType representation that the Mapper will handle.



For now, MapperFeatures are restricted to handling the JAX-RS MediaTypes only, but that might change in the future.



# Building



Nothing fancy, just clone and build using the pom.xml file. Unit tests are included