Red Hat Training

A Red Hat training course is available for JBoss Enterprise SOA Platform

4.2.6. Message Header Format

This is the format of a message header:
    public interface Header
{
	public Call getCall ();
	public void setCall (Call call);
}
The message header's contents are contained in an instance of the org.jboss.soa.esb.addressing.Call class:
    public class Call
{
	public Call ();
	public Call (EPR epr);
	public Call (Call copy);
	public void setTo (EPR epr);
	public EPR getTo () throws URISyntaxException;

	public void setFrom (EPR from);
	public EPR getFrom () throws URISyntaxException;

	public void setReplyTo (EPR replyTo);
	public EPR getReplyTo () throws URISyntaxException;

	public void setFaultTo (EPR uri);
	public EPR getFaultTo () throws URISyntaxException;

	public void setRelatesTo (URI uri);
	public URI getRelatesTo () throws URISyntaxException;
	public void copy();
	public void setAction (URI uri);
	public URI getAction () throws URISyntaxException;
	public final boolean empty();
	public void setMessageID (URI uri);
	public URI getMessageID () throws URISyntaxException;
	public String toString();
	public String stringForum();
	public boolean valid();
	public void copy (Call from);
}
The org.jboss.soa.esb.addressing.Call class supports both one-way and request-reply interaction patterns.

Table 4.1. org.jboss.soa.esb.addressing.Call Properties

Property Type Required Description
To EPR Yes The message recipient's address.
From EPR No The endpoint from which the message originated.
ReplyTo EPR No An endpoint reference that identifies the intended receiver for replies to this message. If a reply is expected, a message must contain a [ReplyTo]. The sender must use the contents of the [ReplyTo] to formulate the reply message. If the [ReplyTo] is absent, the contents of the [From] may be used to formulate a message to the source. This property may be absent if the message has no meaningful reply. If this property is present, the [MessageID] property is required.
FaultTo EPR No An endpoint reference that identifies the intended receiver for faults related to this message. When formulating a fault message the sender must use the contents of the [FaultTo] of the message being replied to to formulate the fault message. If the [FaultTo] is absent, the sender may use the contents of the [ReplyTo] to formulate the fault message. If both the [FaultTo] and [ReplyTo] are absent, the sender may use the contents of the [From] to formulate the fault message. This property may be absent if the sender cannot receive fault messages (for example, it is a one-way application message). If this property is present, the [MessageID] property is required.
Action URI Yes An identifier that uniquely (and opaquely) identifies the semantics implied by this message.
MessageID URI Depends A URI that uniquely identifies this message in time and space. No two messages with a distinct application intent may share a [MessageID] property. A message may be retransmitted for any purpose including communications failure and may use the same [MessageID] property. The value of this property is an opaque URI whose interpretation beyond equivalence is not defined. If a reply is expected, this property must be present.
Always consider the role of the header when developing and using services. For example, if you need a synchronous interaction pattern based upon request and response, be sure to set the ReplyTo field or a default endpoint reference will be used. Even with "request/response", the response need not go back to the original sender. Likewise, when sending one-way (no response) messages, do not set the ReplyTo field because it will be ignored.

Warning

Users should not rely on the internal formats of EPR directly because they are specific to implementations of the API. There is no guarantee the format will remain the same for them.

Note

The message header is formed in conjunction with the message. It is immutable once it has been transmitted between endpoints. Although the interfaces allow the recipient to modify the individual values, the JBoss Enterprise SOA Platform will ignore such modifications. (In future releases it is likely that such modifications will also be disallowed by the application programming interface, in order to improve clarity.) These rules can be found in the WS-Addressing standards.