ballerina/socket module
Module overview
This module provides an implementation for connecting to a remote socket server or acts as a server for an incoming socket request. The module facilitates two types of endpoints called Client
and Listener
.
Samples
Listener endpoints
The sample given below shows how a listener is used to listen to the incoming socket request. The onAccept(socket:Caller)
resource function gets invoked when a new client is connected. The new client is represented using the socket:Caller
.
onReadReady(socket:Caller, byte[])
resource gets invoked once the remote client sends some data and onClose(socket:Caller)
is invoked once the client is departs.
import ballerina/io;
import ballerina/socket;
listener socket:Listener server = new ({ port:61598 });
service echoServer on server {
resource function onAccept (socket:Caller caller) {
io:println("Join: ", caller.remotePort);
}
resource function onReadReady (socket:Caller caller, byte[] content) {
_ = caller->write(content);
}
resource function onClose(socket:Caller caller) {
io:println("Leave: " + caller.remotePort);
}
resource function onError(socket:Caller caller, error er) {
io:println(er.reason());
}
}
Client endpoints
Client endpoints are used to connect to and interact with a socket server. The client can only send the data to the server. Client's callbackService
needs to retrieve the data from the server and do multiple requests/responses between client and the server.
import ballerina/io;
import ballerina/socket;
public function main() {
socket:Client socketClient = new({host: "localhost", port: 9999, callbackService: ClientService});
string msg = "Hello Ballerina\n";
byte[] c1 = msg.toByteArray("utf-8");
_ = socketClient->write(c1);
}
service ClientService = service {
resource function onConnect(socket:Caller caller) {
io:println("connect: ", caller.remotePort);
}
resource function onReadReady (socket:Caller caller, byte[] content) {
io:println("client write");
_ = caller->write(content);
}
resource function onClose(socket:Caller caller) {
io:println("Leave: ", caller.remotePort);
}
resource function onError(socket:Caller caller, error er) {
io:println(er.reason());
}
};
Type Definitions
Type | Values | Description | |
---|---|---|---|
Caller | Client | Represents caller object in socket service resources and client callback service resources. This has all the remote functions expose by socket:Client. |
Records Summary
Record | Description | ||
---|---|---|---|
ClientConfig | Configuration for socket client endpoint. | ||
ListenerConfig | Represents the socket server configuration. | ||
SocketError | SocketError will return in a socket related error situation. |
Objects Summary
Object | Description | ||
---|---|---|---|
Listener | Represents service endpoint where socket server service registered and start. |
Endpoints Summary
Endpoint | Description | ||
---|---|---|---|
Client | Represents socket client and related remote functions. |
public type ClientConfig record
Configuration for socket client endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
host | string | Target service URL |
|
port | int | Port number of the remote service |
|
callbackService | service | The callback service for the client. Resources in this service gets called on receipt of messages from the server. |
public type ListenerConfig record
Represents the socket server configuration.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
interface | string? | null | the interface that server with to bind |
public type SocketError record
SocketError will return in a socket related error situation.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | the cause for the error |
public type Listener object
Represents service endpoint where socket server service registered and start.
-
<Listener> __init(int port, socket:ListenerConfig? config)
Parameter Name Data Type Default Value Description port int config socket:ListenerConfig? null -
<Listener> __start() returns (error?<>)
Return Type Description error?<> -
<Listener> __stop() returns (error?<>)
Return Type Description error?<> -
<Listener> __attach(service s, map annotationData) returns (error?<>)
Parameter Name Data Type Default Value Description s service annotationData map Return Type Description error?<>
Endpoint Client
Represents socket client and related remote functions.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
remotePort | int | 0 | the remote port number to which this socket is connected |
localPort | int | 0 | the local port number to which this socket is bound |
remoteAddress | string? | null | the remote IP address string in textual presentation to which the socket is connected |
localAddress | string? | null | the local IP address string in textual presentation to which the socket is bound |
id | int | 0 | a unique identifier to identify each client |
-
<Client> write(byte[] content) returns (int | error<>)
Writes given data to the client socket.
Parameter Name Data Type Default Value Description content byte[] - the content that wish to send to the client socket
Return Type Description int | error<> - number of bytes got written or an error if encounters an error while writing
-
<Client> close() returns (error?<>)
Closes the client socket connection.
Return Type Description error?<> - an error if encounters an error while closing the connection or returns nil otherwise
-
<Client> shutdownRead() returns (error?<>)
Shutdowns the further read from socket.
Return Type Description error?<> an error if encounters an error while shutdown the read from socket or returns nil otherwise
-
<Client> shutdownWrite() returns (error?<>)
Shutdowns the further write from socket.
Return Type Description error?<> an error if encounters an error while shutdown the write from socket or returns nil otherwise