Swan Lake Alpha3

Overview of Ballerina Swan Lake Alpha3

The Ballerina Swan Lake Alpha3 release includes the language features planned for the Ballerina Swan Lake release. Moreover, this release includes improvements and bug fixes to the compiler, runtime, standard library, and developer tooling. This release note lists only the features and updates added after the Alpha2 release of Ballerina Swan Lake.

Updating Ballerina

If you are already using Ballerina, you can directly update your distribution to Ballerina Swan Lake Alpha3 using the Ballerina update tool. To do this, first, execute the command below to get the update tool updated to its latest version.

bal update

If you are using an update tool version below 0.8.14, execute the ballerina update command to update it. Next, execute the command below to update to Swan Lake Alpha3.

bal dist pull slalpha3

Installing Ballerina

If you are a new user, then download the installers to install.

What is new in Ballerina Swan Lake Alpha3


Support for module-level variables with list, mapping, and error binding patterns

Variable declarations with list, mapping, or error binding patterns are now allowed at the module level. Unlike simple variables, these variables must be initialized in the declaration.

Also, these variable declarations cannot contain the isolated or configurable qualifier.

Support for module-level public variables

Module-level variables can now be declared as public using the public qualifier. Such variables will be visible outside the modules in which they are declared.

Isolated variables and variables declared with var cannot be declared as public variables.

Improvement to annotation attachment with empty mapping constructor expression

If the type of the annotation is a mapping type for which an empty mapping constructor is valid, the mapping constructor expression is no longer mandatory in the annotation attachment.

The absence of the mapping constructor expression in such an annotation attachment is equivalent to specifying a mapping constructor expression with no fields.

Introduction of the function function type descriptor to represent any function

A new function type descriptor has been introduced to represent all function values.

New lang library functions
New xml:text() function

This function can be used to select all the items in a sequence that are of type xml:Text.

Bug fixes

To view bug fixes, see the GitHub milestone for Swan Lake Alpha3.


New runtime Java API to create errors

A new runtime Java API is introduced to create errors.

The createDistinctError API has been deprecated and should not be used to create distinct errors. The new createError API can be used instead.

Bug fixes

To view bug fixes, see the GitHub milestone for Swan Lake Alpha3.

Standard library

Log package updates
Introduced additional log levels and log functions

Introduced 2 additional log levels: DEBUG and WARN. The printDebug and printWarn functions in the ballerina/log module can be used to publish logs at the respective log levels. The print function was renamed to printInfo.

To set the global log level, place the entry given below in the Config.toml file:

Each module can also be assigned its own log level. To assign a log level to a module, provide the following entry in the Config.toml file:

OS package updates
  • Removed the exec function.
Task package updates

The module has been revamped by removing the Scheduler and Listener classes and introducing the following functions to schedule and manage the job either one-time or periodically.

  • Configures the scheduler worker pool with the worker count and max waiting time.
  • Schedules the job at a specified time.
  • Schedules the recurring job according to the given duration.
  • Unschedules the particular job.
  • Pauses all the jobs.
  • Resumes all the jobs.
  • Pauses the particular job.
  • Resumes the particular job.
  • Gets all the running jobs.
Time package updates

Revamped the entire time package as follows:

  • Introduced the time:Utc record to represent the UTC timestamp.
  • Introduced the time:Civil record to represent the localized time.
  • Added necessary APIs to do time generation, manipulations, and conversions.

Steps for migration from the previous version to the current version are listed in this issue.

Cache package updates
  • Introduced the new EvictionPolicy configuration to set the eviction policy in the CacheConfig record.

The EvictionPolicy record has been introduced with the option LRU as the module only supports the LRU eviction policy to evict the cache data when the cache is full.

  • Removed the AbstractEvictionPolicy object type.

This object type had the common APIs for the cache eviction functionalities to implement a custom eviction policy. It has been removed with the introduction of the above configuration.

New xmldata package

A new module is added to convert data in XML format to JSON format and vice-versa.

  • Converts a JSON object to an XML representation.
  • Converts an XML value to its JSON representation.
Removed jsonutils, xmlutils, runtime, and reflect packages

The jsonutils, xmlutils, runtime, and reflect packages were removed from Standard Libraries.

The XML/JSON conversation APIs in jsonutils and xmltutils packages are now supported by the xmldata package.

HTTP package updates
  • Changed the return types of the client methods to depend on the targetType argument. The default targetType is http:Response.
  • Introduced a header map as an optional argument for non-entity-body client remote methods (GET, HEAD, OPTIONS).
  • Introduced header map and media type as optional arguments for entity-body client remote methods (POST, PUT, PATCH, DELETE, EXECUTE).
  • Improved the data types of outbound request/response payloads which can be set directly.
  • Marked HTTP client remote methods as isolated.

  • Introduced module error inheritance and remove error union types.

