

Property Mediator¶

The Property Mediator has no direct impact on the message, but rather on the message context flowing through Synapse. You can retrieve the properties set on a message later through the Synapse XPath Variables or the get-property() extension function. A property can have a defined scope for which it is valid. If a property has no defined scope, it defaults to the Synapse message context scope. Using the property element with the action specified as remove, you can remove any existing message context properties.

Info

The Property mediator is a conditionally content aware mediator.

Syntax¶

<property name="string" [action=set|remove] [type="string"] (value="literal" | expression="xpath") [scope=default|transport|axis2|axis2-client] [pattern="regex" [group="integer"]]>
    <xml-element/>?
</property>

Configuration¶

The parameters available for configuring the Property mediator are as follows:

Parameter Name	Description
Name	A name for the property. You can provide a static value or a dynamic value for the property name. A dynamic property name can be retrieved by using an XPath function. You can use any of the XPath functions that you use for the property value or property expression. Note that the XPath function should be contained within curly brackets (`{}`) as well as double quotations (`""`). See the examples given below. `property name="{get-property('propertyName')}"` `property name="{$ctx:propertyName}"` `property name="{json-eval({$ctx:propertyName})}"` For names of the generic properties that come by default, see Generic Properties . You can select them from the drop-down list if you are adding the Property Mediator as shown below.
Action	The action to be performed for the property. Set: If this is selected, the property will be set in the message context. Remove: If this is selected, the property will be removed from the message context.
Set Action As	The possible values for this parameter are as follows: Value: If this is selected, a static value would be considered as the property value and this value should be entered in the Value parameter. Expression: If this is selected, the property value will be determined during mediation by evaluating an expression. This expression should be entered in the Expression parameter.
Type	The data type for the property. Property mediator will handle the property as a property of selected type. Available values are as follows: STRING INTEGER BOOLEAN DOUBLE FLOAT LONG SHORT OM JSON String is the default type. The `OM` type is used to set xml property values on the message context. This is useful when the expression associated with the property mediator evaluates to an XML node during mediation. When the `OM` type is used, the XML is converted to an AXIOM OMElement before it is assigned to a property. The `JSON` type is used to set JSON values on the message context. It is recommended to use the JSON data type (rather than the STRING data type) for JSON payloads. Note that when the JSON is just a string, you need to add quotes around them. This is due to the restrictions in RFC. Example 1: Creating a property with a JSON string by giving the value. Example 2 : Creating a property with a JSON object via expression evaluation.
Value	If the Value option is selected for the Set Action As parameter, the property value should be entered as a constant in this parameter.
Expression	If the Expression option is selected for the Set Action As parameter, the expression which determines the property value should be entered in this parameter. This expression can be an XPath expression or a JSONPath expression. When specifying a JSONPath, use the format `json-eval(<JSON_PATH>)` , such as `json-eval(getQuote.request.symbol)`. In both XPath and JSONPath expressions, you can return the value of another property by calling `get-property(property-name)`. For example, you might create a property called `JSON_PATH` of which the value is `json-eval(pizza.toppings)` , and then you could create another property called `SON_PRINT` of which the value is `get-property('JSON_PATH')`, allowing you to use the value of the JSON_PATH property in the JSON_PRINT property.
Pattern	This parameter is used to enter a regular expression that will be evaluated against the value of the property or result of the XPath/JSON Path expression.
Group	The number (index) of the matching item evaluated using the regular expression entered in the Pattern parameter.
Scope	The scope at which the property will be set or removed from. Possible values are as follows. Synapse: This is the default scope. The properties set in this scope last as long as the transaction (request-response) exists. Transport: The properties set in this scope will be considered transport headers. For example, if it is required to send an HTTP header named 'CustomHeader' with an outgoing request, you can use the property mediator configuration with this scope. Axis2: Properties set in this scope have a shorter life span than those set in the Synapse scope. They are mainly used for passing parameters to the underlying Axis2 engine axis2-client: This is similar to the Synapse scope. The difference between the two scopes is that the axis2-client scope can be accessed inside the mediate() method of a mediator via a custom mediator created using the Class mediator. Operation: This scope is used to retrieve a property in the operation context level. Registry: This scope is used to retrieve properties within the registry . System: This scope is used to retrieve Java system properties. Environment: This scope is used to retrieve environment variables ('env'). File: This scope is used to retrieve properties defined in the `file.properties` configuration file ('file'). For a detailed explanation of each scope, see Accessing Properties with XPath.

Note

