Index Changes
This is version 32. It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]



Introduction: Encoder = The Bridge Enables Talk between Legacy and Modern

Table of Content

What Is Encoder?

  • Encoder decodes non-XML coded message into XML message as well as encodes XML message into non-XML coded message (the name seems to reflect that it only does the encoding part, but actually it provides function for both encoding and decoding)
  • Although JBI does not limit messages posted to NMR to be in XML format, XML is the defacto standard for interoperability and a common message format allows for decoupled, pluggable capabilities to act on the message contents.
  • Most of the data coming from EDI partners is still non-XML coded
  • Conclusion: encoder is needed to do data conversion in both directions – inbound and outbound
  • Encoder's role is illustrated in the diagram below
  • Inbound - When an external non-XML coded message is received by a binding component, if in the WSDL the message type is configured as encoded, the binding component will call encoder API to decode the message into XML format and then send it to NMR
  • Outbound - When an XML message is received by a binding component from NMR, if in the WSDL the message type is configured as encoded, the binding component will call encoder API to encode the message into a non-XML coded message and then send it to the external partner

Back to Top

What Defines an Encoder?

An encoder consists of three pieces of information
  1. Encoding Style. A.k.a. encoding type or encoder type. An encoding style usually conveys a set of general encoding rules that is specific to one type of encoding (but generally applies to all encoders of that type). It is usually identified by a well-known name, such as HL7, SWIFT or X12 etc.
  2. Detail Encoding Rules. Detail encoding rules are specific to one encoder, such as the delimiters at certain places, field lengths etc.
  3. Abstract Message Structure, which defines the message's logical structure the encoder deals with
With these three pieces of information, an encoder's runtime behavior is determined.

Back to Top

How Is Encoder Feature Supported in Open-ESB?

Based on encoder's role and what defines an encoder, following components are needed to support this feature
  • A set of parsers and marshalers, each pair is used to deal with a specific encoding style
  • A set of editors/validators/wizards, each triple is used to create/edit/validate the message structure and the detail encoding rules of encoders of a specific encoder type
  • A tester that is used to test encoder's runtime behavior at design time
  • Glue components that wire everything together
Below is the module composition diagram for the encoder implementation
  • Shaded boxes inside the dark line indicate the scope of the encoder support
  • Bluish boxes indicate the modules that will be released in Kenai (tentative plan, may change)
  • Modules indicated in upper boxes have dependencies on modules indicated in lower boxes

Back to Top

Loosely Coupled Service Provider Architecture

From the diagram we can see that encoder implementation uses loosely coupled service provider architecture for both runtime library and design time tools. More encoder service providers and design time plug-ins can be employed when needs do arise.

Back to Top

Encoder Runtime

Encoder runtime is a set of modules that fulfil following tasks:
  • Let clients query a list of encoding styles that are supported in the current environment
  • Let clients lookup encoders using encoding styles
  • Decode/encode data (the real job)
Encoder runtime is used by both deployed composite applications and the design time tools (mainly the encoder tester). Encoder runtime consists of following modules:
  • The service provider interface (SPI) that defines the interaction between the encoder runtime framework and encoder service providers
  • Encoder runtime framework (mainly for looking up encoder service providers)
  • The encoder service providers (building blocks that do the real work)
  • The encoder API, which is used by binding components or other modules (potentially). All non-encoder related modules should only use encoder APIs to access the encoder feature, nothing else.
Encoder runtime is packaged in two ways:
  • For composite applications, it is packaged as a JBI shared library and the shared library identifier is “com.sun.encoder-1.0” (might be changed later)
  • For the design time environment, it is packaged as a set of NetBeans library wrapper modules. So far, the modules available are “Encoder Framework Wrapper”, “Custom Encoder Wrapper” and “HL7 Encoder Wrapper”

Back to Top

Encoder Editor

Encoder editors are needed at design time to edit encoder's abstract message structure and its detail encoding rules. In Open-ESB, NetBeans' XSD editor is used as the base of encoder editors. The reasons are:
  • XSD is the de facto data modeling language used in JBI
  • XSD editor is a good fit for modeling abstract message structures
  • Encoding rules are additional information in augment to abstract message structure
So the overall strategy for implementing encoder editors is:
  • Use NetBeans' XSD editor to edit abstract message structure
  • Apply encoding rules after the abstract message structure is created
  • Use XSD editor plug-ins to edit specific encoding rules
  • Store encoding rules inside XSD's Annotation/AppInfo schema component
  • Encoder runtime providers read metadata (both the abstract message structure and encoding rules) only from the XSD

Back to Top

XSD Editor Plug-in

XSD editor team recently added a service provider interface to allow plugging in GUI extensions to the editor. The interface is called “AppInfoProvider”, which allows an AppInfo service provider to display a custom node (with custom property sheet) over the AppInfo it recognizes.
XSD editor also passes in a context to the plug-in to facilitate mutating the XSD model.

Back to Top

Apply Encoding Rules

