Building configurable artifacts (data <a href="http://setgetweb.com/p/BPMv8/v8r0m1/topic/com.ibm.wbpm.main.doc/topics/esbprog_bindings_ws3.html">bindings</a>, data handlers, and function selectors)

IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Services and service-related functions > Access external services with adapters > Configure and using adapters > IBM WebSphere Adapters > Adapter Toolkit > Implementing code from the IBM WebSphere Adapter Toolkit > Enterprise Metadata Discovery interfaces and implementation for technology adapters
Building configurable artifacts (data bindings, data handlers, and function selectors)

Building services using Enterprise Metadata Discovery involves building configurable artifacts that include data bindings, data handlers, and function selectors.

Implementing a data handler

To implement a data handler, implement the common.connector.runtime.DataHandler interface.
This interface contains two methods as follows:

Object transform(Object input, Class targetClass, Object options)
void transformInto(Object input, Object target, Object options)

The transform method takes an InputStream and produces a data object from it or takes a data object and produces an InputStream (depending on the processing mode). The target class indicates the processing to be performed by the data handler. The options parameter is a map that can include an encoding parameter. When implementing a data handler, code it to handle both byte array and string formats, if possible.
Existing WebSphere adapters, as of versions 6.2x, 7.0 and 7.5.x use InputStream for accessing raw data and data object for the transformed version exclusively.
Implement the TransformInto method in a data handler to transform a data object by writing to an output stream, so the input would be a data object, and the target would be an output stream.
A data handler should only transform from the raw payload to a data object and vice versa; it should not put the data in a record, or an envelope or other adapter-specific format, as this is the processing responsibility of a data binding.

Implementing a function selector

When provided with data and metadata from an adapter, the function selector generates the native function name. A function selector implements the interface commonj.connector.runtime.FunctionSelector. This interface contains the method String generateEISFunctionName(Object[] args);.
The argument array you get depends on which listener interface you are using. If you are using InboundListener (passing data only), the first object in the array is the record. If you are using ExtendedMessageListener (passing data and metadata), the first object in the array is an InboundNativeDataRecord that contains an InboundInteraction spec (for metadata) and the record (for data).
For services using adapters to exchange data with a local file system (like flat files) and services using adapters to access files on an FTP server, the InboundInteractionSpec contains the file name and path to the files being processed. A custom function selector can use the information in the InboundInteractionSpec to generate a native function.
For a custom adapter, you can create either a smart function selector that uses the data or metadata to perform function selection, with or without configuration; or you can implement a simple function selector that always returns a static function name. Implementing a simple function selector restricts your inbound service to a single function. This, in turn, restricts the service to dealing with a single data type; unless anyType is used in the WSDL, which is discouraged because a WSDL that contains an anyType schema is difficult to use in IBM BPM or WebSphere ESB (due to the fact that it does not indicate the actual type emitted).

Implementing a data binding

A data binding implements the interface commonj.connector.runtime.RecordHolderDataBinding. This interface contains four methods as follows:

Record getRecord();
void setRecord(Record record);
DataObject getDataObject();
void setDataObject(DataObject object);
These methods perform the mediation between the record that the adapter needs (for example an InputStreamRecord), and the data object specified in the service (WSDL).
The data binding can call a data handler to perform low-level transformation on an input stream. The adapter foundation classes provide a base class, named BaseDataBinding that adapters can extend to handle the low-level details of calling a data handler. The BaseDataBinding data handler has three methods as follows:

InputStream transformToInputStream(DataObject object);
DataObject transformToDataObject(InputStream stream, QName expectedType);
void setChildDataHandler(Qname bindingConfiguration);

To use these methods, call setChildDataHandler first with a data handler configuration, then call one of the transform methods. The expectedType parameter on transformToDataObject should match the type of the DataObject you want the transformation to produce. You can derive this from the expected type that the data binding is passed in the BindingContext interface described in the Binding context and configuration.

Binding context and configuration

Data handlers, data bindings and function selectors can be context-enabled and may be configurable.
BindingContext is a mix-in interface that provides access to contextual information, such as the configuration of this binding, the expected type for data handlers and data bindings and the type of service being used.
The BindingContext interface has several constants and one method as follows:

void setBindingContext(Map context);
To access the binding configuration, do context.get(BindingContext.BINDING_CONFIGURATION)
To access the expected type, do context.get (BindingContext.EXPECTED_TYPE)

Function selectors, data handlers, and data bindings are all configurable. This configuration can be quite rich, providing single and multi-valued properties, drop-downs, and user-editable tables and trees.
Every configurable artifact needs to have a Properties bean. The class name for this bean must follow the naming convention [Artifact]Properties, where [Artifact] is the class name of the function selector, data binding, or data handler being configured.
The properties bean contains all the artifact's properties as JavaBeans properties. Getters and setters must be provided for every attribute. Arrays are allowed for complex properties.
To enable the type of configuration that provides single and multi-valued properties, drop-downs, and user-editable tables and trees, you need a Configuration class and an EditableType class; each one using the same naming convention as the Properties class: [Artifact]Configuration and [Artifact]EditableType. The Configuration class must implement the interface commonj.connector.metadata.BindingConfigurationEdit, which has one method of note, which is public EditableType getEditableType();.
The method public EditableType getEditableType(); return the EditableType implementation for this artifact. The EditableType class implements the commonj.connector.metadata.discovery.EditableType interface, which contains the following methods:

PropertyGroup createProperties()
void synchronizeFromBeanToPropertyGroup(Object bean, PropertyGroup pg)
void synchronizeFromPropertyGroupToBean(PropertyGroup pg, Object bean)

The createProperties method creates an enterprise metadata discovery (EMD) property group that can contain several properties, or even nested property groups.
The synchronization methods provide the capability to keep the property group synchronized with the property bean. To specify a data handler property in a data binding, use a BindingTypeBeanProperty in the Property bean and a WBIBindingProperty in the property group.

Enterprise Metadata Discovery interfaces and implementation for technology adapters