## Apache Synapse

## Properties Catalog

Properties provide the means of accessing various types of information regarding a message that passes through the ESB. Furthermore, it is also possible to use properties to control the behavior of the ESB on a given message flow.

## Content

- Introduction
- Contents
- Generic Properties
  - PRESERVE_WS_ADDRESSING
  - RESPONSE
  - OUT_ONLY
  - ERROR_CODE
  - ERROR_MESSAGE
  - ERROR_DETAIL
  - ERROR_EXCEPTION
  - TRANSPORT_HEADERS
  - messageType
  - ContentType
  - preserveProcessedHeaders
  - SERVER_IP
- HTTP Transport Properties
  - POST_TO_URI
  - FORCE_SC_ACCEPTED
  - DISABLE_CHUNKING
  - NO_ENTITY_BODY
  - FORCE_HTTP_1.0
  - HTTP_SC
  - FAULTS_AS_HTTP_200
  - NO_KEEPALIVE
  - REST_URL_POSTFIX
  - REQUEST_HOST_HEADER
  - FORCE_POST_PUT_NOBODY
  - FORCE_HTTP_CONTENT_LENGTH
  - COPY_CONTENT_LENGTH_FROM_INCOMING
  - COPY_CONTENT_LENGTH_FROM_INCOMING
- Synapse Message Context Properties
  - SYSTEM_DATE
  - SYSTEM_TIME
  - MESSAGE_FORMAT
  - OperationName

## Generic Properties

Generic properties allow to configure or change the behavior of the message flow as they are processed by the ESB.

### PRESERVE_WS_ADDRESSING

By default, the ESB adds a new set of WS-Addressing headers to the messages forwarded from the ESB. If this property is set to "true" on a message, the ESB will forward it without altering its existing WS-Addressing headers.

`Possible Values`
  "true", "false"
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="PRESERVE_WS_ADDRESSING" value="true"/>

### RESPONSE

Once this property is set to 'true' on a message, the ESB will start treating it as a response message. It is generally used to route a request message back to its source as the response. However, currently respond mediator perform the same functionality.

`Possible Values`
  "true", "false"
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="RESPONSE" value="true"/>

### OUT_ONLY

Set this property to "true" on a message to indicate that no response message is expected for it once it is forwarded from the ESB. In other words, the ESB will do an out-only invocation with such messages. It is very important to set this property on messages that are involved in out-only invocations to prevent the ESB from registering unnecessary callbacks for response handling and eventually running out of memory.

`Possible Values`
  "true", "false"
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="OUT_ONLY" value="true"/>

### ERROR_CODE

Use this property to set a custom error code on a message which can be later processed by a Synapse fault handler. If the Synapse encounters an error during mediation or routing, this property will be automatically populated.

`Possible Values`
  String
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="error-code" expression="get-property('ERROR_CODE')"/>

### ERROR_MESSAGE

Use this property to set a custom error message on a message which can be later processed by a Synapse fault handler. If the Synapse encounters an error during mediation or routing, this property will be automatically populated.

`Possible Values`
  String
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="Cause" expression="get-property('ERROR_MESSAGE')"/>

### ERROR_DETAIL

Use this property to set the exception stacktrace in case of an error. If the ESB encounters an error during mediation or routing, this property will be automatically populated.

`Possible Values`
  String
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="Trace" expression="get-property('ERROR_DETAIL')"/>

### ERROR_EXCEPTION

Contains the actual exception thrown in case of a runtime error.

`Possible Values`
  String
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="error-exception" expression="get-property('ERROR_EXCEPTION')"/>

### TRANSPORT_HEADERS

Contains the map of transport headers. Automatically populated. Individual values of this map can be accessed using the property mediator in the transport scope.

`Possible Values`
  java.util.Map
`Default Behavior`
  Populated with the transport headers of the incoming request.
`Scope`
  axis2
`Example`
  <property name="TRANSPORT_HEADERS" action="remove" scope="axis2"/>

### messageType

Message formatter is selected based on this property. This property should have the content type, such as text/xml, application/xml, or application/json.

`Possible Values`
  string
`Default Behavior`
  Content type of incoming request.
`Scope`
  axis2
`Example`
  <property name="messageType" value="text/xml" scope="axis2"/>

### ContentType

This property will be in effect only if the messageType property is set. If the messageType is set, the value of Content-Type HTTP header of the outgoing request will be chosen based on this property. Note that this property is required to be set only if the message formatter seeks it in the message formatter implementation.

`Possible Values`
  string
`Default Behavior`
  Value of the Content-type header of the incoming request.
`Scope`
  axis2
`Example`
  <property name="ContentType" value="text/xml" scope="axis2"/>

### preserveProcessedHeaders

By default, Synapse removes the SOAP headers of incoming requests that have been processed. If we set this property to 'true', Synapse preserves the SOAP headers.

`Possible Values`
  "true", "false"
`Default Behavior`
  Preserving SOAP headers
`Scope`
  synapse
`Example`
  <property name="preserveProcessedHeaders" value="true" scope="default"/>

### SERVER_IP

Server IP/Host name of hosted server

`Possible Values`
  string
`Default Behavior`
  Set automatically by the mediation engine upon startup with IP address or hostname of the ESB host
`Scope`
  synapse
`Example`
  <property name="StringServerIp" expression="get-property('SERVER_IP')" scope="default" type="STRING"/>

## HTTP Transport Properties

HTTP transport properties allow to control and configure how the HTTP transport processes the ongoing messages.

### POST_TO_URI

