Use the HTTP Header Setter primitive to create, modify,
copy or delete HTTP message headers.
Introduction
The HTTP Header Setter mediation
primitive provides a mechanism for managing HTTP headers in the message.
You can change, copy, add, or delete HTTP headers by setting the mediation
primitive properties.
If you want multiple header changes you
can set multiple actions. Multiple actions are acted on sequentially,
in the order in which they are specified; this means that header changes
can build on each other.
You can create new HTTP headers by
specifying header field values. You can search for HTTP headers that
already exist in the SMO by specifying the header name to match on.
If a matching header is found, it can then be deleted from the message,
copied to another location in the SMO, or have the value set. If a
matching header is not found, a new header can be created using a
specified header field value.
The HTTP Header Setter mediation
primitive has one input terminal (in), one output terminal (out) and
a fail terminal (fail). The in terminal is wired to accept a message
and the other terminals are wired to propagate a message. If the mediation
is successful, the out terminal propagates the modified message. If
an exception occurs during the transformation, the fail terminal propagates
the original message, together with any exception information contained
in the failInfo element.
The HTTP Header Setter mediation primitive
uses the given header name to determine where to look in the SMO.
There are three different types of HTTP Header, distinguished by name
and their location in the SMO.
- HTTP Control Headers, which have their own schema in the SMO,
located at /headers/HTTPHeader/control. The names of these headers
are relative XPaths.
- HTTP Spec Headers, which are listed in the SMO at /headers/HTTPHeader/header.
The names of these headers are from the HTTP 1.1 spec
- Any other headers are User Headers and are listed at /headers/properties.
Usage
You can use the HTTP Header Setter
mediation primitive to ensure that when a HTTP message is sent to
another system, via the HTTP binding, the headers that are sent with
the message are correctly set.
Because the operations you define
occur sequentially, a later operation can depend on an earlier operation.
For example, you could create a new header, copy it to elsewhere in
the SMO and then delete it from the list of headers it was initially
appended to.
You can also use the HTTP Header Setter mediation
primitive to help to filter messages, using the Message Filter mediation
primitive. You might want to find a particular header and make it
available to be used in the filtering.
Properties
- HTTP Header Elements
- HTTP Header elements on an SMO node.
- Mode
- If you want to create a new HTTP header, the Mode property must
be set to 'Create'.
- If you want to search for a HTTP header and then modify the value
of any header that is found, or create a new header if none are found,
the Mode property must be set to 'Modify'.
- If you want to search for a HTTP header and then copy the first
found header to another location in the SMO, the Mode property must
be set to Copy' .
- If you want to search for a HTTP header and then delete any headers
that are found, the Mode property must be set to 'Delete'.
- Header name
- You can specify a HTTP header field name; any HTTP headers in
the SMO that has a matching name can then be modified, copied, or
deleted.
- Set Value using XPath
- Determine whether the Value to set should be a literal value or
an XPath expression that identifies a source value to copy into the
HTTP header at runtime. This property is only used when the Mode property
is set to 'Create' or 'Modify'.
- Value
- If the Mode property is set to 'Create' or 'Modify', the Value
property should be set to a HTTP header literal value or an XPath
expression that identifies a value to copy into the HTTP header at
runtime. When a new HTTP header is created or a matching HTTP header
is found, this new value is set in the specified field.
- If the Mode property is set to 'Copy', the Value property should
be an XPath 1.0 expression, identifying the target element to where
the first found HTTP header will be copied.
- If the Mode property is set to 'Delete', the Value property should
not be set.
- Validate Input
- If true, causes the input message to be validated before the mediation
is performed.
Table 1. HTTP Header Setter mediation primitive
propertiesProperty |
Valid Values |
Default |
HTTP Header Elements |
Mode |
String: Create or Modify or Copy or Delete |
|
Header Name |
String: a field name |
|
Set Value using XPath |
Boolean: true or false |
false |
Value |
String: An XPath expression or value |
|
Validate input |
|
Boolean: true or false |
false |
Considerations
Consider the following when
using the HTTP Header Setter mediation primitive:
- If the Mode property is "Modify" and a header cannot be found,
a new header will be created.
- If the XPath expression of the copy target resolves to more than
one element in the SMO, a runtime exception occurs.
- The location of the header within the SMO depends upon its type;
control, spec or user.
- If the Validate input property is true and the input message is
invalid, a runtime exception occurs.