WSO2 ESB Properties Tutorial

What Are Properties?

WSO2 ESB provides properties as a way to control different aspects of the messages flowing through the mediation engine. They will not change the content (payload) of the message, but they will be used to change the behavior of the message flowing through the ESB. The property mediator is used to access or modify the properties defined in the WSO2 ESB.

You can define a property mediator inside the ESB configuration language as below if you are setting a static value for the property.

<property name="TestProperty" value="Chanaka" scope="default" type="STRING">

If you are setting a dynamic value for the property, then you can use the following method.

<property name="TestProperty" expression="//m0:getQuote/m0:request/m0:symbol"

xmlns:m0="http://services.samples/xsd" scope="default" type="STRING">

In the above property declaration, you can find that we are defining a scope for the property. This scope definition will define the scope where this property can be visible inside the ESB.

1. default (Synapse)

Once you set a property under this scope, its value will be available throughout both the in- and out-sequences.

2. axis2

Once you set a property under this scope, its value will be available only throughout the sequence it's been set. If you set the Property mediator to the in-sequence, you cannot access it in the out-sequence.

3. axis2-client

This is similar to the Synapse scope. The difference is that you can access it in the following two ways inside a custom mediator:

public boolean mediate(org.apache.synapse.MessageContext mc) {
org.apache.axis2.context.MessageContext axis2MsgContext;
axis2MsgContext = ((Axis2MessageContext) mc).getAxis2MessageContext();
String propValue = (String) axis2MsgContext.getProperty("PropName");
System.out.println("SCOPE_AXIS2_CLIENT - 1 : " + propValue);

propValue = (String) axis2MsgContext.getOptions().getProperty("PropName");
System.out.println("SCOPE_AXIS2_CLIENT - 2: " + propValue);
return true;
}

4. transport

Once you set a property under this scope, it will be added to the transport header of the outgoing message from the ESB.

WSO2 has a huge set of mediators, but the property mediator is mostly used for writing any proxy service or API.

The property mediator is used to store any value or XML fragment temporarily during the lifecycle of a thread for any service or API.

We can compare the property mediator with Variables in any other traditional programming language, like C, C++, Java, .Net, etc.

There are a few properties that are used/maintained by the ESB itself, and on the other hand, a few properties can be defined by users (programmers). In other words, we can say that properties can be defined in the two categories below:

• ESB-defined properties

• User-defined properties

These properties can be stored/defined in different scopes, like

• Transport
• Synapse or Default
• Axis2
• Registry
• System
• Operation

Generally, these properties are read by the get-properties() function. This function can be invoked with the following variations:

• get-property(String propertyName)
• get-property(String scope, String propertyName)

The first function doesn’t require passing a scope parameter, which always reads properties from the default/synapse scope.

Performance Implication (Found in ESB 4.9.0 and Prior Versions)

It has been discovered that use of the  get-properties()function degrades performance drastically for any service. The get-properties()  function first does an ESB Registry look-u,p and then later on difference scopes- however, using scope identifiers limits its search to the relevant area only. This additional registry look up has been improved in the ESB 5.0.0 release. Hence, you will not get the same performance impact (which was there prior to ESB 5.0.0) even if you use get-property in ESB 5.0.0. But using $ctx is always the best approach.

Solution (Reading Through Scope)

Instead of using get-properties(), these properties can be referenced by the below prefixes separated by a colon:

•  $ctx  – from Synapse or Default Scope
•  $trp  – from Transport scope
•  $axis2  – from Axis2 Scope
•  $Header  – Anything from Header
•  $body  – for accessing any element in SOAP Body (applicable for SOAP 1.1 and SOAP 1.2)

Let's assume that there is any property set with name “Test-Property.”

From Default Scope

<property name=”Read-Property-value” expression=”get-property(‘Test-Property’)”/>

<property name=”Read-Property-value” expression=”$ctx:Test-Property”/>

From Transport Scope

<property name=”Read-Property-value” expression=”get-property(‘transport’,’Test-Property’)”/>

<property name=”Read-Property-value” expression=”$trp:Test-Property”/>

From Axis2 Scope

<property name=”Read-Property-value” expression=”get-property(‘axis2′,’Test-Property’)”/>

<property name=”Read-Property-value” expression=”$axis2:Test-Property”/>

We should prefer to use the $ format to access these properties for better performance.

Note: This syntax cannot be used with a few ESB defined properties, mentioned below:

• OperationName

• MessageID

• To

Please make sure you are using the correct way to access ESB-defined properties.