2201.0.0 (Swan Lake)

Overview of Ballerina 2201.0.0 (Swan Lake)

2201.0.0 (Swan Lake) is the first major release of 2022, and it includes a new set of features and significant improvements to the compiler, runtime, standard library, and developer tooling. It is based on the 2022R1 version of the Language Specification.

Updating Ballerina

Info: The version format has been revised. 2201.0.0 (Swan Lake) represents the format of $YYMM.$UPDATE.$PATCH ($CODE_NAME). For further information, see Ballerina Swan Lake is on the Horizon.

If you are already using Ballerina, use the Ballerina update tool to directly update to 2201.0.0 (Swan Lake). To do this:

  1. Run the command below to get the latest version of the update tool.

    bal update

  2. Run the command below to update your Ballerina version to 2201.0.0 (Swan Lake).

    bal dist update

Troubleshooting

If you already ran the bal dist update (or bal dist pull 2201.0.0) before the bal update command, follow the instructions below to recover your installation.

For macOS Users (.pkg installations)
  1. Run the rm ~/.ballerina/ballerina-version command to delete the version configuration.
  2. Run the chmod 755 /Library/Ballerina/distributions/ballerina-2201.0.0/bin/bal command to provide execute permissions for the bal command.
  3. Run the bal dist use 2201.0.0 command to switch to the 2201.0.0 version.
For Ubuntu Users (.deb installations)
  1. Run the rm ~/.ballerina/ballerina-version command to delete the version configuration.
  2. Run the chmod 755 /usr/lib/ballerina/distributions/ballerina-2201.0.0/bin/bal command to provide execute permissions for the bal command.
  3. Run the bal dist use 2201.0.0 command to switch to the 2201.0.0 version.
For CentOS Users (.rpm installations)
  1. Run the rm ~/.ballerina/ballerina-version command to delete the version configuration.
  2. Run the chmod 755 /usr/lib64/ballerina/distributions/ballerina-2201.0.0/bin/bal command to provide execute permissions for the bal command.
  3. Run the bal dist use 2201.0.0 command to switch to the 2201.0.0 version.
For Windows Users (.msi installations)
  1. Run the del %userprofile%\.ballerina\ballerina-version command to delete the version configuration.
  2. Run the bal dist use 2201.0.0 command to switch to the 2201.0.0 version.

Installing Ballerina

If you have not installed Ballerina, then download the installers to install.

Migrating from Swan Lake Beta Releases

Info: If you have been using Swan Lake Beta releases, delete the Dependencies.toml files in your Ballerina packages when migrating to Balelrina 2201.0.0 (Swan Lake).

A few backward-incompatible changes have been introduced during the Swan Lake Beta program, and thereby, some of your existing packages may not compile with Ballerina 2201.0.0 (Swan Lake). Therefore, you need to delete the Dependencies.toml file to force the dependency resolver to use the latest versions of your dependencies.

Language Updates

New Features

Support to Refer to Parameters and Local Variables in Object Constructor Expressions

Object constructor expressions can now refer to parameters and local variables. This feature is also available when using an object constructor expression with the service qualifier to create a service object. These references can be in field initializers and object methods, including the init method.

Bug Fixes

  • Fixed a bug that caused constants to be resolved with incorrect types in certain scenarios. The type of constants is now the intersection of readonly and the singleton type containing just the shape of the value named by the constant.

  • Fixed a spec deviation in type narrowing. This may result in types that were previously narrowed no longer being narrowed.

    Consider the following records.

    Previously, when a type test was used as follows, the type of v in the else block was narrowed to Student.

    Even though jBallerina currently allows only values that belong to either Employee or Student to be passed as arguments for the parameter of type Employee|Student, the Ballerina specification defines subtyping to be semantic. This, along with mutability, would mean that a value that does not belong to Employee nor Student but belongs to Employee|Student can be passed as an argument here, which results in the possibility of the value not belonging to Student in the else block.

    For example, one would be able to call fn with the following.

    Although it is not possible to call this function in this manner at the moment since jBallerina does not support semantic subtyping, the changes to narrowing have been introduced in this release to minimize future incompatibility issues.

  • Fixed a spec deviation that allowed non-required fields of records/maps and error detail records/maps to be bound using mapping and error binding patterns in variable declarations and destructuring assignment statements. Attempting to bind a non-required field will now result in a compilation error.

  • Fixed a bug in the compiler that resulted in some illegal variable shadowing scenarios not being detected. Ballerina allows shadowing only variables that belong to the module scope.

  • Fixed a bug that caused classes with all final fields of immutable types to be considered a readonly class (i.e., a subtype of readonly).

    Such a class can no longer be used in a context that expects a subtype of readonly.

  • Fixed a bug that resulted in invalid table lookups due to not distinguishing between int, float, and decimal zero.

To view bug fixes, see the GitHub milestone for 2201.0.0 (Swan Lake).

Runtime Updates

Bug Fixes

To view bug fixes, see the GitHub milestone for 2201.0.0 (Swan Lake).

Standard Library Updates

New Features

graphql Package
  • Added the CORS configuration support
http Package
  • Implemented typed headers for the HTTP response
  • Added the map<string> data binding support for application/www-x-form-urlencoded
  • Added support to provide an inline request/response body with x-form-urlencoded content
  • Added compiler plugin validation for usage of the @http:Payload annotation

Improvements

graphql Package
  • Removed the deprecated add method in the graphql:Context object
grpc Package
  • Changed the --proto_path option of the gRPC command to --proto-path
websub Package
  • Added support for readonly parameters in remote methods

websubhub Package

  • Added support for readonly parameters in remote methods
kafka Package
  • Made the kafka:Caller optional in the onConsumerRecord method of the kafka:Service
  • Allowed the readonly & kafka:ConsumerRecord[] parameter type in the onConsumerRecord method

Code to Cloud Updates

Improvements

  • Removed awslambda and azure_functions module support for single .bal files

Bug Fixes

To view bug fixes, see the GitHub milestone for 2201.0.0 (Swan Lake).

Developer Tools Updates

New Features

Ballerina Shell
  • Added the module auto-import feature to the Ballerina Shell. If the user code contains a module prefix for a module that has not been imported, the Ballerina Shell provides the option to import the module.

    For example, see below.

Improvements

Ballerina OpenAPI Tool
OpenAPI Contract Generation
  • Added support for HTTP headers of types int, int[], boolean, and boolean[]
  • Added support for HTTP payloads of type map<string>
  • Improved the OAS response header mapping for contexts in which the header details are defined within the return type
Ballerina Service Generation
  • Added support for OAS query parameters with nested/optional/nullable types and default values
  • Added support for OAS header parameters with optional/nullable types and default values
Ballerina update tool
  • Improved the view for bal dist list with the -a flag
  • Improved the bal dist use command to check for the distribution availability prior to the download suggestion

Bug Fixes

To view bug fixes, see the GitHub milestone for 2201.0.0 (Swan Lake) of the repositories below.