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/builtin
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
Represents the AuthenticationContext, populated with authenticated information.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
scheme | string | ||
authToken | string |
public type CallFailedException
Representation of `CallFailedException`
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | Error message |
|
cause | error? | optional |
|
causes | error[]? | optional array of |
public type CallStackElement
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
Representation of `IllegalStateException`
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | error message |
|
cause | error? | optional error cause |
public type InvocationContext
Represents the InvocationContext.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
id | string | ||
userPrincipal | runtime:0.0.0:UserPrincipal | ||
authContext | runtime:0.0.0:AuthContext | ||
attributes | map |
public type NullReferenceException
Representation of `NullReferenceException`
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | error message |
|
cause | error? | optional error cause |
public type UserPrincipal
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 |
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 |
Return Type | Description | ||
---|---|---|---|
CallStackElement |
|
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 |