org.jboss.soa.esb.message
Interface Body

All Known Subinterfaces:
BytesBody, MapBody, ObjectBody, TextBody

public interface Body

The message body holds arbitrary information which represents the payload as far as clients and services are concerned. A body may contain: (i) a byte array for arbitrary data. How that array is interpreted by the service is implementation specific and outside the scope of the ESB to enforce. (ii) a list of Objects of arbitrary types. How these objects are serialized to/from the message body when it is transmitted is up to the specific Object type. The plan is to add support for various TYPES of Object and the message implementation will use external adapters to externalize/internalize the Objects. Currently we only support Serializable objects. Given that there are attachments, properties, byte arrays and named objects, you may be wondering where should you put your payload? The answer is fairly straightforward: As a service developer, you define the contract that clients use in order to interact with your service. As part of that contract, you will specific both functional and non-functional aspects of the service, e.g., that it is an airline reservation service (functional) and that it is transactional (non-functional). You'll also define the operations (messages) that the service can understand. As part of the message definition, you stipulate the format (e.g., Java Serialized message versus XML) and the content (e.g., transaction context, seat number, customer name etc.) When defining the content, you can specify where in the Message your service will expect to find the payload. That can be in the form of attachments, specific named objects (even the default named object if you so wish), or the byte array. It is entirely up to the service developer to determine. The only restrictions are that objects and attachments must be globally uniquely named, or one service (or Action) may inadvertently pick up a partial payload meant for another if the same Message Body is forwarded across multiple hops. As a service users, you obtain the contract definition about the service (e.g., through UDDI or out-of-band communication) and this will define where in the message the payload must go. Information placed in other locations will likely be ignored and result in incorrect operation of the service. Note, in order to maintain loose coupling, services should not expose any backend implementation choices. As such you should try to avoid sending Java Serialized instances within the Body where possible because it does limit your future choices on service implementation to Java and potentially specific versions of Java.


Field Summary
static java.lang.String DEFAULT_LOCATION
           
 
Method Summary
 void add(java.lang.Object value)
          Add the specified Object at the default location within the message.
 void add(java.lang.String name, java.lang.Object value)
          Add the specified Object to the body.
 java.lang.Object get()
          Get the Object at the default location in the message, or null otherwise.
 java.lang.Object get(java.lang.String name)
          Get the specified Object, or null if not present.
 byte[] getByteArray()
          Deprecated. As of 4.2 you can use get(BytesBody.BYTES_LOCATION)
 byte[] getContents()
          Deprecated. As of 4.2 you can use get(BytesBody.BYTES_LOCATION)
 java.lang.String[] getNames()
           
 void merge(Body b)
          Merge two bodies.
 java.lang.Object remove(java.lang.String name)
          Remove the specified Object and return it, or null if not present.
 void replace(Body b)
          Replace this body instance with the one given.
 void setByteArray(byte[] content)
          Deprecated. As of 4.2 you can use add(BytesBody.BYTES_LOCATION, content)
 void setContents(byte[] content)
          Deprecated. As of 4.2 you can use add(BytesBody.BYTES_LOCATION, content)
 

Field Detail

DEFAULT_LOCATION

static final java.lang.String DEFAULT_LOCATION
See Also:
Constant Field Values
Method Detail

add

void add(java.lang.Object value)
Add the specified Object at the default location within the message. If the default location is already used then the contents will be overwritten.

Parameters:
value -

add

void add(java.lang.String name,
         java.lang.Object value)
Add the specified Object to the body.

Parameters:
name - The name of the object. MUST be unique within this body. If null then an exception will be thrown. This is to make sure that some computational errors don't arbitrarily resolve to data within the message body that could then be misinterpreted. If someone wants to go with the default name then they can either use add(value) or explicitly use the default name.
value - The Object to add.

get

java.lang.Object get()
Get the Object at the default location in the message, or null otherwise.

Returns:
the object.

get

java.lang.Object get(java.lang.String name)
Get the specified Object, or null if not present.

Parameters:
name - the name of the Object to retrieve. If null then an exception will be thrown. This is to make sure that some computational errors don't arbitrarily resolve to data within the message body that could then be misinterpreted. If someone wants to go with the default name then they can either use add(value) or explicitly use the default name.
Returns:
the Object.

remove

java.lang.Object remove(java.lang.String name)
Remove the specified Object and return it, or null if not present.

Parameters:
name - the name of the Object to remove.
Returns:
the Object removed.

setContents

void setContents(byte[] content)
Deprecated. As of 4.2 you can use add(BytesBody.BYTES_LOCATION, content)

Set the byte content of the body. This does not affect any of the named objects or attachments.

Parameters:
content - the message bytes

getContents

byte[] getContents()
Deprecated. As of 4.2 you can use get(BytesBody.BYTES_LOCATION)

Returns:
the byte content of the body.

setByteArray

void setByteArray(byte[] content)
Deprecated. As of 4.2 you can use add(BytesBody.BYTES_LOCATION, content)

Set the byte content of the body. This does not affect any of the named objects or attachments.

Parameters:
content - the message bytes

getByteArray

byte[] getByteArray()
Deprecated. As of 4.2 you can use get(BytesBody.BYTES_LOCATION)

Returns:
the byte content of the body.

replace

void replace(Body b)
Replace this body instance with the one given.

Parameters:
b - the body to be replaced with.

merge

void merge(Body b)
Merge two bodies. Any duplicate entries in the current instance will be lost in favour of the new instance.

Parameters:
b - the body to be merged with.

getNames

java.lang.String[] getNames()
Returns:
get the list of names in this instance.