ballerina/io package

Package Overview

This package is designed to support input and output operations via channels in a canonical way, either in a blocking, or non-blocking manner.

architecture

Channels

A channel represents an I/O source or sink of some bytes, characters, or records that are opened for reading, or writing, respectively.

Byte channels

The most primitive channel is the ByteChannel which reads and writes 8-bit bytes.

// Open a file in read-write mode.
io:ByteChannel byteChannel = io:openFile("some/file.txt", io:RW);

// Here is how 100 bytes are read from the channel.
var readResult = byteChannel.read(100);
    match readResult {
        (blob, int) content => {
            return content; // Return the read content.
        }
    error err => {
        return err; // An IO error occurred when reading the bytes.
    }
}

// Write some content to the beginning of the file.
string someContent = "some content";
blob content = someContent.toBlob("UTF-8");
var writeResult = byteChannel.write(content, 0);
match writeResult {
    int numberOfBytesWritten => {
        return numberOfBytesWritten; // Return the count of written bytes.
    }
    error err => {
        return err; // An IO error occurred when writing the bytes.
    }
}

Character channels

The CharacterChannel is used to read and write characters. The charset encoding is specified when creating the CharacterChannel.

// Create a `CharacterChannel` from the `ByteChannel`.
var charChannel = new io:CharacterChannel(byteChannel, "UTF-8");

If a CharacterChannel points to a JSON or XML source, it can be read and then written, directly into a variable of the respective type.

// Reading a JSON.
var readResult = charChannel.readJson();
match readResult {
    json value => {
        return value; // Return the read JSON value.;
    }
    error err => {
        return err; // An IO error occurred when reading the JSON.
    }
}

// Writing a JSON.
json content = {fname:"Jhon", lname:"Doe", age:40};
var writeResult = charChannel.writeJson(content);
match writeResult {
    error err => {
        return err; // An IO error occurred when writing the JSON.
    }
    () => {
        io:println("JSON content written successfully.");
    }
}
// Reading an XML.
var result = charChannel.readXml();

Record channels

Ballerina also supports I/O for delimited records.

// Creating a `DelimitedRecordChannel` from the `CharacterChannel`.
// Records are separated using a new line, and
// fields of a record are separated using a comma.
var recordsChannel = new io:DelimitedTextRecordChannel(charChannel, fs = ",", rs = "\n");

// Reading a few records.
while (recordsChannel.hasNext()) {
    var result = recordsChannel.getNext();
    match result {
        string[] record => {
            println(record); // Retrieved a record.
        }
        error err => {
            return err; // An IO error occurred when reading the records.
        }
    }
}

A .CSV file can be read and written directly into a CSVChannel, as shown in this code snippet.

var csvChannel = io:openCsvFile("records.csv");

Records of the .CSV file can read directly into a table of a matching type.

// First let’s define a type that matches a record in the CSV file.
type Employee record {
   string id;
   string name;
   float salary;
};

// Now read the CSV file as a table of Employees and compute total salary.
float totalSalary = 0;
match csvChannel.getTable(Employee) {
   table<Employee> employees => {
       foreach employee in employees {
           totalSalary += employee.salary;
       }
       return totalSalary; // Return total of salaries of all employees.
   }
   error err => {
       return err; // An IO error occurred when reading the records.
   }
}

Type Definitions

Type Values Description
ByteOrder LI | BI

Represents network byte order.

BIG_ENDIAN - specifies the bytes to be in the order of most significant byte first

LITTLE_ENDIAN - specifies the byte order to be the least significant byte first

Format tdf | default | csv

Format which will be used to represent the CSV.

DEFAULT - Would default to the format specified by CSVChannel. Presidence will be given to field separator and record separator.

CSV - Field separator would be "," and the record separator would be new line.

TDF - Field separator will be tab and record separator will be new line.

Mode w | rw | r | a

Represents the set of permissions supported to open file.

READ - open the file in read mode WRITE - open the file in write mode READ/WRITE - open the file either to read or write APPEND - append to existing file instead of replacing

Separator : | , |

Field separators which are supported by DelimitedTextRecordChannel.

Records Summary

Record Description
SocketProperties SocketProperties represents the properties which are used to configure TCP connection.