Before applying custom encoding rules, an XSD must be created using XSD editor to define the abstract structure of a message. Once the abstract message structure is defined, a special hint along with the default encoding rules can be applied to the XSD to activate custom encoding support on that XSD. This is done via the new XSD contextual menu added specifically for custom encoding support, as below:
User can choose one of the available encoding styles and apply it to the XSD. Some encoding styles may require the XSD to following certain constraints. Once an encoding style is applied, the contextual menu changes to:
The "Test" and "Remove Encoding" menu items are enabled while other encoding styles are disabled. Same encoding style can be re-applied and the effect will be assigning default encoding rules to newly created elements (the elements created after last time the encoding style was applied). Once the encoding style is applied, user can edit detail encoding rules at the node level via the special encoding node under the Element/Annotation node, as below:
Please refer to the specific encoder wiki pages (for example, custom encoder wiki) for the details on editing node level encoding rules since this editing support is encoding style specific. After finishing all encoding rules, user can validate the integrity of encoding rules by clicking the Validate button on XSD editor. User can also test the encoder's runtime behavior at design time using encoder tester.

Back to Top


Implementation of each encoding style should provide a validation plug-in to XSD's validation framework, which will be used to do encoding rule level validation in augment to normal XSD validation. This way, if an XSD has encoding rules applies and the validation button is clicked on XSD editor, the encoding rules will automatically be validated after XSD grammar and semantics are validated. The following screen shot shows an example of the validation result:

Please note the encoding rule violations pointed out by the encoding rule validation plug-in.

Back to Top


Encoder support in Open-ESB provides a generic (one for all encoding styles) tester for user to test encoder's runtime behavior at design time. This is required for easily verifying the abstract message structure and the encoding rules are as expected and the encoder runtime is working as expected.
Encoder Tester's GUI is very light because the design rational behind it is to keep it simple and hi-fidelity, meaning that it should reflect an encoder's runtime behavior as accurately as possible.
The encoder tester's screen looks like the following screenshot shows (launched from the XSD context menu):
Once the decode test is done, the result is placed in an XML file inside the current project. The xsi:schemaLocation attribute is usually populated by the encoder runtime. So, to verify the decode result, just click the validate button of the XML editor. There is no automatic way to verify the encode result.

Back to Top

Use Encoder in JBI Binding Component

It is very simple to use an encoder in binding components once the XSD that defines the encoder is ready. The steps are:
  • Import the XSD into a WSDL just like a normal XSD.
  • For the binding component's inbound or outbound message type, configure it as “encoded” and put in an encoding style. The encoding styles currently supported are “customencoder-1.0” and “hl7encoder-1.0”.
For example, the configuration screen for File BC that uses encoding is shown below:

Back to Top

Use Encoder in Java SE or Java EE Projects

Encoder can also be used in Java SE or Java EE projects. Encoder NetBeans modules now automatically register/unregister encoder Java SE libraries with NetBeans library manager when these modules are installed/enabled or disabled/uninstalled. These Java SE libraries, once registered in NetBeans by the relevant encoder modules, can be referenced in Java SE or Java EE projects to support use of encoders in these projects. For example, if all encoder NetBeans modules currently available have been installed and enabled, from an EJB module project's property page, one can click "Libraries" --> "Add Library...", and following screen will be shown:
One can select the encoder libraries that are needed to support the EJB module project. Encoder-Framework library is always needed for using any of the encoder types. Besides this library, depending on which encoder type(s) will be used, one can select one or more encoder provider libraries, such as the Encoder-Custom library or the Encoder-HL7 library or both.

After the necessary encoder libraries have been added to the J2SE or J2EE project, an encoder definition (an XSD file) should be created or imported into the source folder of the project. The encoder definition may be edited (using the relevant encoder editor) or tested (using the encoder tester) to be satisfactory. The encoder (defined by the encoder definition) then can be used in Java like following code snippet shows:

            //Get the encoder factory instance
            EncoderFactory factory = EncoderFactory.newInstance();

            //Get the encoder type instance using an encoding style
            EncoderType type = factory.makeType("customencoder-1.0");

            //Specify a top element
            QName topElem = new QName("", "root");

            //Construct the metadata instance
            MetaRef meta = factory.makeMeta(
                    this.getClass().getClassLoader().getResource("org/helloworld/newXmlSchema.xsd"), topElem);

            //Create the encoder instance
            Encoder coder = factory.newEncoder(type, meta);

            //Decode the data
            javax.xml.transform.Source source = coder.decodeFromString(input);

The encoder definition (the XSD file) usually is packaged with the Java class that uses it, so in the Java code the XSD file's location must be retrieved using the current class loader. The location might be a URL pointing to a resource in a jar file or may be a URL pointing to an XSD file in the local file system.

When the project is built, the encoder jar files specified in these libraries will be packaged into the target jar file. One caveat is to make sure the Class-Path attribute is populated in the target jar file's manifest file. EJB module project does not seem to do this during build. A bug has been filed for this. The workaround is to manually modify the manifest file under the project's Configuration Files folder before build.

This mechanism has been tested with the scenario of implementing a web service using an EJB module.

Back to Top

Encoder Providers That Have Been Implemented

Back to Top


Please follow the steps outlined at the Encoder Feature Installation Guide page to proceed with the encoder feature installation.
Back to Top

Write Your Own Encoder Provider

Please follow the steps outlined at the Write Your Own Encoder Provider page to proceed with implementing your own encoder providers.
Back to Top

Tips, Tricks and Known Issues

Please read the Tips, Tricks and Known Issues page to learn how better use the encoder feature in Open-ESB and avoid pitfalls.
Also See Use Encoders in POJO SE
Also See Use Encoders in Java SE
Also See Use Encoders in EJB
Back to Top


Back to Top

JSPWiki v2.4.100
« Home Index Changes Prefs
This particular version was published on 30-Apr-09 13:32 PM, -0700 by LixinTang