ballerina/runtime package

Package overview

This package includes functions to interact with the runtime, the invocation context and to manage errors.

Invocation Context

The Invocation Context is a data holder that is created per request and preserved for a single request-response flow. The Invocation Context comprises of a unique ID, a UserPrincipal instance that includes user details and an AuthContext instance that has the authentication related details if available.

Errors

The runtime package includes the NullReferenceException and IllegalStateException error types. These two error types wrap the error type defined in the ballerina/runtime package. Furthermore, there are utility methods to retrieve the current call stack and the particular call stack frame for an error.

Additionally, the runtime package also contains utility methods to halt a worker (sleep) for a given period of time and to look up properties from the runtime context.

Samples

The following sample shows how to access the Invocation Context, set data to it and access the same.

import ballerina/runtime;
import ballerina/io;

// set data to the Invocation Context
// set the username ‘tom’ as the user name
runtime:getInvocationContext().userPrincipal.username = "tom";
// set claims
map claims = { email: "tom@ballerina.com", org: "wso2" };
runtime:getInvocationContext().userPrincipal.claims = claims;
// set scopes
string[] scopes = ["email", "profile"];
runtime:getInvocationContext().userPrincipal.scopes = scopes;
// set auth scheme
runtime:getInvocationContext().authContext.scheme = "jwt";
// set auth token
runtime:getInvocationContext().authContext.authToken = "abc.pqr.xyz";

// retrieve data from the invocation context
// retrieve user name
string userName = runtime:getInvocationContext().userPrincipal.username;
io:println(userName);
// retrieve claims
map retrievedClaims = <map>runtime:getInvocationContext().userPrincipal.claims;
io:println(retrievedClaims);
// retrieve scopes
string[] retrievedScopes = runtime:getInvocationContext().userPrincipal.scopes;
io:println(retrievedScopes);
// retrieve auth scheme
string authScheme = runtime:getInvocationContext().authContext.scheme;
io:println(authScheme);
// retrieve auth token
string token = runtime:getInvocationContext().authContext.authToken;
io:println(token);

The following sample shows how to halt the current worker for a given time period.

import ballerina/runtime;

// sleep the current worker for 5 seconds
runtime:sleep(5000);

The following sample shows how to access properties from the runtime.

import ballerina/runtime;

// retrieve the property ‘ballerina version’ from the runtime
runtime:getProperty("ballerina.version");

The following sample shows how to create and throw and error and how to access the call stack for the error.

import ballerina/runtime;
import ballerina/io;

// prints the current call stack
io:println(runtime:getCallStack());

function throwError1 () {
    throwError2();
}

function throwError2 () {
    // creates an error with a message
    error e = { message: "error 2 occured" };
    throw e;
}

try {
    throwError1();
} catch (error e) {
    // prints the call stack frame for the error caught
    io:println(runtime:getErrorCallStackFrame(e));
}

Records Summary

Record Description
AuthContext Represents the AuthenticationContext, populated with authenticated information.
CallFailedException Representation of `CallFailedException`
CallStackElement Representation of `CallStackElement`
IllegalStateException Representation of `IllegalStateException`
InvocationContext Represents the InvocationContext.
NullReferenceException Representation of `NullReferenceException`
UserPrincipal Represents the UserPrincipal, populated with authenticated user information.

Functions Summary

Return Type Function and Description
CallStackElement[] getCallStack()

Retrieves the Call Stack

CallStackElement getErrorCallStackFrame(error? e)

Retrieves the Call Stack Frame for a particular error

InvocationContext getInvocationContext()

Creates a InvocationContext instance.

string getProperty(string name)

Returns the value associated with the specified property name.

sleep(int millis)

Halts the current worker for a predefined amount of time.

public type AuthContext record

Represents the AuthenticationContext, populated with authenticated information.

Field Name Data Type Default Value Description
scheme string
authToken string

public type CallFailedException record

Representation of `CallFailedException`

Field Name Data Type Default Value Description
message string

Error message

cause error?

optional error instance

causes error[]?

optional array of error instances

public type CallStackElement record

Representation of `CallStackElement`

Field Name Data Type Default Value Description
callableName string

Callable name

packageName string

Package name

fileName string

File name

lineNumber int

Line number

public type IllegalStateException record

Representation of `IllegalStateException`

Field Name Data Type Default Value Description
message string

error message

cause error?

optional error cause

public type InvocationContext record

Represents the InvocationContext.

Field Name Data Type Default Value Description
id string
userPrincipal runtime:UserPrincipal
authContext runtime:AuthContext
attributes map

public type NullReferenceException record

Representation of `NullReferenceException`

Field Name Data Type Default Value Description
message string

error message

cause error?

optional error cause

public type UserPrincipal record

Represents the UserPrincipal, populated with authenticated user information.

Field Name Data Type Default Value Description
userId string
username string
claims map
scopes string[]

public function getCallStack() returns (CallStackElement[])

Retrieves the Call Stack

Return Type Description
CallStackElement[]

Array of CallStackElement elements

public function getErrorCallStackFrame(error? e) returns (CallStackElement)

Retrieves the Call Stack Frame for a particular error

Parameter Name Data Type Default Value Description
e error?

optional error instance

Return Type Description
CallStackElement

CallStackElement instance

public function getInvocationContext() returns (InvocationContext)

Creates a InvocationContext instance.

Return Type Description
InvocationContext

InvocationContext instance

public function getProperty(string name) returns (string)

Returns the value associated with the specified property name.

Parameter Name Data Type Default Value Description
name string

Name of the property

Return Type Description
string

Value of the property if the property exists, an empty string otherwise

public function sleep(int millis)

Halts the current worker for a predefined amount of time.

Parameter Name Data Type Default Value Description
millis int

Amount of time to sleep in milliseconds