Swan Lake Alpha2

Overview of Ballerina Swan Lake Alpha2

This Alpha2 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 Alpha1 release of Ballerina Swan Lake.

Updating Ballerina

You can use the update tool to update to Ballerina Swan Lake Alpha2 as follows.

For existing users

If you are already using Ballerina, you can directly update your distribution to the Swan Lake channel 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 Alpha2.

bal dist pull slalpha2

For new users

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

Highlights

  • Support for mapping and error binding patterns in the match statement
  • Support for configurable variables of record and table types
  • Support for decrypting string values using the new lang.config lang library
  • Improvements to the HTTP, MIME, WebSocket, GraphQL, WebSub, WebSubHub, IO, email, UDP, crypto, and JWT standard library modules
  • The extension of the Ballerina package distribution file has been changed from .balo to .bala
  • Improvements to developer tools such as the Language Server and debugger

What is new in Ballerina Swan Lake Alpha2

Language

Support for mapping and error binding patterns in the match statement

Mapping binding pattern

The match statement now supports mapping and error binding patterns with var.

Error binding pattern

Runtime

Support for configurable variables of record and table types

Record type

Record fields with simple types like int, string, boolean, float, decimal, and arrays of the respective types are now supported.

For example, if the Config.toml file contains the following TOML table,

it can be loaded as configurable variables of a record type as follows.

Table type

Ballerina now supports configurable variables of type table through TOML arrays of tables.

For example, if the Config.toml file contains the following TOML table array,

it can be loaded as a configurable variable of a table type as follows.

Support for decrypting string values using the new config lang library

The bal encrypt command can be used to encrypt plain text values and specify those in the Config.toml file. Then, the config:decryptString() function can be used to decrypt the configurable value.

For example, if the Config.toml file contains the following encrypted string value,

it can be decrypted in the Ballerina code as follows.

Standard library

HTTP module improvements
Introduced byte stream manipulation functions to the request and response

This introduction enables manipulating the payload as a stream of byte[]. The setByteStream() and getByteStream() methods use the Ballerina stream feature.

Introduced the http:Header annotation to bind headers in an inbound request

With the introduction of the @http:Header annotation, inbound request headers can be retrieved by binding them to a resource method parameter. Individual headers can be accessed as string or string[] types while a parameter of type http:Headers can be used to access all headers.

MIME module improvements
Introduced byte stream manipulation methods to the mime:Entity class

This introduction enables manipulating the entity body as a stream of byte[].

WebSocket module improvements

Introduced the Sync client. This is the primary client of the WebSocket module. This client is capable of reading and writing messages synchronously.

Reading and writing text messages

Reading and writing binary messages

GraphQL module improvements

Ballerina GraphQL listeners can now be configured using the same configurations as the listener configurations in http:Listener. Additionally, a GraphQL service can be secured by defining a maxQueryDepth as an annotation to restrict the depth of a query before execution.

WebSub module improvements

Included functionality to the websub:SubscriberService to respond with user-defined custom payloads/header parameters in error scenarios.

WebSubHub module improvements

Included functionality to the websubhub:Service to respond with user-defined custom payloads/header parameters in error scenarios.

IO module improvements

Introduce a parameter of type XmlWriteOptions to specify the entity type and the document type declaration.

Example

Output

Email module improvements
  • Make the body field of the email:Message record optional. This enables sending an email with only the htmlBody field set without a text-typed body field.

  • Add mime:Entity type to the union type of the attachments field in the email:Message record. That enables attaching a single MIME Entity as an attachment. This email:Message record change would appear as follows.

  • The above-mentioned changes related to the body and attachments fields are updated in the email:Options record as given below in order to facilitate the same in the sendEmail method in the email:SmtpClient.
  • Remove the properties field representing custom properties from all Email module related configuration records: email:SmtpConfig, email:PopConfig, email:ImapConfig, email:PopListenerConfig, and email:ImapListenerConfig.

  • The mail.smtp.ssl.checkserveridentity custom property was passed as an entry in the properties to enable/disable the server certificate’s hostname verification. As the properties field is removed from the API, from this release onwards, the verifyHostName boolean field is introduced to the secureSocket record for all the configurations related to the Email module.

This email:SecureSocket record change would appear as follows.

UDP module improvements
  • The sendDatagram method will now send multiple datagrams if the size of the byte[] value provided as the data field of the datagram exceeds 8KB.

  • Returning Datagram from the onDatagram or onBytes remote methods also sends multiple datagrams if the size of the byte[] value provided (as the data field of the datagram) exceeds 8KB.

Crypto module improvements

Added support to decode private keys from .key files and public keys from .cert files and updated the APIs for decoding private/public keys. This enables reading private/public keys from PEM files.

JWT module improvements

Extended the private key support for JWT signature generation and public cert support for JWT signature validation.

Log module improvements

Introduced a configuration in the log module to set the output format to JSON. You need to add the entry below in the Config.toml file to set the output format to JSON.

Code to Cloud

  • The Kubernetes.toml file is renamed to Cloud.toml.
  • The --cloud=docker build option is implemented. This will build the Dockerfile and Docker image without generating the Kubernetes artifacts.

Developer tools

Language Server

Implemented renaming support in the Language Server. Now, VSCode users are able to select a symbol and rename all occurrences within the same module as well as across modules.

Debugger

Added variable paging support. With this feature, the Ballerina variables, which contain a large number of child variables will be shown in a paged view in the debug variable presentation.

Ballerina Shell REPL [EXPERIMENTAL]
  • Fixed the REPL expression output to output the toBalString() result.
  • Improved the REPL parser to support some partial snippets such as the example cases below.
    • Template strings will allow continuing on new lines.
    • The CLI will wait for more input if the last character was an operator.
    • The CLI will not wait for unclosed double quotes.
  • Enabled REPL to exit on Ctrl+D.

Breaking changes

  • Member access on a value of type table now returns () if the table does not contain a member with the specified key. Otherwise, the result is the member in the table value with the given key.
  • Iterating over xml in a from clause in query expressions now returns xml and iterating over xml<T> returns T.
  • Variables of types readonly and value:Cloneable cannot be assigned to any since they may contain values of type error.