Objects Summary

Object Description
ByteChannel

ByteChannel represents an input/output resource (i.e file, socket). which could be used to source/sink bytes.

CSVChannel

Represents a CSVChannel which could be used to read/write records from CSV file.

CharacterChannel

Represents a channel which could be used to read/write characters through a given ByteChannel.

DataChannel

Represents a data channel for reading/writing data.

DelimitedTextRecordChannel

Represents a channel which will allow to read/write records through a given CharacterChannel.

Socket

Represents a TCP socket.

StringReader

Represents a reader which will wrap string content as a channel.

Functions Summary

Return Type Function and Description
ByteChannel createMemoryChannel(blob content)

Creates an in-memory channel which will reference stream of bytes.

CSVChannel openCsvFile(string path, a|rw|w|r mode, :|,| fieldSeparator, string charset, int skipHeaders)

Retrieves a CSV channel from a give file path.

ByteChannel openFile(string path, a|rw|w|r accessMode)

Retrieves a ByteChannel from a given file path.

Socket | error openSecureSocket(string host, int port, io:0.0.0:SocketProperties options)

Opens a secure socket connection with a remote server.

Socket | error openSocket(string host, int port, io:0.0.0:SocketProperties options)

Opens a socket from a specified network location.

print(any[] a)

Prints 'any' value to the STDOUT.

println(any[] a)

Prints an any value to the STDOUT in a new line.

string readln(any a)

Returns the input read from STDIN.

string sprintf(string format, any[] args)

Returns a formatted string using the specified format string and arguments.

Global Variables

Name Data Type Description
APPEND Mode
BIG_ENDIAN ByteOrder
COLON Separator
COMMA Separator
CSV Format
DEFAULT Format
LITTLE_ENDIAN ByteOrder
READ Mode
RW Mode
TAB Separator
TDF Format
WRITE Mode

public type SocketProperties record

SocketProperties represents the properties which are used to configure TCP connection.

Field Name Data Type Default Value Description
localPort int

Local port the socket client should bind

keyStoreFile string

Relative/absolute path to locate keystore file

keyStorePassword string

Keystore password

trustStoreFile string

Relative/absolute path to locate truststore file

trustStorePassword string

Truststore password

certPassword string

Password of the certificate

sslEnabledProtocols string

Protocols supported for SSL (i.e TLSv1.2,TLSv1.1,TLSv1)

ciphers string

Encrypt/decrypt algorithms (i.e RSA, SHA-256)

sslProtocol string

Supported SSL protocols (i.e SSL, TLS)

public function createMemoryChannel(blob content) returns (ByteChannel)

Creates an in-memory channel which will reference stream of bytes.

Parameter Name Data Type Default Value Description
content blob

Content which should be exposed as channel

Return Type Description
ByteChannel

ByteChannel represenation to read the memory content

public function openCsvFile(string path, a|rw|w|r mode, :|,| fieldSeparator, string charset, int skipHeaders) returns (CSVChannel)

Retrieves a CSV channel from a give file path.

Parameter Name Data Type Default Value Description
path string

File path which describes the location of the CSV

mode a|rw|w|r r

Permission which should be used to open CSV file

fieldSeparator :|,| ,

CSV record seperator (i.e comma or tab)

charset string UTF-8

Encoding characters in the file represents

skipHeaders int 0

Number of headers which should be skipped

Return Type Description
CSVChannel

CSVChannel which could be used to iterate through the CSV records

public function openFile(string path, a|rw|w|r accessMode) returns (ByteChannel)

Retrieves a ByteChannel from a given file path.

Parameter Name Data Type Default Value Description
path string

Relative/absolute path string to locate the file

accessMode a|rw|w|r

Permission to open the file

Return Type Description
ByteChannel

ByteChannel representation of the file resource

public function openSecureSocket(string host, int port, io:0.0.0:SocketProperties options) returns (Socket | error)

Opens a secure socket connection with a remote server.

Parameter Name Data Type Default Value Description
host string

Remote server domain/IP

port int

Remote server port

options io:0.0.0:SocketProperties

Mata data to initialize the connection(i.e security information)

Return Type Description
Socket | error

Socket which will represent the network object or an error