WebSocket package updates
  • Introduced auth support for the WebSocket client. The bearer token, Basic Auth, JWT, and OAuth2 support have been introduced with the WebSocket client declarative authentication.

  • Introduced HTTP cookie support for the WebSocket client.

  • Made the websocket:Caller optional in WebSocket service remote functions.

  • Introduced support to send text, binary, and pong messages by returning them from the remote methods. Text/binary data can now be sent to the peer by returning a string or a byte[] value from the onTextMessage and onBinaryMessage remote methods. Also, a pong frame can be sent to the peer by returning a byte[] value from the onPing remote method.

  • Removed the support for the websocket:AsyncClient.
GraphQL package updates
  • Added the support for hierarchical resource paths. The Ballerina GraphQL resources now can have hierarchical resource paths. Each intermediate resource path then maps to a new type in the generated schema.
  • Supported resource functions to return optional types.

The Ballerina GraphQL resources now can return optional types.

Email package updates
  • Enabled read/listen for multiple emails in a single TCP connection.

    Each POP3 or IMAP client/listener creation initiates the connection. Then, the email sending, receiving, or listening operations can be performed many times. Finally, the client/listener has to be closed.

POP3 client example

A similar format is used in the IMAP client.

POP3 service example

Note how the close() method calls the onClose method in the service.

  • Made email body a mandatory field in sendEmail method API.

  • Renamed email sending method names removing Email in each of them Renamed sendEmail as send, sendEmailMessage as sendMessage, receiveEmailMessage as receiveMessage and onEmailMessage as onMessage.

  • Set the default from address of the email:Message record from the SmtpClient authentication field, username. Earlier, the username for authentication was decoupled from the message data. Now, the from field is made optional and the default value will be set from the username.

  • Made POP3 and IMAP clients as blocking clients by providing an optional timeout argument. The time unit is in seconds and the data type is decimal. The default value is 0 in which the inbuilt polling interval is 100 milliseconds. A sample client code is as follows.

  • In the PopListener and ImapListener configurations, the polling interval is not set with the decimal type in seconds to the pollingInterval field, which was earlier named as pollingIntervalInMillis.

  • Renamed the email:SmtpConfig, email:PopConfig, email:ImapConfig, email:PopListenerConfig, and email:ImapListenerConfiguration as email:SmtpConfiguration, email:PopConfiguration, email:ImapConfiguration, email:PopListenerConfiguration, and email:ImapListenerConfiguration respectively.

  • Removed the cronExpression field from the email:ImapListenerConfig and email:PopListenerConfig.

  • Made the body field of the send method mandatory in the email:SmtpClient.

WebSub package updates
  • Introduced a websub-listener configuration for the websub-listener.
WebSubHub package updates
  • Included HTTP Headers parameter into the WebSub Hub API.
  • Introduced pre-initialized constant responses to be used in the websubhub:Service implementation.
  • Initializing the websubhub:HubClient with the client configurations.
  • Introduced the websubhub-listener configuration to configure a websubhub listener.
Security updates
  • Renamed the ballerina/encoding module as ballerina/url and updated the APIs.
  • The Ballerina HTTP listener can be configured to authenticate and authorize the inbound requests with a Basic Auth file user store.

  • Improved client and listener SecureSocket APIs of HTTP, gRPC, WebSocket, GraphQL, WebSub, WebSubHub, TCP, Email, NATS, STAN, and RabbitMQ modules.

  • Improved the SecureSocket configuration of the JDK11 client of the JWT and OAuth2 modules.

  • Added support for OAuth2 client authentication of the JDK11 client, which is used to call an authorization endpoint.

TCP package updates
  • Introduced SSL/TLS support for both the client and listener.
  • Included a tcp:Caller as an optional parameter in the onBytes() method.
  • Renamed tcp:ListenerConfig and tcp:ClientConfig to tcp:ListenerConfiguration and tcp:ClientConfiguration
UDP package updates
  • Renamed udp:ListenerConfig and udp:ClientConfig to udp:ListenerConfiguration and udp:ClientConfiguration
Kafka package updates
  • Renamed the sendProducerRecord function in the client object Producer to send.

  • Renamed the flushRecords function in the client object Producer to ’flush.

  • Replaced the kafka:ConsumerError and kafka:ProducerError with kafka:Error.

