Programming hints to help you when you are writing mediation
code.
- Take care to avoid looping in the Forward Routing Path. For example,
if you set a destination in the path that is the same as the current
destination, the message will endlessly circle, with the routing path
being reset to the current destination each time. The mediation framework
does not check for loops in routing paths.
- Avoid the use of static fields where possible. A single mediation
may be deployed to process multiple messages concurrently.
- Do not cache values computed from the message context or message
contents. Such values might change from message to message. The exception
is caching values derived solely from the mediation handler properties
for performance purposes.
- Mediation programming is subject to the same restrictions as programming
an EJB. For more information about restrictions, see Section 18.1.2
of the EJB 1.1 specification.
- Choose the appropriate level of transactional control for your
mediation: for example, a mediation that operates on fields within
a message is unlikely to have implications for transactional control.
At the other extreme, if your mediation updates database fields, it
requires transactional control, and you should alert your administrator
to set the UseGlobalTransaction flag in the mediation definition.
This flag defaults to a value of False.
- Hints that apply specifically to message format:
- It is good practice to check that your message conforms to the
expected format after your mediation function has operated on it.
You should use the isWellFormed method in the SIMessage interface
to check that all the values of the message properties can be serialized,
and that the data graph of the message conforms to the format of the
message.
- Depending on how you want to process the message, you can specify
a format that meets your needs rather than accept the natural format.
For example, if you want to handle a SOAP message as a byte string,
use the getNewDataGraph method in the SIMessage interface and specify
a format of JMS/bytes. getNewDataGraph returns a
new SDO data graph containing a copy of the SIMessage payload content
in the tree representation specified by the format field, in this
example as a byte string.
- It is good practice to check the message format in the mediation
code because a mediation is unlikely to successfully process a message
with an unexpected format. Use getFormat method on the SIMessage interface.
- The version of SDO supported by mediations is Version 1 only.
- Due to a restriction in the SDO user interface to the message,
message access methods do not have a ‘throws' clause. As a result,
an exception thrown by an access method because of a parsing error
is an unchecked exception. Your mediation can catch a parsing exception
by checking for the exception class SIMessageParseException in the com.ibm.websphere.sib.exception package.
Use code similar to the following example:
try {
// Function involving SDO message access
} catch (SIMessageParseException e) {
// Look at the real cause of the runtime exception, and act on it.
// It is likely to indicate a parse failure...
Throwable cause = e.getCause();
}
Note: If a mediation does not catch the
SIMessageParseException, the original version of the message is sent
to the exception destination.
- When deploying your mediation, give the handler and the handler
list memorable and descriptive names.
- Where you deploy a single mediation against a single destination,
use exactly the same name for your mediation handler, the mediation
handler list and the mediation object in the administrative console.
- For performance reasons, specify selector rules so that the mediation
mediates required subsets only of the messages passing through a destination.