Integrating WebService with Attachments in IBM Integration Designer

First we will look at different types of handling WebServices with Attachments and later, we will let you know to work with preferred way of handling them in IBM Integration Designer or WebSphere Integration Developer.

Types of attachments

There are four types of attachments: 

1. MTOM, 
2. referenced, 
3. swaRef type and 
4. unreferenced.

MTOM attachments 

• use the SOAP Message Transmission Optimization Mechanism (MTOM) (http://www.w3.org/TR/soap12-mtom/) specified encoding. 
• enabled through a configuration option in the import and export bindings as described in Enabling MTOM support in JAX-WS bindings 
• should be used to encode attachments for new applications. 
• MTOM optimization is only available for the xs:base64Binary data type.

Referenced attachments 

• referenced from the SOAP body; i.e the attachment is defined in the WSDL portType schema for the input or output message for the operation, 
• the reference appears in the SOAP body as an element that references the attachment using the attachment's content-Id. 
• To support SOAP messages with referenced attachments for exports, 
• the interface operations must use the document literal non-wrapped binding style or the RPC literal binding style 
• the input or output in the operation containing the reference must be binary

swaRef attachments

• A SOAP with attachment (swaRef) type attachment uses the Web Services Interoperability Organization (WS-I) Attachments Profile. 
• To pass an attachment as a swaRef type using the WS-I Attachments Profile, follow these steps:
• Add the WS-I attachment profile to your module. Open Dependencies in the Business Integration view and in the Predefined Resources section select WS-I attachment profile 1.0 swaRef schema file. Save your work.
• To add an attachment in a business object, create a business object and for the type select swaRef, which will be available since you added the schema previously.
• To add an attachment as a type for an input or output to an operation, create the operation in the interface. 
• Add an input or output to the operation. 
• If using the business object created previously then select the business object as the type to your input or output. 
• If you are not using the business object created earlier, add another input or output and select swaRef as the type.
• Generate the binding, deploy the your application and run it.

Unreferenced attachments 

• do not have a reference from the SOAP body to the attachment.
• not modeled in the WSDL portType of messages and do not appear in the business object representation. 
• can only be accessed through the Service Message Object (SMO). 
• each attachment appears as a separate element in the attachments list of the SMO

Bindings and protocols that can be used with attachments

Only the Java API for XML Web Services (JAX-WS) based binding supports attachments in WID version 6.2.0.1 or higher. 
Only the SOAP 1.2/HTTP or SOAP1.1/HTTP transport protocols can be used with attachments.

Working with MTOM Attachments in Integration Designer

Of all different ways to handle the Web Services with Attachments, MTOM approach is preferred way. This mechanism improves the transmission efficiency of large binary attachments in SOAP messages.

Enabling MTOM support in JAX-WS bindings:

• SOAP messages that use the MTOM specification can be sent and received by enabling support in IBM Integration Developer using JAX-WS import and export binding properties.
• On the Properties for the export or import, click the Binding tab and select the MTOM check box. This will enable the optimization of the transmission of binary data in the SOAP attachment
• Control the size of attachment to be sent using MTOM with Threshold field 
• is optional, integer value 
• indicates the minimum size of binary data to be sent using MTOM. 
• attachment size >= threshold, will be sent using MTOM
• attachment size < threshold, will be inlined in XML document
• 0 indicates all docs will be sent using MTOM

MTOM will not work in following scenarios:

• when the business object parsing mode is set to eager parsing (support is limited to a JAX-WS web service using business object lazy parsing mode).
• when using a JAX-WS handler (support is limited to a JAX-WS web service which does not use any JAX-WS handlers). The JAX-WS handlers specified on the web service should be removed.
• when using a service gateway mediation module, the Data Handler primitive cannot be used with MTOM messages. If direct access to the MTOM attachment data is required within the module, then a non-service gateway module must be used.
• when MTOM is enabled on a JAX-WS export binding, all responses will be sent using MTOM. If some clients do not support MTOM, use two JAX-WS exports - one with MTOM enabled and one with it disabled and ensure client applications use the correct endpoint address.
• when using the JAX-RPC binding for SOAP/HTTP or SOAP/JMS.

Tracing and Logging Components in WebSphere ESB

Compare the Logging vs Tracing

Tracing components are usually used for short term and temporary debugging purposes with a limited amount of data processed.
Logging components are for long-term data collection and storage. Their design is more performance-oriented for production use.

Tracing Components:

Given below are different tracing component descriptions and when to use each of them.

1. Cross component tracing (XCT): XCT lets you track messages through the SCA modules and components
• completely enable or disable it at runtime without the involvement of the development environment. 
• To enable, use the toolbar on the Server Logs view, or in the administration console under Troubleshooting > Cross-Component Trace State 
• makes it applicable for test or production environments
2. Integrated Test Client: Use this feature to test components or modules and view the data flow through mediation primitives.You can use it in two ways:
• Test component/export/import: This invokes an operation using a message entered in the GUI editor.
• Attach mode: This is the trace execution of requests not initiated by the ITC.
• Useful  when a mediation is driven by an external client, such as SOAPUI, or through messaging, such as WebSphere MQ messages being processed using a MQ/JMS Export
• Advantages:
• tests (including input messages) can be stored and re-used
• enter input as XML data (or from file) or graphically using BOs
3. Trace primitive: Use this primitive to trace messages to be logged to the server logs or to a file.
• used for debugging mediation flows
• trace messages contain SMO and other info
• not typically expected to be used in a production system because the MessageLogger or EventEmitter primitives are more suitable.
• following properties are configurable:
• Enabled: Similar to other primitives, it enables or disables the primitive's functionality. It is a promotable property.
• Destination: This specifies the location where the trace statement should be added, either Local Server Log (SystemOut.log), User Trace (UserTrace.log), or File (User-defined).
• File path: This specifies the location of the trace file when the destination field is specified as File.
• Message: This defines the message format that should be traced: {0} = time stamp, {1} = Message ID, {2} = Mediation name, {3} = Module name, {4} = Message defined by the root property, {5} = Version of the SMO. You can include additional explanatory text among the placeholders.
• Root path: This is the XPath expression that identifies what section of the SMO should be serialized into the message.

Logging Components:

Given below are different logging component available in WebSphere ESB and when to use each of them.

1. Message logger primitive: 
• Used to store messages to a relational database
• can write to other storage mediums, such as flat files, through the use of the custom logging facility
• logged messages can be used for data mining or auditing purposes later
• following properties are configurable: 
• Enabled: This is similar to other primitives. It enables or disables the primitive's functionality. It is a promotable property.
• Root: This is the XPath expression that identifies what section of the SMO is serialized into the message.
• Transaction mode: "Same" causes the message to log under the current transaction. "New" causes the message to log under its own transaction.
• Using the "New" transaction mode ensures that a successful message log to a database is always committed. That is, in "Same" mode, a message logged is not committed if the enclosing transaction is rolled-back. 
• An example of the transaction not being committed is if the Fail mediation primitive is used, which triggers a ServiceRuntimeException.
• Logging type: This specifies the location where the trace statement is added, either to a database by default, or use the user-defined handler described below.
• Data source name: This specifies the preconfigured database, using the JNDI reference, when the logging type field is specified as “Database”.
• Handler: This directs output somewhere other than the database, specifies a class that extends java.util.logging.Handler.
• Formatter: This specifies the data formatter class, implementing java.util.logging.Formatter.
• Filter: This specifies the data filtering handler class, implementing java.util.logging.Filter.
• Literal: This defines the message format that is traced: {0} = time stamp, {1} = Message ID, {2} = Mediation name, {3} = Module name, {4} = Message defined by the root property, {5} = Version of the SMO. You can also include additional explanatory text.
• Level: This specifies the trace level that is used to log the message. This is part of the log record passed to the handler.
• To implement your own handler:
• Extend java.util.logging.Handler and make your class available at runtime, for example, by including it directly in your project, or perhaps as a Jar in a library.
• In your implementation, override publish(LogRecord) and use the getFilter() and getFormatter() methods to access the other classes specified.
• Use getLevel() on the LogRecord argument to access the Level property from the mediation primitive.
• If logging to a file, then use buffering, such as a new BufferedWriter(new FileWriter).
2. Event Emitter primitive
• defines the application specific event data that is placed into the extendedDataElements section of the common base event
• when to use an event emitter
• Think of an event emitter as a notification mechanism that is used to indicate an unusual event, such as a significant failure within a flow, or an unusual path in the flow
• when not to use an event emitter
• Avoid placing an event emitter in the normal run path of a flow because this affects performance by causing a large number of events to be generated.
3. Custom mediation primitive
• Can use the Standard Visual snippet or Java snippet
• Below are some of the utility visual snippet functions that can be used for logging.
• print to log: This prints any text to the SystemOut log.
• print BO to log: This prints a Business Object or Service Message Object to the SystemOut log.
• print to logger: This prints text to the java.util.logging logger.
• BO print to logger: This prints a Business Object or Service Message Object to the java.util.logging logger.
• to text: This prints the toString() of a Java Object to the log.
• use custom snippet only if u have functionality that cannot be fulfilled by other primities

Performance Considerations

1. Outputting to log files can drastically reduce the execution speed and becomes a performance bottleneck
2. If you use trace to log files for testing, remove it completely for performance test or production, or devise a mechanism to enable or disable. 
3. The trace mediation primitive has a promotable property called “Enabled”. You can use this to have a trace property available for the administrator in the Integrated Solutions Console (under Enterprise Applications > SCA Modules > <moduleName> > Properties). 
4. The cost of leaving a disabled primitive in the mediation flow is relatively insignificant.