mediation
Module mediation
API
Definitions
choreo/mediation
Functions
createImmutableMediationContext
function createImmutableMediationContext(string httpMethod, PathSegment[] segments, map<PathParamValue> pathParams, map<string[]> qParams) returns Context
Create a new immutable mediation:Context
object using the given conextual information.
Parameters
- httpMethod string - The HTTP method used in this particular context
- segments PathSegment[] - The resource path segments that make up the resource method represented by the context
- pathParams map<PathParamValue> - The path parameters of the represented resource
Return Type
- Context - A new mutable
mediation:Context
instance
createImmutableResourcePath
function createImmutableResourcePath(PathSegment[]|string path) returns ResourcePath|PathSegmentError
Creates an immutable mediation:ResourcePath
object. If the path is provided as a string, any segment of the path
written in the form {identifier}
will be interpreted as a path param. The type of the path param is fixed and
is considered as string
.
Parameters
- path PathSegment[]|string - The parts that make up the path or the path as a string
Return Type
- ResourcePath|PathSegmentError - An immutable instance of
mediation:ResourcePath
createMutableMediationContext
function createMutableMediationContext(Context originalCtx, PathSegment[] segments, map<PathParamValue> pathParams, map<string[]> qParams) returns Context
Create a new mutable mediation:Context
object using the given conextual information. The value passed to
mediation policy functions will be mutable values such as these.
Parameters
- originalCtx Context - Should be an original
mediation:Context
object. i.e., an immutablemediation:Context
instance.
- segments PathSegment[] - The resource path segments that make up the resource method represented by the context
- pathParams map<PathParamValue> - The path parameters of the represented resource
Return Type
- Context - A new mutable
mediation:Context
instance
createMutableResourcePath
function createMutableResourcePath(PathSegment[]|string path) returns ResourcePath|PathSegmentError
Creates a mutable mediation:ResourcePath
object. If the path is provided as a string, any segment of the path
written in the form {identifier}
will be interpreted as a path param. The type of the path param is fixed and
is considered as string
.
Parameters
- path PathSegment[]|string - The parts that make up the path or a path as a string.
Return Type
- ResourcePath|PathSegmentError - A mutable instance of
mediation:ResourcePath
Enums
mediation: PathParamKind
Represents the types of path parameters that one can come across.
Members
Annotations
mediation: FaultFlow
An annotation for marking a public function as the implmenting function of a policy for the
fault-flow of a mediation sequence. A function marked as FaultFlow
is expected to have the following
function parameter signature: (http:Response, http:Request, mediation:Context)
.
e.g.,
@mediation:FaultFlow public function addHeaderOut(http:Response errResp, error e, http:Response? resp, http:Request req, mediation:Context ctx) returns http:Response|false|error|() {}
mediation: RequestFlow
An annotation for marking a public function as the implmenting function of a policy for the
in-flow of a mediation sequence. A function marked as RequestFlow
is expected to have the following
function parameter signature: (http:Response, mediation:Context)
.
e.g.,
@mediation:RequestFlow public function addHeaderIn(http:Response resp, mediation:Context ctx) returns http:Response|false|error|() {}
mediation: ResponseFlow
An annotation for marking a public function as the implmenting function of a policy for the
out-flow of a mediation sequence. A function marked as ResponseFlow
is expected to have the following
function parameter signature: (http:Response, http:Request, mediation:Context)
.
e.g.,
@mediation:ResponseFlow public function addHeaderOut(http:Response resp, http:Request req, mediation:Context ctx) returns http:Response|false|error|() {}
Records
mediation: PathParam
Represents a path parameter segment in a resource path.
Fields
- 'type typedesc<PathParamValue> - The type of the path parameter
- name string - The name of the path parameter
- kind PathParamKind - The type of path parameter
Errors
mediation: PathSegmentError
Represents an error occurred when working with resource path segments.
Object types
mediation: Context
Defines the API for a key-value store for sharing information with the policy implementations as well as
across the policies. A parameter of this type is required to be there in the function signature of a policy function.
There can be 2 types of implementations of this object: an original mediation:Context
and a
shared mediation:Context
. An original mediation:Context
object captures the initial information of a resource.
Any policy attached to the resource needs to be able to access the unmodified contextual information of the
resource. Therefore, an original mediation:Context
implementation should be immutable. A shared
mediation:Context
object is meant to be shared across policy functions and thus meant to be mutable.
Since it's shared and mutable, by the time the proxy makes the request to the backend, the context will contain
the cumulative changes done to the context of the resource across all attached policies.
get
function get(string name) returns anydata
Retrieves the value for the specified key.
Parameters
- name string - The lookup key
Return Type
- anydata - The value
getOrDefault
function getOrDefault(string name, anydata default) returns anydata
Retrieves the value for the specified key. If there is no mapping for the key, returns the specified default value.
Parameters
- name string - The lookup key
- default anydata - The default value to use in the absence of a mapping
Return Type
- anydata - Returns the value if there is a mapping or else the default value
hasKey
Checks whether a mapping exists for the specified key.
Parameters
- name string - Key to look up
Return Type
- boolean - Returns true if there is a mapping for the key
put
function put(string name, anydata value)
Stores the provided key-value pair. If a mapping exists for the key, the value is overwritten.
remove
function remove(string name) returns anydata
Removes the entry mapped by the specified key and returns the removed value.
Parameters
- name string - The lookup key
Return Type
- anydata - The removed value
originalContext
function originalContext() returns Context
Returns the mediation:Context
instance which captured the initial contextual information of the resource,
before the mediation flow was invoked. Calling this on an original mediation:Context
object will return itself.
Return Type
- Context - The original
mediation:Context
object from which thismediation:Context
object was derived
httpMethod
function httpMethod() returns string
The HTTP method of the resource method.
Return Type
- string - The HTTP method
resourcePath
function resourcePath() returns ResourcePath
Retrieves an instance of mediation:ResourcePath
which is an API for contextual information on the resource path
of this resource. It also contains methods for modifying the resource path as the user sees fit. This resource
path is the same path used by the mediation service for deriving the backend endpoint's resource to invoke.
Therefore, the default behaviour of the mediation service is to invoke a resource in the backend endpoint which
has the same relative resource path as the corresponding mediation service resource.
Return Type
- ResourcePath - The
mediation:ResourcePath
object associated with this context
setResourcePath
function setResourcePath(ResourcePath path)
Sets the given mediation:ResourcePath
instance as the resource path of this context.
Parameters
- path ResourcePath - Parameter Description
addPathParamValue
function addPathParamValue(string name, PathParamValue value)
Adds a mapping between a path param name and a resolved value for it. There need not be a path parameter in the
resource path by the name specified in name
for one to use this method. On its own, the path param values have
no bearing on the resource path.
Parameters
- name string - Path parameter name
- value PathParamValue - Resolved value for the specified path parameter
resolvedPathParams
function resolvedPathParams() returns map<PathParamValue> & readonly
Returns the collection of resolved values for the path parameters in this particular context, mapped by the parameter name.
Return Type
- map<PathParamValue> & readonly - Map of resolved path parameter values
removePathParamValue
function removePathParamValue(string name)
Removes the resolved path parameter value which maps to the specified name.
Parameters
- name string - Name of the path parameter value to be removed
addQueryParam
Adds a query parameter to the request to be sent to the backend. If there is already a query parameter by the same name, the new value will be appended to it, making it an array.
removeQueryParam
function removeQueryParam(string name)
Removes the specified query parameter from the request. If the value of the parameter is an array, the whole array will be removed.
Parameters
- name string - Name of the query parameter to remove
queryParams
Retrieves a map of all the query params in the current request context. The returned map is a readonly snapshot of the map of query parameterss in the context at the time this method was called.
mediation: ResourcePath
get
function get(int i) returns PathSegment & readonly
Parameters
- i int -
pathSegments
function pathSegments() returns PathSegment[] & readonly
insert
function insert(int i, PathSegment segment) returns PathSegmentError?
replace
function replace(int i, PathSegment segment) returns PathSegmentError?
remove
function remove(int i) returns PathSegment|PathSegmentError
Parameters
- i int -
resolve
function resolve(map<PathParamValue> pathParamValues) returns string|error
Parameters
- pathParamValues map<PathParamValue> -
toString
function toString() returns string
length
function length() returns int
Union types
Import
import choreo/mediation;
Metadata
Released date: almost 2 years ago
Version: 0.7.0
Compatibility
Platform: any
Ballerina version: 2201.2.3
GraalVM compatible: Yes
Pull count
Total: 53949
Current verison: 151
Weekly downloads
Dependencies