ballerina/tcp

Package Overview

This package provides an implementation for sending/receiving messages to/from another application process (local or remote) for both connection-oriented protocols.

Client

The tcp:Client is used to connect to a socket server and interact with it. The client can simply send the data to the server and retrieve the data from the server.

A Client can be defined by providing the remoteHost and the remotePort. A simple Client code as follows.

1import ballerina/tcp;
2
3public function main() returns error? {
4 tcp:Client socketClient = check new ("localhost", 3000);
5
6 string msg = "Hello Ballerina";
7 byte[] msgByteArray = msg.toBytes();
8 check socketClient->writeBytes(msgByteArray);
9
10 readonly & byte[] receivedData = check socketClient->readBytes();
11
12 check socketClient->close();
13}

Listener

The tcp:Listener is used to listen to the incoming socket request. The onConnect(tcp:Caller) remote method gets invoked when a new client is connected. The new client is represented using the tcp:Caller. The onConnect(tcp:Caller) method may return tcp:ConnectionService|tcp:Error.

The tcp:ConnectionService can have following remote methods

  • onBytes(readonly & byte[] data) - This remote method is invoked once the content is received from the client.
  • onError(readonly & tcp:Error err) - This remote method is invoked in an error situation.
  • onClose() - This remote method is invoked when the connection is closed.

A tcp:Listener can be defined as follows:

1import ballerina/tcp;
2import ballerina/io;
3import ballerina/log;
4
5service on new tcp:Listener(3000) {
6 remote function onConnect(tcp:Caller caller) returns tcp:ConnectionService {
7 io:println("Client connected to echoServer: ", caller.remotePort);
8 return new EchoService();
9 }
10}
11
12service class EchoService {
13
14 remote function onBytes(readonly & byte[] data) returns byte[]|tcp:Error? {
15 // echo back the data to the client
16 return data;
17 }
18
19 remote function onError(tcp:Error err) returns tcp:Error? {
20 log:printError("An error occurred", 'error = err);
21 }
22
23 remote function onClose() returns tcp:Error? {
24 io:println("Client left");
25 }
26}

For information on the operations, which you can perform with this package, see the below Functions. For examples on the usage of the operations, see the following.

Listeners

[1]

Listener

This is used for creating TCP server endpoints.

Clients

[2]

Caller

Represents caller object in tcp service remote methods

Client

Initializes the TCP connection client based on the provided configurations.

Object Types

[2]

ConnectionService

Represent TCP Listener ConnectionService service type.

Service

Represent TCP Listener service type.

Records

[5]

CertKey

Represents combination of certificate, private key and private key password if encrypted.

ClientConfiguration

Configurations for the connection oriented tcp client.

ClientSecureSocket

Secure Socket configuration for TCP Client.

ListenerConfiguration
ListenerSecureSocket

Secure Socket configuration for TCP Listener.

Enums

[1]

Protocol

Represents protocol options.

Errors

[1]

Error

Represents tcp module related errors.