This property makes the outgoing URL of the ESB a complete URL. This is important when we talk through a Proxy Server.

`Possible Values`
  "true", "false"
`Default Behavior`
  false
`Scope`
  axis2
`Example`
  <property name="POST_TO_URI" scope="axis2" value="true"/>

### FORCE_SC_ACCEPTED

When set to true, this property forces a 202 HTTP response to the client so that it stops waiting for a response.

`Possible Values`
  "true", "false"
`Default Behavior`
  false
`Scope`
  axis2
`Example`
  <property name="FORCE_SC_ACCEPTED" scope="axis2" value="true"/>

### DISABLE_CHUNKING

Disables the HTTP chunking for outgoing messaging.

`Possible Values`
  "true", "false"
`Default Behavior`
  false
`Scope`
  axis2
`Example`
  <property name="DISABLE_CHUNKING" scope="axis2" value="true"/>

### NO_ENTITY_BODY

This property should be removed if a user want to generate a response from the ESB to a request without an entity body, for example, GET request.

`Possible Values`
  "true", "false"
`Default Behavior`
  false
`Scope`
  axis2
`Example`
  <property name="NO_ENTITY_BODY" scope="axis2" value="true"/>

### FORCE_HTTP_1.0

Force HTTP 1.0 for outgoing HTTP messages.

`Possible Values`
  "true", "false"
`Default Behavior`
  false
`Scope`
  axis2
`Example`
  <property name="FORCE_HTTP_1.0" scope="axis2" value="true"/>

### HTTP_SC

Set the HTTP status code.

`Possible Values`
  HTTP status code number
`Default Behavior`
  none
`Scope`
  axis2
`Example`
  <property name="HTTP_SC" value="500" scope="axis2"/>

### FAULTS_AS_HTTP_200

Set the HTTP status code.

`Possible Values`
  "true", "false"
`Default Behavior`
  false
`Scope`
  axis2
`Example`
  <property name="FAULTS_AS_HTTP_200" value="true" scope="axis2"/>

### NO_KEEPALIVE

Disables HTTP keep alive for corresponded connection flow. This Can be use in both inflow and outflow.

`Possible Values`
  "true", "false"
`Default Behavior`
  false
`Scope`
  axis2
`Example`
  <property name="NO_KEEPALIVE" value="true" scope="axis2"/>

### REST_URL_POSTFIX

The value of this property will be appended to the target URL when sending messages out in a RESTful manner through an address endpoint. This is useful when you need to append a context to the target URL in case of RESTful invocations. If you are using an HTTP endpoint instead of an address endpoint, specify variables in the format of "uri.var.*" instead of using this property.

`Possible Values`
  A URL fragment starting with "/"
`Default Behavior`
  In the case of GET requests through an address endpoint, this contains the query string.
`Scope`
  axis2
`Example`
  <property name="REST_URL_POSTFIX" value="/context" scope="axis2"/>

### REQUEST_HOST_HEADER

The value of this property will be set as the HTTP host header of outgoing request.

`Possible Values`
  string
`Default Behavior`
  ESB will set hostname of target endpoint and port as the HTTP host header
`Scope`
  axis2
`Example`
  <property name="REQUEST_HOST_HEADER" value="www.wso2.org" scope="axis2"/>

### FORCE_HTTP_CONTENT_LENGTH

This property allows the content length to be sent when the ESB sends a request to a back end server. When HTTP 1.1 is used, this property disables chunking and sends the content length. When HTTP 1.0 is used, the property only sends the content length. This property should be set in scenarios where the backend server is not able to accept chunked content.

`Possible Values`
  "true", "false"
`Default Behavior`
  false
`Scope`
  axis2
`Example`
  <property name="FORCE_HTTP_CONTENT_LENGTH" scope="axis2" value="true"/>

### COPY_CONTENT_LENGTH_FROM_INCOMING

This property allows the HTTP content length to be copied from an incoming message. It is only valid when the FORCE_HTTP_CONTENT_LENGTH property is used. The COPY_CONTENT_LENGTH_FROM_INCOMING avoids buffering the message in memory for calculating the content length, thus reducing the risk of performance degradation.

`Possible Values`
  "true", "false"
`Default Behavior`
  false
`Scope`
  axis2
`Example`
  <property name="COPY_CONTENT_LENGTH_FROM_INCOMING" scope="axis2" value="true"/>

## Synapse Message Context Properties

Synapse Message Context Properties allow to retrieve the data related to synapse mediation engine information for current message flow.

### SYSTEM_DATE

Returns the current date as a String. Optionally, a date format as per the standard date format may be supplied. e.g. synapse:get-property("SYSTEM_DATE", "yyyy.MM.dd G 'at' HH:mm:ss z") or get-property('SYSTEM_DATE').

`Possible Values`
  string
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="StringDateVal" expression="get-property('SYSTEM_DATE')" scope="default" type="STRING"/>

### SYSTEM_TIME

Returns the current time in milliseconds.

`Possible Values`
  string
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="StringTimeVal" expression="get-property('SYSTEM_TIME')" scope="default" type="STRING"/>

### MESSAGE_FORMAT

Returns pox, soap11, soap12 depending on the message. If a message type is unknown this returns soap12.

`Possible Values`
  string
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="StringMessageFormat" expression="get-property('MESSAGE_FORMAT')" scope="default" type="STRING"/>

### OperationName

Returns the operation name corresponding to the message.

`Possible Values`
  string
`Default Behavior`
  none
`Scope`
  synapse
`Example`
  <property name="StringOperationName" expression="get-property('OperationName')" scope="default" type="STRING"/>