Coding tips for mediations programming

Programming hints to help you when we are writing mediation code.

• Take care to avoid looping in the Forward Routing Path. For example, if we 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 our 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 we 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. We 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 we want to process the message, we can specify a format that meets our needs rather than accept the natural format. For example, 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();
  }
  

  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 we deploy a single mediation against a single destination, use exactly the same name for our 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.

Including SOAP header schemas in the SDO repository