public function openSocket(string host, int port, io:0.0.0:SocketProperties options) returns (Socket | error)

Opens a socket from a specified network location.

Parameter Name Data Type Default Value Description
host string

Remote server domain/IP

port int

Remote server port

options io:0.0.0:SocketProperties

Connection stream that bridge the client and the server

Return Type Description
Socket | error

Socket which will allow to communicate with a remote server or error

public function print(any[] a)

Prints 'any' value to the STDOUT.

Parameter Name Data Type Default Value Description
a any[]

public function println(any[] a)

Prints an any value to the STDOUT in a new line.

Parameter Name Data Type Default Value Description
a any[]

public function readln(any a) returns (string)

Returns the input read from STDIN.

Parameter Name Data Type Default Value Description
a any

Any value to be printed

Return Type Description
string

Input read from STDIN

public function sprintf(string format, any[] args) returns (string)

Returns a formatted string using the specified format string and arguments.

Parameter Name Data Type Default Value Description
format string

Represent the format of the string which should be returned

args any[]
Return Type Description
string

Formatted string

public type ByteChannel object

ByteChannel represents an input/output resource (i.e file, socket). which could be used to source/sink bytes.

  • <ByteChannel> read(int nBytes) returns ((blob,int) | error)

    Source bytes from a given input/output resource.

    Number of bytes returned will be < 0 if the file reached its end.

    This operation will be asynchronous, where the total number of required bytes might not be returned at a given time.

    Parameter Name Data Type Default Value Description
    nBytes int

    Positive integer. Represents the number of bytes which should be read

    Return Type Description
    (blob,int) | error

    Content, the number of bytes read or an error

  • <ByteChannel> write(blob content, int offset) returns (int | error)

    Sink bytes from a given input/output resource.

    This operation will be asynchronous, write might return without writing all the content.

    Parameter Name Data Type Default Value Description
    content blob

    Block of bytes which should be written

    offset int
    Return Type Description
    int | error

    Offset which should be kept when writing bytes

  • <ByteChannel> close() returns (error)

    Closes a given byte channel.

    Return Type Description
    error

    Will return () if there's no error

  • <ByteChannel> base64Encode() returns (ByteChannel | error)

    Encodes a given ByteChannel with Base64 encoding scheme.

    Return Type Description
    ByteChannel | error

    Return an encoded ByteChannel or an error

  • <ByteChannel> base64Decode() returns (ByteChannel | error)

    Decodes a given ByteChannel with Base64 encoding scheme.

    Return Type Description
    ByteChannel | error

    Return a decoded ByteChannel or an error

public type CSVChannel object

Represents a CSVChannel which could be used to read/write records from CSV file.

  • <CSVChannel> new(io:0.0.0:CharacterChannel channel, :|,| fs, int nHeaders)

    Constructs a CSV channel from a CharacterChannel to read/write CSV records.

    Parameter Name Data Type Default Value Description
    channel io:0.0.0:CharacterChannel

    ChracterChannel which will represent the content in the CSV

    fs :|,| ,

    Field separator which will separate between the records in the CSV

    nHeaders int 0

    Number of headers which should be skipped prior to reading records

  • <CSVChannel> hasNext() returns (boolean)

    Indicates whether there's another record which could be read.

    Return Type Description
    boolean

    True if there's a record

  • <CSVChannel> getNext() returns (string[] | error)

    Gets the next record from the CSV file.

    Return Type Description
    string[] | error

    List of fields in the CSV or error

  • <CSVChannel> write(string[] csvRecord) returns (error)

    Writes record to a given CSV file.

    Parameter Name Data Type Default Value Description
    csvRecord string[]

    A record to be written to the channel

    Return Type Description
    error

    Returns an error if the record could not be written properly

  • <CSVChannel> close() returns (error)

    Closes a given CSVChannel.

    Return Type Description
    error

    Returns if an error is encountered

  • <CSVChannel> getTable(typedesc structType) returns (table | error)

    Returns a table which coresponds to the CSV records.

    Parameter Name Data Type Default Value Description
    structType typedesc

    The object the CSV records should be deserialized

    Return Type Description
    table | error

    Table which represents CSV records or error

