Wsmessenger Project
Wsmessenger is a long connection message middleware based on websocket protocl. It builds on netty that make it work well in high concurrency circumstances. It can be used to create PUSH service for android app. It also can be used to create monitor tools for web cluster.
Quit start guide
- Import dependencies
- Set up server side
- Set up client side
- Send message
- Implement customized message
- Listen message
- Listen lifecycle
- Advanced configuration
Import dependencies
Here we use MAVEN to manage project's dependencies.
For server side, you should import wsmessenger-server
.
<dependency>
<groupId>space.chensheng.wsmessenger</groupId>
<artifactId>wsmessenger-server</artifactId>
<version>1.5.0</version>
</dependency>
For client side, you should import wsmessenger-client
.
<dependency>
<groupId>space.chensheng.wsmessenger</groupId>
<artifactId>wsmessenger-client</artifactId>
<version>1.5.0</version>
</dependency>
To implement customized messages, you should import wsmessenger-message
<dependency>
<groupId>space.chensheng.wsmessenger</groupId>
<artifactId>wsmessenger-message</artifactId>
<version>1.5.0</version>
</dependency>
Set up server side
ServerBootstrap
is used to set up the server side. The server will listen 2046
port by default.
Simply set up the server side.
WsMessengerServer server = new ServerBootstrap().build();
server.start();
If you want to listen server's lifecycle and received messages, listeners can be added when setting up the server side.
WsMessengerServer server = new ServerBootstrap()
.addLifecycleListener(new MyServerLifecycleListener())
.addMessageListener(new MyTextMessageListener())
.build();
server.start();
Set up client side
ClientBoostrap
is used to set up the client side. Once client starts, it will establish a long connection to server through websocket protocol.
Before setting up the client side, you should create a config file wsmessenger-client.properties
in your project. The config should specify clientId
and serverUrl
.
clientId=your-wsmessenger-client-id
serverUrl=ws://127.0.0.1:2046
Simply set up the client side.
WsMessengerClient client = new ClientBootstrap().build();
client.start();
If you want to listen client's lifecycle and received messages, listeners can be added when setting up the client side.
WsMessengerClient client = new ClientBootstrap()
.addLifecycleListener(new MyClientLifecycleListener())
.addMessageListener(new MyTextMessageListener())
.build();
client.start();
Send message
Server and client can comunicate with each other by sending message.
In server side, WsMessengerServer
is used to send message.
TextMessage message = new TextMessage();
message.setContent("This is a text message sent to client!")
server.sendMessage(message, clientId);
In client side, WsMessengerClient
is used to send message.
TextMessage message = new TextMessage();
message.setContent("This is a text message sent to server!")
client.sendMessage(message, null);
Server side's sender APIs
API | description |
---|---|
sendMessage(WsMessage message) | Send message to all connected clients. |
sendMessage(WsMessage message, String clientId) | Send message to specific client. |
sendMessageReliably(WsMessage message, String clientId) | Send message to specific client, and add message to pending queue if client is unavailable. |
sendWaitingMessage(WsMessage message, String clientId, WaitingCallback callback) | Send message to specific client, and waiting for client's response. Trigger callback when receiving response or timeout. |
sendWaitingMessage(WsMessage message, String clientId, WaitingCallback callback, long timeout) | Send message to specific client, and waiting for client's response in specific timeout milliseconds. Trigger callback when receiving response or timeout. |
sendWaitingMessageReliably(WsMessage message, String clientId, WaitingCallback callback) | Send message to specific client, and waiting for client's response. Trigger callback when receiving response or timeout. Add message to pending queue if client is unavailable. |
sendWaitingMessageReliably(WsMessage message, String clientId, WaitingCallback callback, long timeout) | Send message to specific client, and waiting for client's response in specific timeout milliseconds. Trigger callback when receiving response or timeout. Add message to pending queue if client is unavailable. |
sendWaitingMessageReliablyWithRetry(WsMessage message, String clientId) | Send message to specific client, and waiting for client's response. Retry 3 times until receiving success response. Add message to pending queue if client is unavailable. |
sendWaitingMessageReliablyWithRetry(WsMessage message, String clientId, int retry) | Send message to specific client, and waiting for client's response. Retry specific times until receiving success response. Add message to pending queue if client is unavailable. |
Client side's sender APIs
API(serverId is always null) | description |
---|---|
sendMessage(WsMessage message) | send message to server |
sendMessage(WsMessage message, String serverId) | send message to server |
sendMessageReliably(WsMessage message, String serverId) | Send message to server, and add message to pending queue if server is unavailable. |
sendWaitingMessage(WsMessage message, String serverId, WaitingCallback callback) | Send message to server, and waiting for server's response. Trigger callback when receiving response or timeout. |
sendWaitingMessage(WsMessage message, String serverId, WaitingCallback callback, long timeout) | Send message to server, and waiting for server's response in specific timeout milliseconds. Trigger callback when receiving response or timeout. |
sendWaitingMessageReliably(WsMessage message, String serverId, WaitingCallback callback) | Send message to server, and waiting for server's response. Trigger callback when receiving response or timeout. Add message to pending queue if server is unavailable. |
sendWaitingMessageReliably(WsMessage message, String serverId, WaitingCallback callback, long timeout) | Send message to server, and waiting for server's response in specific timeout milliseconds. Trigger callback when receiving response or timeout. Add message to pending queue if server is unavailable. |
sendWaitingMessageReliablyWithRetry(WsMessage message, String serverId) | Send message to specific server, and waiting for server's response. Retry 3 times until receiving success response. Add message to pending queue if server is unavailable. |
sendWaitingMessageReliablyWithRetry(WsMessage message, String serverId, int retry) | Send message to specific server, and waiting for server's response. Retry specific times until receiving success response. Add message to pending queue when server is unavailable. |
Implement customized message
Developer can implement customized message, and send it between server and client. To implement a customized message, you should extend WsMessage
. The following is an example:
import space.chensheng.wsmessenger.message.component.WsMessage;
public class UserInfoMessage extends WsMessage {
private int userId;
private String userName;
public int getUserId() {
return userId;
}
public void setUserId(int userId) {
this.userId = userId;
}
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName;
}
}
UserInfoMessage message = new UserInfoMessage();
message.setUserId(123);
message.setUserName("wsmessenger");
client.sendMessage(message, null);
Listen message
Message listeners can be added to listen specific message. Developer should implement your own MessageListener
.
In server side, ServerMessageListener
is used to implement. The following is an example listening TextMessage
:
public class MyTextMessageListener extends ServerMessageListener<TextMessage> {
@Override
protected void onMessage(TextMessage message, ClientInfo clientInfo, MessengerServer server) {
String replyContent = "Hello client, i have received your text message " + message.getContent();
TextMessage relyMessage = new TextMessage();
replyMessage.setContent(replyContent);
server.sendWaitingMessageReliablyWithRetry(replyMessage, clientInfo.getClientId());
}
}
In client side, ClientMessageListener
is used to implement. The following is an example listening TextMessage
:
public class MyTextMessageListener extends ClientMessageListener<TextMessage> {
@Override
protected void onMessage(TextMessage message, MessengerClient client) {
String replyContent = "Hello server, i have received your text message " + message.getContent();
TextMessage relyMessage = new TextMessage();
replyMessage.setContent(replyContent);
client.sendWaitingMessageReliablyWithRetry(replyMessage, null);
}
}
Listen lifecycle
Lifecycle listeners can be added to listen server and client's lifecycle. Developer should implement your own LifecycleListener
.
In server side, ServerLifecycleListener
is used to implement. The following is an example:
public class MyServerLifecycleListener extends ServerLifecycleListener {
@Override
public void onServerStart(MessengerServer server) {
//server is started
}
@Override
public void onClientConnect(ClientInfo clientInfo, MessengerServer server) {
//client is connected
}
@Override
public void onClientDisconnect(ClientInfo clientInfo, MessengerServer server) {
//client is disconnected
}
}
In client side, ClientLifecycleListener
is used to implement. The following is an example:
public class MyClientLifecycleListener extends ClientLifecycleListener {
@Override
public void onClientConnect(MessengerClient client) {
//success to connect server
}
@Override
public void onClientStart(MessengerClient client) {
//client is started
}
@Override
public void onClientStop(MessengerClient client) {
//client is stopped
}
@Override
public void onClientRestart(MessengerClient client) {
//client restarts
}
}
Advanced configuration
There are serveal advanced configurations for server and client.
In server side, you can create a config file named wsmessenger-server.properties
in your project. It is optional. The following table shows configuration details:
property name | property value |
---|---|
serverId | Default is wsmessenger-server . The server's id. The serverId will be set to message when sending message to client. |
serverPort | Default is 2046 . The port listened by server. |
pendingClientMaxCount | Default is 100 . Server will keep messages in pending queue for unavailable clients. If unavailable client's size exceed max count, new messages will not keep for new unavailable clients. |
pendingClientMaxMsg | Default is 100 . The max number of messages kept in pending queue for single unavailable client. |
pendingClientTimeoutMillis | Default is 3600000 . Time unit is millisecond. If an unavailable client sitting in pending queue exceeds pendingClientTimeoutMillis , it will be removed from the pending queue. |
pendingClientTimeoutCheckerIntervalMinutes | Default is 5 . Time unit is minute. The interval minutes to check whether unavailable clients is timeout or not. |
maxPendingMsg | Default is 1000 . The total number of messages kept in pending queue for all unavailable clients. |
acceptorThreadSize | Default is 1 . The number of threads to accept connections from clients. One thread is enough. |
ioThreadSize | Default is 4 . The number of threads to read io from clients. |
businessThreadSize | Default is 8 . The number of threads to execute business tasks. |
heartbeatIntervalSeconds | Default is 60 . Time unit is second. The interval seconds to send heartbeat to clients. |
heartbeatMaxFail | Default is 3 . The max fail times of heartbeat. The long connection to client will be closed if heartbeat fail specific times. |
soBacklog | Default is 3074 . The same as socBacklog in TCP/IP. |
allowHalfClosure | Default is false . The same as allowHalfClosure in TCP/IP |
waitingMsgTimoutMillis | Default is 120000 . Time unit is millisecond. The timeout to wait receiver's response for message that needed response. If timeout to wait resposne, the timeout callback will be triggered. |
waitingMsgMaxSize | Default is 1000 . The number of messages kept in waiting response queue. New waiting inforamtion will not be added to waiting queue if waiting size execceds the max size. |
maxContentLen | Default is 1048576 . Unit is byte. The max size of message. |
maxFrameSize | Default is 1048576 . Unit is byte. The max size of message. |
retryTaskMaxSize | Default if 1000 . The max number of retry tasks kept in retry queue. New retry task will be dropped if the retry queue execceds max size. |
In client side, you must create a config file named wsmessenger-client.properties
in your project. It is required. The following table shows configuration details:
property name | property value |
---|---|
clientId | REQUIRED. The messenger client id. Server will identify different client by clientId . |
serverUrl | REQUIRED. The server url client will connect to. Just like this ws://127.0.0.1:2046 |
ioThreadPoolSize | Default is 1 . The number of threads ro read io from server. |
businessThreadPoolSize | Default is 4 . The number of threads to execute business tasks. |
heartbeatSeconds | Default is 60 . Time unit is second. The interval seconds to send heartbeat to server. |
heartbeatMaxFail | Default is 3 . The max fail times of heartbeat. The long connection to server will be closed if heartbeat fail specific times. |
reconnectMillis | Default is 10000 . Time unit is milliseconds. The interval milliseconds to reconnect server when server is unavailable. |
maxPendingMsg | Default is 1000 . The max number of messages kept in pending queue for unavailable server. |
waitingMsgTimoutMillis | Default is 120000 . Time unit is millisecond. The timeout to wait receiver's response for message that needed response. If timeout to wait resposne, the timeout callback will be triggered. |
waitingMsgMaxSize | Default is 1000 . The max number of messages kept in waiting response queue. New waiting inforamtion will not be added to waiting queue if waiting size execceds the max size. |
maxContentLen | Default is 1048576 . Unit is byte. The max size of message. |
maxFrameSize | Default is 1048576 . Unit is byte. The max size of message. |
retryTaskMaxSize | Default if 1000 . The max number of retry tasks kept in retry queue. New retry task will be dropped if the retry queue execceds max size. |