Messaging Service Guide

What you'll build

You will build a messaging service that enables persisting and fetching messages 

What you’ll need

An Integrated Developer Environment (IDE)

Popular choices include IntelliJ IDEA, Spring Tools, Visual Studio Code, or Eclipse, and many more.

A Java™ Development Kit (JDK) installed. We recommend AdoptOpenJDK version 11 or version 14.

Running PostgreSQL database with ‘FlexiCore’ database acceesible by user ‘FlexiCore’ identified by password ‘FlexiCore’

Running MongoDB database

FlexiCore executable at /home/FlexiCore or any other location , FlexiCore’s latest executable can be obtained from the release section.

Environment can be easily installed using Wizzdi Setup , latest Wizzdi Setup is available here.

Phase 1: Basic Messaging Service

at this phase we will create a service allowing users to save and fetch messages.

Step 1.a: Design Basic Model

managing entities for this phase:

  1. Users – we can use the existing User model FlexiCore provides to model message source and target
  2. Message – we need to model a single message , this object will contain a from/to users the contant and the subject of the message


Create a new Maven Project with the following structure:

update your pom.xml from here

Step 1.b: Create Message Entity

Open up the project in your IDE and create the file in the src/main/java/com/wizzdi/messaging/model folder. Now change the contents of the file by adding the extra method and annotations shown in the code below. You can copy and paste the code or just type it.

  1. Our Message object inherits from Baseclass since we want to be able to govern permissions for it
  2. content field is annotated with @Lob annotation since we want the underlaying database to create this field in a format suitable for long strings (rather than limited space varchar)

Step 1.c: Create Persistence.xml

copy persistence.xml content from here.

this will allow automatic generation of JPA metamodels required to implement Criteria API based queries.

Step 1.d: install messaging model

./mvn install

./cp target/messaging-model-1.0.0-jar /home/FlexiCore/entities

Step 1.e: create Message service plugin

create a maven project with the following structure:

update your pom.xml from here

Step 1.f: Create Message service request objects

lets define objects that will be consumed by our api:

  1. MessageCreate – this object will contain all required details for creating a message ( from user , to user , content and subject) it will also inherit from BaseclassCreate object as we would like to extend Baseclass capabilities
  2. MessageUpdate – this object will extend MessageCreate object and id of the message to update
  3. MessageFilter – this object will be sent by the client when fetching messages and will contain filtering options on messages

Step 1.g: Create Message Repository

lets define the repository that will be used to fetch and save messages from database.

  1. the repository is annotated by
    •  @Extension annotation to allow FlexiCore to load it as a plugin 
    • @PluginInfo annotation to allow future versioning support
    • @Component annotation to let spring know it is a bean.
  2. the repository class extends AbstractRepositoryPlugin which provides easy method for access control and out of the box methods for persisting objects
  3. the repository exposes methods for listing and counting messages both are calling the addMessagePredicates which adds the required predicates , all access control predicates are automatically added when countAllFiltered and getAllFiltered are called
  4. addMessagePredicates uses JPA Criteria Api to filter data based on MessageFilter object we have created in previous phase.

Step 1.h: Create Message Service

lets define the service that will be used by other plugins and REST api (or any other API implementations for that matter)

Step 1.h: Create Message REST Service

lets define the REST service that will expose REST api that our clients will use:

Phase 2: Add WebSoscket Support

currently clients will have to poll for new messages which will cause excessive CPU usage and bad experience for the users since messages will only update during the polling interval , to solve that we will add a Web Socket endpoint to push new messages to clients.

Step 2.a: Change Message-Service Structure

message service v1.1.0 structure

Step 2.b: Create Web Socket Messages Classes

currently we will only support a single new web socket message called NewMessage but we will leave room for more message types that implement IWSMessage interface.

Registration of the new type is done by a component listening on PluginsLoadedEvent – an event sent after plugins beans have been registered.

Step 2.c: Create Web Socket Message Encoder , Message WebSocket and Message Sender

we are using Jackson’s ObjectMapper to serialize the messages.

the @ServerEndpoint annotation registers this class as a websocket endpoint and registers the MessageMessageEncoder class as the encoder for outgoing messages , we have added a path parameter place holder so the authnetication key can be provided by clients.

the @Protected annotation is being used to automatically autheticate the incoming authetication key and push the SecurityContext into the sessions properties. once a client connects we add it to a map of running sessions.

the MessageSender will listen to events of type IWSMessage and will send them to relevant sessions ( this is determined by the getTargetIds method on the message)

Step 2.d: Send NewMessage Event

now we will need to send the NewMessage event when a message is created by updating createMessage method in MessageService :