portal
An interface used to manage socket.
Method
open(url, [options])
Opens a socket and returns it.
- url (type: String): An URL where the connection is established.
-
options (type: Object): A plain object that configures the socket.
-
transports (type: Array, default:
["ws", "sse", "stream", "longpoll"]
)An array of the transport ids, in order of index. A guide to choose a transport list:
- Add
ws
as a first element of the list if your portal server supportsws
transport. - Add fallback transports.
sse
andstream
for streaming.longpoll
for long polling.
For details about features and issues of fallback transports, see the transport interface section.
- Add
-
timeout (type: Number, default:
false
)A timeout value in milliseconds. The timeout timer starts at the time the
connecting
event is fired. If the timer expires before the connection is established, theclose
event is fired. The valuefalse
means no timeout. -
heartbeat (type: Number, default:
false
)A heartbeat interval value in milliseconds. A opened socket continuously sends a heartbeat event to the server each time the value has elapsed. Actually, the socket sends the event 5 seconds before the heartbeat timer expires to wait the server’s echo. If the event echoes back within 5 seconds, the socket reset the timer. Otherwise, the
close
event is fired. For that reason, the value must be larger than5000
and the recommended value is20000
. The valuefalse
means no heartbeat. -
lastEventId (type: Number, default:
0
)A initial value for the last event id to be passed to the
urlBuilder
function. Note that this is valid only when the server assures the message-sending order. -
sharing (type: Boolean, default:
false
)A flag indicating that connection sharing across tabs and windows is enabled or not. If this is turned on, as long as the cookie is enabled, the socket object will try to automatically share a real connection if there is no corresponding one, and find and use a shared connection if it exists within the cookie’s scope. Note that if the web page or computer becomes horribly busy, a newly created socket might establish a physical connection.
-
prepare (type: Function(Function connect(), Function cancel(), Object options))
A function that is called before the socket tries to connect and determines whether to allow the socket to try to connect or not when a physical connection is needed. The function receives three arguments: The callback to connect, the callback to cancel and merged options object. You can use this when the opening handshake is needed, the user is needed to be authenticated and the option is needed to be managed by the server. The default function simply executes the connect function. Note that if the option
sharing
istrue
and there is an available shared connection, this function will not be executed. -
reconnect (type: Function(Number lastDelay, Number attempts))
A function to be used to schedule reconnection. The function is called every time after the
close
event is fired and should return a delay in milliseconds orfalse
not to reconnect. The function receives two arguments: The last delay in milliseconds used ornull
at first and the total number of reconnection attempts. This can be disabled by setting the value tofalse
. The default function returns 500 at first and then the double of the last delay of each call. -
idGenerator (type: Function())
A function to be used to generate a socket id. The function should return a string and the returned string should be unique enough for the server to use it as a identifier of the connection until the connection disconnects. The default function generates a random UUID based on the
Math.random
. Note that the default function is enough for the transient use, but if you are going to use it permanently e.g. a persistent field of persistent entity, you have to consider to introduce higher quality of UUID generator based on thecrypto.getRandomValues
or handshake request utilizingprepare
function. -
urlBuilder (type: Function(String url, Object, params, String when))
A function to be used to build an url within specific goal. The function should return an effective url including the given parameters. The function accepts three arguments: The absolute form of the given url, the params object according to the purpose and the purpose of request. The default function appends a query string representation of the
when
and theparams
to the url.when
can be one of the following valuesopen
: to establish a connection. The params hasid
,transport
,heartbeat
,lastEventId
and_
for anti-caching. Additionaly if the transport islongpolljsonp
,callback
is also included to the params.poll
: In the long polling, thewhen
of first request isopen
and that of further requests arepoll
. The params hasid
,transport
,lastEventIds
and_
for anti-caching. Additionaly if the transport islongpolljsonp
,callback
is also included to the params.abort
: to notify the server of disconnection. The params hasid
and_
for anti-caching.
-
params (type: Object)
An additional parameters to be merged with the default parameters and passed to the
urlBuilder
function. The first-depth property’s name should be the one of the possiblewhen
. Functions will be called with no arguments. -
inbound (type: Function(String data))
A function to be used to convert data sent by the server into an event object. Every data sent by the server invokes the function and it should return an event object having
type
. The event object can have the following optional properties:id
(an event id),reply
(if true then a reply event will be sent) anddata
(the first argument of corresponding handlers). The default function parses the data as JSON and returns the parsed value because the server sends a JSON string representing the event as data by default. Note that binary data is considered as amessage
event without calling the function. -
outbound (type: Function(Object event))
A function to be used to convert an event object into data to be sent to the server. Every data to be sent to the server invokes the function and it should return a string. The given event object has
id
(an event id),type
(a event type which the user input),reply
(if true then a reply event will be received),socket
(a socket id) anddata
(data which the user input) properties. The default function serializes the event object into JSON and returns it because the server accepts a JSON string representing the event as data by default. Note that binary data is sent as it is instead without calling the function. -
notifyAbort (type: Boolean, default:
false
, applicable transport: transport over HTTP protocol)This option helps the server detect disconnection of HTTP connection when the server does not support to detect disconnection. If it’s
true
, when theclose
method is called, simple HTTP GET request whose url is generated byurlBuilder
with the abortwhen
. For example, since browser can’t abort script tag used inlongpolljsonp
transport, the only way to abort it is for server to end the response. This option can be used in that case. If multiple connections vialongpolljsonp
are established without this support, browser could not send any request due to the restriction of the number of simultaneous connections. -
credentials (type: Boolean, default:
false
, applicable transport:sse
,stramxhr
,longpollajax
)If the browser implements Cross-Origin Resource Sharing and the value is
true
, user credentials such as cookies and HTTP authentication is to be included in a cross-origin connection. -
xdrURL (type: Function(String url), applicable transport:
streamxdr
,longpollxdr
)A function used to add session information to an url. For security reasons, the
XDomainRequest
excludes cookie when sending a request, so the session cannot be tracked by cookie. However, if the server supports session tracking by url, it is possible to track the session by rewriting the url. If you wish to disable applied transports, set the value tofalse
or function returningfalse
. The default function modifies the url only ifJSESSIONID
orPHPSESSID
cookie exists. For example, If the url isurl?k=v
andJSESSIONID
cookie exists, the url becomesurl;jsessionid=${cookie.JSESSIONID}?k=v
, and ifPHPSESSID
cookie exists, the url becomesurl?PHPSESSID=${cookie.PHPSESSID}&k=v
. Otherwise, it returnsfalse
. -
streamParser (type: Function(String chunk), applicable transport:
streamxhr
,streamiframe
,streamxdr
)A function to parse stream response to find data from chunks. The function receives chunk and should return an array of data and the returned array’s length varies with each chunk because a single chunk may contain a single data, multiple data or a fragment of a data. The default function parses a chunk according to the event stream format, but deals with the data field only.
-
find()
Returns the first socket.
find(url)
Returns the socket which is mapped to the given url.