Chat engine servlet v. 1.3


Servlet provides server-side engine with open API for creating and deploying web chats. It is not a chat itself but a complete engine lets you create chat rooms and users, post and request messages etc. Current version supports REST API and outputs data in JSON, so your actual chat could be programmed with any language including JavaScript. And you can even deploy chats on mobile web with this engine. How to use it:

1) download chatengine.jar and save it in WEB-INF/lib

2) describe ChatEngine servlet in web.xml file.  


    <servlet>
     <servlet-name>ChatEngine</servlet-name>
     <servlet-class>com.jsos.chat.ChatEngineServlet</servlet-class>
    </servlet>

3) define a mapping:
 


    <servlet-mapping>
     <servlet-name>ChatEngine</servlet-name>
     <url-pattern>/servlet/ChatEngine/*</url-pattern>
    </servlet-mapping>

engine accepts some parameters as a part of request URI, so your requests look so for example:
 


http://your_host/servlet/ChatEngine/engine/restart
http://your_host/servlet/ChatEngine/users/create etc.

or (if you are deploying Chat engine as a part of some web application):
 


http://your_host/app_name/servlet/ChatEngine/engine/restart
http://your_host/app_name/servlet/ChatEngine/users/create etc.

app_name here is a name for your web application.

The model. Chat engine supports rooms (separate spaces). Each room has got an unique ID and name. One room (ID is 0) exists always by default. Chat's user can join to any room. Names and ID's within the room should be unique. Published message is a plain text. You can publish private messages (addressed to some user only) - just start the message (text) from @user_name pattern.

JSON API returns an object with two fields:

code - a status code for the request. 1 - success
message - for the failed requests contains an error message, otherwise it is an object (array of objects) with the results.

Here is a full list of accepted commands:

version

Returns a version info.

URL: /engine/version

Formats: JSON

HTTP Method: GET

Requires Authentication false

Parameters: none

---------------------------------------

restart

Restarts the engine.

URL: /engine/restart

Formats: JSON

HTTP Method: GET

Requires Authentication false

Parameters: none

---------------------------------------

create room

create a new chat room.

URL: /rooms/create

Formats: JSON

HTTP Method: GET

Requires Authentication false

Parameters:

  • name - a name for the room

Fields in the response:

code - a status code
message - error message or ID for the created room
name - a name for the room

---------------------------------------

delete room

delete a room.

URL: /rooms/delete

Formats: JSON

HTTP Method: GET

Requires Authentication false

Parameters:

  • name - a name for the room OR
  • id - an ID for the room

---------------------------------------

clear room

clear a room (delete all messages).

URL: /rooms/clear

HTTP Method: GET

Requires Authentication false

Parameters:

  • name - a name for the room OR
  • id - an ID for the room

---------------------------------------

list rooms

get a list of rooms

URL: /rooms/list

HTTP Method: GET

Requires Authentication false

Parameters: none

Fields in the response:

code - a status code
message - an array. Each element describes a room info:
  id - an ID for the room
  name - a name for the room
  usr_counter - how many users are in
  msg_counter - how many messages

---------------------------------------

room info

get room info

URL: /rooms/info

HTTP Method: GET

Requires Authentication false

Parameters:

  • name - a name for the room OR
  • id - an ID for the room

Fields in the response:

code - a status code
message - error message or an object:
  id - an ID for the room
  name - a name for the room
  usr_counter - how many users are in
  msg_counter - how many messages

---------------------------------------

join to chat

add user to room

URL: /users/login

HTTP Method: GET

Requires Authentication false

Parameters:

  • name - a name for the user
  • roomName - a name for the room OR
  • roomId - an ID for the room

Fields in the response:

code - a status code
message - error message or an ID for the user

---------------------------------------

leave the chat

disconnect user from chat

URL: /users/logout

HTTP Method: GET

Requires Authentication false

Parameters:

  • name - a name for the user
  • roomName - a name for the room OR
  • id - an ID for the room

---------------------------------------

list of users

get list of users

URL: /users/list

HTTP Method: GET

Requires Authentication false

Parameters:

  • roomName - a name for the room OR
  • roomId - an ID for the room

Fields in the response:

code - a status code
message - an array. Each element describes an user info:
  id - an ID for the user
  name - a name for the user
  dateJoin - a timestamp for the login date
  dateLast - a timestamp for the lat message date
  optional list of attributes (see below)

---------------------------------------

user info

get user info

URL: /users/info

HTTP Method: GET

Requires Authentication false

Parameters:

  • name - a name for the user OR
  • id - an ID for the user
  • roomName - a name for the room OR
  • roomId - an ID for the room

also you can optionally pass additional attributes from this user. Just set a pair in your request: attribute_name and attribute_value

Fields in the response:

code - a status code
message - an object:
  id - an ID for the user
  name - a name for the user
  dateJoin - a timestamp for the login date
  dateLast - a timestamp for the lat message date
  optional list of attributes (see above)

---------------------------------------

add message

post a new message

URL: /messages/create

HTTP Method: GET, POST

Requires Authentication false

Parameters:

  • name - a name for the user OR
  • id - an ID for the user
  • roomName - a name for the room OR
  • roomId - an ID for the room
  • txt - a text for the message

Fields in the response:

code - a status code
message - error message or message ID

---------------------------------------

get messages

get last messages

URL: /messages/get

HTTP Method: GET

Requires Authentication false

Parameters:

  • roomName - a name for the room OR
  • roomId - an ID for the room
  • sinceId - an optional parameter. Describes an initial ID for the search

Fields in the response:

code - a status code
message - an array. Each element describes a message info:
  id - an ID for the message
  txt - a text for the message
  date - a timestamp for the message
  from - user info
  to - user info

---------------------------------------

and here you can download a JavaScript based chat you can use as a basic example for Chat engine - simplechat.jsp

For downloading:

servlet: chatengine.jar  
 

 © Coldbeans    Comments?
 

See also JSOS - the largest collection of servlets and filters.

Also in JSOS: