freebird-transport
The transport for freebird REQ/RSP/IND message transmission
Table of Contents
1. Overview
This module is the abstract class for developers to create their own transportation to communicate with freebird framework. This class inherits from EventEmitter which will emit a 'message'
event when a message arrives.
- In this document,
transp
will be used to denote the instance of this class. - In the following methods, the argument
msg
must be an object in the shape of{ clientId, data }
, where thedata
property is mandatory and should be a string or a buffer, and theclientId
property is optional and should be a string or a number if given. One can attach an identifier, like a client id, tomsg.clientId
for message multiplexing.
For implementers:
To have a valid transp
, two things must be done by the implementor.
- Must implement the
transp._send(msg, callback)
method on the transport instance. - Must call the
transp.receive(msg)
method to let the transport instance know that there a message comes in. Callingtransp.receive(msg)
will induce a'message'
event triggered on the transport instance.
For users:
To use the transport object:
- Call
transp.send(msg, callback)
to send message out. It wil throw if_send()
was not provided by the implementer. - Listen to
'message'
event to receive messages.
2. APIs and Events
- Constructor
- Implementer provides
- Implementer calls
- User calls
- User listens to events
new Transport()
Create the transport instance.
Arguments:
- none
Returns:
- (Object):
transp
, instance of this class
Examples:
var Transport = ;var transp = ;
._send(msg, callback)
The implmentation of sending out the message.
Arguments:
msg
(Object): The message to trasmit out is a string or a buffer attached todata
property of this object.callback
(Function):function (err, bytes) { ... }
. This err-first callback should be called after message sent off. The argumentbytes
tells how many bytes were sent.
Returns:
- none
Examples:
var transp = ; transp { var bytes; if typeof msgdata === 'string' msgdata = msgdata; if !Buffer return ; bytes = msgdatalength; // ... implemention of message sending // Finally, call callback ;};
._broadcast(msg, callback)
The implmentation of broadcasting the message. This is optional, it will use transp.send(msg, callback)
internally by default if implementation is not given. This broadcasting method is used to send an indication to multiple remote clients.
Arguments:
msg
(Object): The message to broadcast out is a string or a buffer attached todata
property of this object.callback
(Function):function (err, bytes) { ... }
. This err-first callback should be called after message sent off. The argumentbytes
tells how many bytes were sent.
Returns:
- none
Examples:
var transp = ; transp { var bytes; if typeof msgdata === 'string' msgdata = msgdata; if !Buffer return ; bytes = msgdatalength; // ... implemention of message broadcasting // Finally, call callback ;};
.send(msg, callback)
Call this method to send the message off.
Arguments:
msg
(Object): The message to trasmit out must be a string or a buffer which should be attached todata
property of this object.callback
(Function):function (err, bytes) { ... }
. Get called after message sent off. The argumentbytes
tells how many bytes were sent.
Returns:
- none
Examples:
var transp = ; // assume transp._send was implemented // call transp.send() to send messagetransp;
.broadcast(msg, callback)
Call this method to broadcast the message.
Arguments:
msg
(Object): The message to trasmit out must be a string or a buffer which should be attached todata
property of this object.callback
(Function):function (err, bytes) { ... }
. Get called after message sent off. The argumentbytes
tells how many bytes were sent.
Returns:
- none
Examples:
var transp = ; transp;
.receive(msg[, callback])
The Implemntor should call this method to inform the message arrival.
Arguments:
msg
(Object): This must be an object with adata
property that holds the received message.callback
(Function):function (err) { ... }
. Optional. Get called after message sent off.
Returns:
- none
Examples:
var transp = ; // Implemntor calls transp.receive() when message arrivesfoo;
.on('message', function (msg) {})
The user can listen to the 'message'
event to receive the message.
Arguments of the listener
msg
(Object): This must be an object with adata
property that holds the received message of a string or a buffer.
Examples:
var transp = ; transp;
.on('unhandledMessage', function (msg) {})
The user can listen to the 'unhandledMessage'
event to receive the message that is not processed by the freebird.
Arguments of the listener
msg
(Object): This must be an object with adata
property that holds the received message of a string or a buffer.
Examples:
var transp = ; transp;
3. TCP Server/Client Example
3.1 TCP Server
var net = Transport = ; var transp client; transp = ; server = net; server; // Implementaion of _sendtransp { var bytes; if typeof msg !== 'object' return ; if typeof msgdata === 'string' msgdata = msgdata; if !Buffer return ; bytes = msgdatalength; if !client return ; client; ;}; moduleexports = transp;
3.2 TCP Client
var net = Transport = ; var transp client; transp = ;client = net; client; // Message receivedclient; moduleexports = transp;