Module : runtime
Module overview
This module 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
AuthenticationContext
instance that has the authentication related details if available.
Errors
The runtime module includes the NullReferenceException
and IllegalStateException
error types. These two error
types wrap the error
type defined in the ballerina/runtime
module. Furthermore, there are utility methods to
retrieve the current call stack and the particular call stack frame for an error.
Additionally, the runtime module 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/io;
import ballerina/runtime;
// Set data to the Invocation Context.
// Set the username as ‘tom’.
runtime:getInvocationContext().principal.username = "tom";
// Set claims.
map<any> claims = { email: "tom@ballerina.com", org: "wso2" };
runtime:getInvocationContext().principal.claims = claims;
// Set scopes.
string[] scopes = ["email", "profile"];
runtime:getInvocationContext().principal.scopes = scopes;
// Set auth scheme.
runtime:getInvocationContext().authenticationContext.scheme = "jwt";
// Set auth token.
runtime:getInvocationContext().authenticationContext.authToken = "abc.pqr.xyz";
// Retrieve data from the invocation context.
// Retrieve user name.
string userName = runtime:getInvocationContext().principal.username;
io:println(userName);
// Retrieve claims.
map<any> retrievedClaims = runtime:getInvocationContext().principal.claims;
io:println(retrievedClaims);
// Retrieve scopes.
string[] retrievedScopes = runtime:getInvocationContext().principal.scopes;
io:println(retrievedScopes);
// retrieve auth scheme.
string authScheme = runtime:getInvocationContext().authenticationContext.scheme;
io:println(authScheme);
// Retrieve auth token.
string token = runtime:getInvocationContext().authenticationContext.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 access the call stack and how to trap an error.
import ballerina/io;
import ballerina/runtime;
public function main() {
// Print the current call stack.
io:println(runtime:getCallStack());
var errorMessage = trap getError();
if (errorMessage is error) {
io:println(errorMessage.reason());
}
}
function getError() {
panicWithError();
}
function panicWithError() {
// Create an error with a reason.
error e = error("error occurred");
panic e;
}
AuthenticationContext | Represents the AuthenticationContext, populated with authenticated information. |
CallStackElement | Representation of `CallStackElement` |
InvocationContext | Represents the InvocationContext. |
Principal | Represents the Principal, populated with authenticated user information. |
getCallStack | Retrieves the Call Stack |
getInvocationContext | Creates a InvocationContext instance. |
getProperty | Returns the value associated with the specified property name. |
sleep | Halts the current worker for a predefined amount of time. |
timeout | Gives a timeout to the current worker for a predefined amount of time. |