NATS package updates
  • Renamed the ConnectionConfig record to ConnectionConfiguration.

  • Included url as a field in the ConnectionConfiguration record.

  • Changed the ConnectionConfiguration in the client and listener init functions to an included record parameter. This allows the record field values to be passed as named parameters.

STAN package updates
  • Renamed the StreamingConfig record to StreamingConfiguration.

  • Included the url as a field in the StreamingConfiguration record.

  • Changed the StreamingConfiguration in the client and listener init functions to an included record parameter. This allows the record field values to be passed as named parameters.

RabbitMQ package updates
  • Renamed the ConnectionConfig record to ConnectionConfiguration.
Common standard library updates
  • All the timeout configurations are converted to accept decimal values and the time unit is in seconds.

Code to Cloud

  • Removed Docker annotation support.
Bug fixes

To view bug fixes, see the GitHub milestone for Swan Lake Alpha3.

Ballerina packages

Introduced local repository support

  • Apart from the Ballerina Central remote repository, you can now push packages to the local repository which can be found at <user-home>/.ballerina/repositories/local. Refer to the section on changes to CLI commands for information regarding pushing to the local repository.
  • To use a package from the local repository, the 'repository' has to be specified in the TOML table of the relevant dependency in the Dependencies.toml file.

E.g., to test a developed package before pushing it to Ballerina Central, build and push it to the local repository using the push command and add it to the Dependencies.toml file of the depending package as shown below.

Developer tools


Changes to CLI commands
  • Build and test commands

    • Support for providing [(--key=value)...] is removed from bal build.
  • Run command

    • Providing the project path to the run command is now optional. The default source root is the present working directory similar to how the build command works.
    • Program arguments should be followed by the end-of-options delimiter --.
  • New and init commands

    • Introduced creation of the Pacakge.md file for a library template. Passing the --template lib flag will create the Package.md file in addition to the Ballerina.toml file and the source BAL files.
  • Push command

    • Introduced pushing to the local repository. Passing --repository=local will push the Ballerina archive (.bala) to the local repository. For information about local repository support, see the Ballerina Packages Changelist.
  • Run bal help <command> to get more information on the command changes.

  • CLI Auto-Completion

    • Installing On Linux Bash

      • Set up auto-completion in the current bash shell.
      • Set up auto-completion permanently in the bash shell.
    • Installing On Mac Bash

      • Set up auto-completion permanently in the bash shell.

Test framework

  • Moved the Project Test Suite execution to a single JVM. Changed from running each Test Suite in a JVM instance. This improves the user experience when debugging tests. It no longer prompts to debug each test suite of a project.
  • Support for seamless integration of CICD tools by adding inbuilt path fixes to the JaCoCo XML generated for Ballerina packages.


  • Added conditional breakpoint support. (Conditional expressions can now be configured for Ballerina breakpoints in the Visual Studio Code Debug view).
  • Added support to configure environment variables in the launch mode.
  • Added expression evaluation support for type cast expressions.


  • Added JSON file generation support to the Ballerina to OpenAPI command.
  • Added improvements for handling the Ballerina resource method response type in the OpenAPI to Ballerina command.

Bindgen tool

  • Improved the generated bindings with the use of distinct type classes.
  • Improved the internal mechanism used to generate the bindings. Previous handlebars-based implementation is now changed to a syntax-tree-based implementation.


Language Server
  • The Ballerina Language Server now supports telemetry-based crash reporting. This was enabled through the LSP protocol's telemetry events. If you wish to disable Ballerina Telemetry, uncheck the Ballerina: Enable Telemetry setting from VSCode.

To view bug fixes, see the GitHub milestone for Swan Lake Alpha3.

Ballerina Shell
  • The Ballerina Shell now supports redefining module-level definitions and variable declarations.
  • A new /remove command has been introduced to be used from within the Ballerina Shell to remove one or more declarations from the snippet memory.
  • Ballerina Shell can now load definitions and declarations from a file. The file to load from can be specified using the -f or --file command-line options when launching the Ballerina Shell. Alternatively, the /file command can also be used for this purpose from within the Shell.

The --force-dumb command-line option will now have only a long option and the short option -f is now used to load from a file.

  • The Ballerina Shell now supports cyclic type definitions and list binding patterns.

  • The Ballerina Shell now preserves qualifiers such as the final qualifier of a variable declaration.


Now, the debugger supports conditional breakpoints. Conditional expressions can be configured for Ballerina breakpoints in the VSCode debug view.

Breaking changes

  1. == and != equality expressions can no longer be used with variables of type readonly.
  2. Implicit conversion from xml:Text to string is no longer supported.