public type CharacterChannel object

Represents a channel which could be used to read/write characters through a given ByteChannel.

  • <CharacterChannel> new(io:0.0.0:ByteChannel channel, string charset)

    Constructs a CharacterChannel from a given ByteChannel and Charset.

    Parameter Name Data Type Default Value Description
    channel io:0.0.0:ByteChannel

    ByteChannel which would be used to read/write characters

    charset string

    Character-Set which would be used to encode/decode given bytes to characters

  • <CharacterChannel> read(int numberOfChars) returns (string | error)

    Reads a given number of characters.

    Parameter Name Data Type Default Value Description
    numberOfChars int

    Number of characters which should be read

    Return Type Description
    string | error

    Content which is read or an error

  • <CharacterChannel> write(string content, int startOffset) returns (int | error)

    Writes a given sequence of characters (string).

    Parameter Name Data Type Default Value Description
    content string

    Content which should be written

    startOffset int

    Number of characters which should be offset when writing content

    Return Type Description
    int | error
  • <CharacterChannel> readJson() returns (json | error)

    Reads a json from the given channel.

    Return Type Description
    json | error

    Read json string or an error

  • <CharacterChannel> readXml() returns (xml | error)

    Reads a XML from the given channel.

    Return Type Description
    xml | error

    Read xml or an error

  • <CharacterChannel> writeJson(json content) returns (error)

    Writes a given json to the given channel.

    Parameter Name Data Type Default Value Description
    content json

    The json which should be written

    Return Type Description
    error

    If an error occurred while writing

  • <CharacterChannel> writeXml(xml content) returns (error)

    Writes a given xml to the channel.

    Parameter Name Data Type Default Value Description
    content xml

    The XML which should be written

    Return Type Description
    error

    If an error occurred while writing

  • <CharacterChannel> close() returns (error)

    Closes a given character channel.

    Return Type Description
    error

    If an error occurred while writing

public type DataChannel object

Represents a data channel for reading/writing data.

  • <DataChannel> new(io:0.0.0:ByteChannel byteChannel, BI|LI bOrder)

    Parameter Name Data Type Default Value Description
    byteChannel io:0.0.0:ByteChannel
    bOrder BI|LI BI
  • <DataChannel> readInt16() returns (int | error)

    Reads a 16 bit integer.

    Return Type Description
    int | error

    value of the integer which is read or an error

  • <DataChannel> readInt32() returns (int | error)

    Reads a 32 bit integer.

    Return Type Description
    int | error

    value of the integer which is read or an error

  • <DataChannel> readInt64() returns (int | error)

    Reads a 64 bit integer.

    Return Type Description
    int | error

    value of the integer which is read or an error

  • <DataChannel> writeInt16(int value) returns (error)

    Writes 16 bit integer.

    Parameter Name Data Type Default Value Description
    value int

    integer which will be written

    Return Type Description
    error

    nill if the content is written successfully or an error

  • <DataChannel> writeInt32(int value) returns (error)

    Writes 32 bit integer.

    Parameter Name Data Type Default Value Description
    value int

    integer which will be written

    Return Type Description
    error

    nill if the content is written successfully or an error

  • <DataChannel> writeInt64(int value) returns (error)

    Writes 64 bit integer.

    Parameter Name Data Type Default Value Description
    value int

    integer which will be written

    Return Type Description
    error

    nill if the content is written successfully or an error

  • <DataChannel> readFloat32() returns (float | error)

    Reads 32 bit float.

    Return Type Description
    float | error

    value of the float which is read or an error

  • <DataChannel> readFloat64() returns (float | error)

    Reads 64 bit float.

    Return Type Description
    float | error

    value of the float which is read or an error

  • <DataChannel> writeFloat32(float value) returns (error)

    Writes 32 bit float.

    Parameter Name Data Type Default Value Description
    value float

    float which will be written

    Return Type Description
    error

    nill if the float is written successfully or an error

  • <DataChannel> writeFloat64(float value) returns (error)

    Writes 64 bit float.

    Parameter Name Data Type Default Value Description
    value float

    float which will be written

    Return Type Description
    error

    nill if the float is written successfully or an error

  • <DataChannel> readBool() returns (boolean | error)

    Reads 1 byte and convert it's value to boolean.

    Return Type Description
    boolean | error

    boolean value which is read or an error

  • <DataChannel> writeBool(boolean value) returns (error)

    Writes boolean.

    Parameter Name Data Type Default Value Description
    value boolean

    boolean which will be written

    Return Type Description
    error

    nill if the content is written successfully or an error

  • <DataChannel> readString(int nBytes, string encoding) returns (string | error)

    Reads string value represented through the provided number of bytes.

    Parameter Name Data Type Default Value Description
    nBytes int

    specifies the number of bytes which represents the string

    encoding string

    specifies the char-set encoding of the string

    Return Type Description
    string | error

    value of the string or an error

  • <DataChannel> writeString(string value, string encoding) returns (error)

    Writes a given string value to the respective channel.

    Parameter Name Data Type Default Value Description
    value string

    the value which should be written

    encoding string

    the encoding which will represent the value string

    Return Type Description
    error

    nill if the content is written successfully or an error

  • <DataChannel> close() returns (error)

    Closes the data channel.

    Return Type Description
    error

    nill if the channel is closed successfully or an i/o error