There are predefined XPath variables (such as $ctx ) that you can directly use in the Synapse configuration, instead of using the synapse:get-property() function. These XPath variables get properties of various scopes and have better performance than the get-property() function, which can have much lower performance because it does a registry lookup. These XPath variables get properties of various scopes. For more information on these XPath variables, see Accessing Properties with XPath.

Examples¶

Setting and logging and property¶

In this example, we are setting the property symbol and later we can log it using the Log Mediator.

<property name="symbol" expression="fn:concat('Normal Stock - ', //m0:getQuote/m0:request/m0:symbol)" xmlns:m0="http://services.samples/xsd"/>

<log level="custom">
    <property name="symbol" expression="$ctx:symbol"/>
</log>

Sending a fault message based on the Accept http header¶

In this configuration, a response is sent to the client based on the Accept header. The PayloadFactory mediator transforms the message contents. Then a Property mediator sets the message type based on the Accept header using the $ctx:accept expression. The message is then sent back to the client via the Respond mediator.

<payloadFactory media-type="xml">
    <format>
        <m:getQuote xmlns:m="http://services.samples">
            <m:request>
                <m:symbol>Error</m:symbol>
            </m:request>
        </m:getQuote>
    </format>
</payloadFactory>
<property name="messageType" expression="$ctx:accept" scope="axis2" />
<respond/>

Reading a property stored in the Registry¶

You can read a property that is stored in the Registry by using the get-property() method in your Synapse configuration. For example, the following Synapse configuration retrieves the abc property of the collection gov:/data/xml/collectionx , and stores it in the regProperty property.

<property name="regProperty" expression="get-property('registry', 'gov:/data/xml/collectionx@abc')"/>

Info

You can use the following syntax to read properties or resources stored in the gov or conf Registries. When specifying the path to the resource, do not give the absolute path. Instead, use the gov or conf prefixes.

Reading a property stored under a collection¶

get-property('registry','gov:<path to resource from governance>@<propertyname>')
get-property('registry','conf:<path to resource from config>@<propertyname>')

Reading a property stored under a resource¶

get-property('registry','gov:<path to resource from governance>/@<propertyname>')
get-property('registry','conf:<path to resource from config>/@<propertyname>')

Reading an XML resource¶

get-property('registry','gov:<path to resource from governance>')
get-property('registry','conf:<path to resource from config>')

Reading a file stored in the Registry¶

Following is an example, in which you read an XML file that is stored in the registry using XPath, to retrieve a value from it. Assume you have the following XML file stored in the Registry (i.e., gov:/test.xml ).

test.xml

<root>
  <book>A Song of Ice and Fire</book>
  <author>George R. R. Martin</author>
</root>

Your Synapse configuration should be as follows. This uses XPath to read XML.

reg_xpath.xml

<property name="xmlFile" expression="get-property('registry','gov:/test.xml')" scope="default" type="OM"></property>
<log level="custom">
    <property name="Book_Name" expression="$ctx:xmlFile//book"></property>
</log>

Your output log will look like this.

[2015-09-21 16:01:28,750]  INFO - LogMediator Book_Name = A Song of Ice and Fire

Reading SOAP headers¶

SOAP headers provide information about the message, such as the To and From values. You can use the get-property() function of the Property mediator to retrieve these headers. You can also add Custom SOAP Headers using the PayloadFactory mediator and the Script Mediator.

To¶

Property	Description
Header Name	To
Possible Values	Any URI
Description	The To header of the message.
Example	get-property("To")

From¶

Property	Description
Header Name	From
Possible Values	Any URI
Description	The From header of the message.
Example	get-property("From")

Action¶

Property	Description
Header Name	Action
Possible Values	Any URI
Description	The SOAPAction header of the message.
Example	get-property("Action")

ReplyTo¶

Property	Description
Header Name	ReplyTo
Possible Values	Any URI
Description	The ReplyTo header of the message.
Example	<header name="ReplyTo" action="remove"/>

MessageID¶

Property	Description
Header Name	MessageID
Possible Values	UUID
Description	The unique message ID of the message. It is not recommended to make alterations to this property of a message.
Example	get-property("MessageID")

RelatesTo¶

Property	Description
Header Name	RelatesTo
Possible Values	UUID
Description	The unique ID of the request to which the current message is related. It is not recommended to make changes.
Example	get-property("RelatesTo")

FaultTo¶

Property	Description
Header Name	FaultTo
Possible Values	Any URI
Description	The FaultTo header of the message.
Example	`<header name="FaultTo" value="http://localhost:9000"/>`

Top