public type DelimitedTextRecordChannel object

Represents a channel which will allow to read/write records through a given CharacterChannel.

  • <DelimitedTextRecordChannel> new(io:0.0.0:CharacterChannel channel, string fs, string rs, string fmt)

    Constructs a DelimitedTextRecordChannel from a given CharacterChannel.

    Parameter Name Data Type Default Value Description
    channel io:0.0.0:CharacterChannel

    CharacterChannel which will point to the input/output resource

    fs string

    Field separator (this could be a regex)

    rs string

    Record separator (this could be a regex)

    fmt string default
  • <DelimitedTextRecordChannel> hasNext() returns (boolean)

    Checks whether there's a record left to be read.

    Return Type Description
    boolean

    True if there's a record left to be read

  • <DelimitedTextRecordChannel> getNext() returns (string[] | error)

    Get next record from the input/output resource.

    Return Type Description
    string[] | error

    Set of fields included in the record or an error

  • <DelimitedTextRecordChannel> write(string[] textRecord) returns (error)

    Writes records to a given input/output resource.

    Parameter Name Data Type Default Value Description
    textRecord string[]

    List of fields to be written

    Return Type Description
    error

    An error if the records could not be written properly

  • <DelimitedTextRecordChannel> close() returns (error)

    Closes a given record channel.

    Return Type Description
    error

    An error if the record channel could not be closed properly

public type Socket object

Represents a TCP socket.

Field Name Data Type Default Value Description
channel io:0.0.0:ByteChannel

ByteChannel which will represent the socket connection

port int

Remote server connection port

localPort int

Local port the socket connection should bound

address string

IP/Host of the remote server

localAddress string

Local interface the connection should bound

  • <Socket> close() returns (error)

    Closes a socket connection.

    Return Type Description
    error

    An error if the connection could not be closed properly

  • <Socket> shutdownInput() returns (error)

    Shutdown the connection from reading. In this case content cannot be read from the server.

    Return Type Description
    error

    An error if the connection could not be shutdown properly

  • <Socket> shutdownOutput() returns (error)

    Shutdown the connection from writing. In this case content cannot be written to the server.

    Return Type Description
    error

    An error if the connection could not be shutdown properly

public type StringReader object

Represents a reader which will wrap string content as a channel.

  • <StringReader> new(string content, string encoding)

    Constructs a channel to read string.

    Parameter Name Data Type Default Value Description
    content string

    content which should be written

    encoding string UTF-8

    encoding of the characters of the content

  • <StringReader> readJson() returns (json | error)

    Reads string as json from reader.

    Return Type Description
    json | error

    json or an error

  • <StringReader> readXml() returns (xml | error)

    Reads string as XML from reader

    Return Type Description
    xml | error
  • <StringReader> readChar(int nCharacters) returns (string | error)

    Reads characters from the given string.

    Parameter Name Data Type Default Value Description
    nCharacters int

    read specifc number of characters

    Return Type Description
    string | error

    string or an error

  • <StringReader> close() returns (error)

    Closes reader.

    Return Type Description
    error