Index Changes

Difference between version and version     

Back to Encoders, or Encoders Info


At line 1 removed 20 lines.
!!!Encoders
* [Installation Guide|EncoderInstallation]
* Encoder Providers (Implemented)
** [Custom Encoder|CustomDefined]
** [HL7 Encoder|HL7]
** [Cobol Copybook Encoder|CobolCopybooks]
* Encoder Providers (Planned)
** IDOC Encoder
** SEF Encoder
** MFS for IMS Encoder
** Swift Encoder(?)
** SAG (LDA, PDA) for ADABAS Natural Encoder
* [Encoder Provider Registration|EncoderRegistration]
* [Implement Your Own Encoder Provider|CreateOwnEncoder]
* [Tips, Tricks and Known Issues|EncoderTricksAndTips]
* [Encoder Next Step (document)|Jbicomps/EncoderNextStep.odt]
* [Encoder Road Map (document)|Jbicomps/EncoderRoadMap.odp]
* [Encoder vs. OTD comparison (document)|Jbicomps/EncoderVsOtd.odp]
* [Encoder planning for mid-term and long-term (ods document)|Jbicomps/Encoder_plan_detail.ods]
* [Encoder planning - details (odt document)|Jbicomps/Encoder_plan.odt]
At line 2 added 1 line.
[top|#top]
At line 23 changed 5 lines.
!!! Demo
[{Image src='customencoderdemo.gif' width='254' height='183' align='top' }]
* [Custom Encoder Demo|http://wiki.open-esb.java.net/attach/CustomDefined/EncoderDemoSwf2.html] - an End-to-end scenario of Custom Encoder (File-to-File).
* [TestCustomEncoderProjects2_and_Data.zip|http://wiki.open-esb.java.net/attach/CustomDefined/TestCustomEncoderProjects2_and_Data.zip] - NetBeans Projects and input data used in the demo.
!!! Use COBOL Copybooks Encoder (in a File-to-File scenario)
At line 29 removed 1 line.
!!! Introduction: Encoder = The Bridge Enables Talk between Legacy and Modern
At line 7 added 1 line.
[{TableOfContents }]
At line 32 changed 17 lines.
!! Table of Content
* [What Is Encoder?|Encoders#WhatIsEncoder]
* [What Defines an Encoder?|Encoders#WhatDefinesAnEncoder]
* [How Is Encoder Feature Supported in Open-ESB?|Encoders#HowIsEncoderFeatureSupportedInOpenESB]
* [Loosely Coupled Service Provider Architecture|Encoders#LooselyCoupledServiceProviderArchitecture]
* [Encoder Runtime|Encoders#EncoderRuntime]
* [Encoder Editor|Encoders#EncoderEditor]
* [XSD Editor Plug-in|Encoders#XSDEditorPlugIn]
* [Apply Encoding Rules|Encoders#ApplyEncodingRules]
* [Validator|Encoders#Validator]
* [Use Encoder in JBI Binding Component|Encoders#UseEncoderInJBIBindingComponent]
* [Use Encoder in Java SE or Java EE Projects|Encoders#UseEncoderInJavaSEOrJavaEEProjects]
* [Encoder Providers That Have Been Implemented|Encoders#EncoderProvidersThatHaveBeenImplemented]
* [Installation|Encoders#Installation]
* [Write Your Own Encoder Provider|Encoders#WriteYourOwnEncoderProvider]
* [Tips, Tricks and Known Issues|Encoders#TipsTricksAndKnownIssues]
* [Contact|Encoders#Contact]
!! 1. Prerequisites
* Install a latest Glassfish ESB v2.1 build or open-esb build which can be downloaded from [here|https://open-esb.dev.java.net/Downloads.html].
* You will need to manually install the Cobol Copybook encoder library and related design-time modules by following these steps:
** You can manually build the .nbm files from NetBean's mercurial repository (http://hg.netbeans.org/soa-dev65), or simply download a snapshot copy following below links:
|| source module || nbm file to be built
| c.s.encoder.coco | [ com-sun-encoder-coco.nbm |com-sun-encoder-coco.nbm ]
| encoder.coco.ui | [ org-netbeans-modules-encoder-coco-ui.nbm | org-netbeans-modules-encoder-coco-ui.nbm ]
| it.imolinfo.jbi4cics.netbeansplugin.libraries | [ it-imolinfo-jbi4cics-netbeansplugin-libraries.nbm | it-imolinfo-jbi4cics-netbeansplugin-libraries.nbm ]
| it.imolinfo.jbi4cics.netbeansplugin.cpy2wsdlwizard | [ it-imolinfo-jbi4cics-netbeansplugin-cpy2wsdlwizard.nbm | it-imolinfo-jbi4cics-netbeansplugin-cpy2wsdlwizard.nbm ]
** Go to NetBeans Tools -> Plugins, and click on "Add Plugins..." in the "Downloaded" tab to add these nbm files. Follow the instructions to install them.
[{Image src='install2_NB_pluggins.png' align='top' width='850' height='558' }]
** You can verify the Cobol Copybook encoder related NetBeans modules installed, such as "CPY2WSDL Wizard" and "Encoder Editor - COCO".
[{Image src='install1_NB_pluggins.png' align='top' width='849' height='775' }]
** For the encoder shared library jar file, you can manually build it from open-jbi-components cvs source code (see [open-jbi-components|https://open-jbi-components.dev.java.net/public/cvs.html]), or simply download a snapshot copy following below link:
|| source directory || shared library jar
| open-jbi-components\ojc-core\encodersl | [ encoderlib.jar | encoderlib.jar ]
** You will then need to reinstall the "sun-encoder-library" under the JBI's "Shared Libaries" by using this encoderlib.jar.
*** First uninstall the older version (you may wish to make a copy of it by going to <glassfish_dir>\addons\jbi-components\encoderlib.jar).
[{Image src='install3_uninstall_encoder_lib.png' align='top' width='331' height='412' }]
*** Then install the encoderlib.jar
[{Image src='install4_reinstall_encoder_lib.png' align='top' width='263' height='369' }]
At line 50 changed 9 lines.
!! 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
[{Image src='EncoderRole.png' width='919' height='390' align='top' }]
* 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|UseCOCoEncoder#top]
At line 60 changed 1 line.
[Back to Top|Encoders#TableOfContent]
!! 2. Create a BPEL module new project
* Choose "New Project", and select "BPEL Module" under the "SOA" Catogory.
[{Image src='prj1_new_project_BPEL_Module.png' align='top' width='737' height='505' }]
* Give a project name.
[{Image src='prj2_new_BPEL_Module.png' align='top' width='737' height='505' }]
* When finish, a new project of BPEL module is created with skeleton BPEL code.
[{Image src='prj3_new_BPEL_Module.png' align='top' width='763' height='594' }]
At line 62 changed 6 lines.
!! What Defines an Encoder?
An encoder consists of three pieces of information
# ''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.
# ''Detail Encoding Rules''. Detail encoding rules are specific to one encoder, such as the delimiters at certain places, field lengths etc.
# ''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|UseCOCoEncoder#top]
At line 47 added 5 lines.
!! 3. Create COBOL copybook document using wizard
You can create a COBOL copybook document using following two different wizards:
# The New "Empty Copybook File" wizard to create a blank document, and fill in the content manually by yourself.
# The "External COBOL Copybook document(s)" wizard to retrieve existing copybook document(s).
Note that currently we only support COBOL Copybook document with ".cpy" file extension. If you have an external Copybook document in your file system, you will need to rename it to ".cpy" extension in order for the browser to locate it by default.
At line 70 changed 1 line.
[Back to Top|Encoders#TableOfContent]
[Back to Top|UseCOCoEncoder#toc]
At line 72 changed 11 lines.
!! 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
[{Image src='ModuleComposition.png' align='top' }]
* 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
! 3.1. Use the New "Empty Copybook File" wizard.
* Right click on "Process Files" folder, and select New -> "Empty Copybook File".
[{Image src='newCobol0.png' align='top' width='546' height='313' }]
Note: If you don't see the "Empty Copybook File" selection, you can go to NetBeans main menu File -> New File.
[{Image src='newCobol1.png' align='top' width='360' height='178' }]
Then under "SOA" Category, you should be able to see them.
[{Image src='newCobol2.png' align='top' width='737' height='505' }]
* Specify the file name.
[{Image src='newCobol3.png' align='top' width='737' height='505' }]
* When finish, a blank Copybook document is created and opened.
[{Image src='newCobol4_copy.png' align='top' width='574' height='373' }]
You can right click on the editor to copy and paste from an existing content.
[{Image src='newCobol5_pasted.png' align='top' width='538' height='264' }]
At line 84 changed 1 line.
[Back to Top|Encoders#TableOfContent]
[Back to Top|UseCOCoEncoder#top]
At line 86 changed 2 lines.
!! 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.
! 3.2. Use the "External COBOL Copybook document(s)" wizard.
* Right click on "Process Files" folder, and select New -> "External COBOL Copybook document(s)".
[{Image src='External1.png' align='top' width='551' height='310' }]
Note: If you don't see the "External COBOL Copybook document(s)" selection, you can go to NetBeans main menu File -> New File.
[{Image src='newCobol1.png' align='top' width='360' height='178' }]
Then under "SOA" Category, you should be able to see them.
[{Image src='External2.png' align='top' width='737' height='505' }]
* In the "New File" dialog, specify the Copybook document source from an URL, or from your local file system.
[{Image src='External3.png' align='top' width='744' height='450' }]
* If you choose to retrieve the Copybook document source from your local file system, click on "Browse" to locate the file.
[{Image src='External4.png' align='top' width='510' height='281' }]
The selected local file is shown as below:
[{Image src='External5.png' align='top' width='744' height='450' }]
* When finish, a copy of the Copybook document is retrieved and put under the project folder.
[{Image src='External6.png' align='top' width='838' height='342' }]
At line 91 added 3 lines.
[Back to Top|UseCOCoEncoder#top]
At line 90 changed 1 line.
[Back to Top|Encoders#TableOfContent]
!! 4. Generate COBOL Copybook Encoder definition XSD.
You will need to use the "Generate COBOL Copybook Encoder definition XSD" wizard to create annotated XSD with COCo Encoder specific information.
* Right click on COBOL copybook document, and select "Generate Encoder definition XSD" from the popup.
[{Image src='xsd1.png' align='top' width='836' height='478' }]
* In the "Generate Encoder definition XSD" dialog, specify the Code Pages, Codings, and select appropriate options.
You may also see the tooltips to understand what each option means.
[{Image src='xsd2_wizard.png' align='top' width='685' height='499' }]
* When finish, the Encoder definition XSD is generated and opened.
[{Image src='xsd3.png' align='top' width='905' height='552' }]
* The generated XSD may also be viewed using the "Schema" view:
[{Image src='xsd4_schema_view.png' align='top' width='380' height='420' }]
* The generated XSD may also be viewed using the "Design" view:
[{Image src='xsd5_design_view.png' align='top' width='374' height='330' }]
At line 92 changed 14 lines.
!! 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|UseCOCoEncoder#top]
At line 107 changed 1 line.
[Back to Top|Encoders#TableOfContent]
!! 5. Use Encoder Tester to test generated Copybook Encoder definition XSD.
You can use the "Encoder Tester" to test the generated XSD on actual Copybook data. This allows you to test the runtime message decoding/parsing and encoding/generation at design-time.
At line 109 changed 11 lines.
!! 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
! 5.1. Decoding test
* Right click on the generated Encoder Defintion XSD, and select Encoding -> Test.
[{Image src='tester1.png' align='top' width='693' height='697' }]
* In the "Test Encoding" dialog, the root element in the Meta section is already filled. You need to specify "Decode" under the Input section.
[{Image src='tester2.png' align='top' width='615' height='550' }]
* Specify the input COBOL Copybook data file to test. You may use the default output file name or modify it at your will. You may also specify appropriate "Verbose Level" under Debug section for information on step-by-step message decoding/encoding.
[{Image src='tester3.png' align='top' width='614' height='551' }]
The input data in this example is shown:
[{Image src='tester3a.png' align='top' width='465' height='156' }]
* When finish, the parsed XML is generated and opened. The information on step-by-step message decoding may also be displayed on the bottom-right pane.
[{Image src='tester4.png' align='top' width='1109' height='850' }]
You may wish to format the XML by selecting "Source" -> "Format".
[{Image src='tester5_format_xml.png' align='top' width='464' height='163' }]
And as such, you have a better view of the parsed XML:
[{Image src='tester6_formatted.png' align='top' width='748' height='454' }]
At line 121 changed 1 line.
[Back to Top|Encoders#TableOfContent]
! 5.2. Encoding test
* You may also wish to test the decoding of COBOL Copybook encoder by selecting "Encode" in the "Test Encoding" dialog. Specify the input XML, output file name, and other appropriate options including Debug Level.
[{Image src='tester7_encode.png' align='top' width='616' height='549' }]
* When finish, the output COBOL Copybook native data is generated. The information on step-by-step message encoding may also be displayed on the bottom-right pane.
[{Image src='tester8.png' align='top' width='1109' height='850' }]
At line 123 changed 2 lines.
!! 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.
[Back to Top|UseCOCoEncoder#top]
At line 126 changed 1 line.
XSD editor also passes in a context to the plug-in to facilitate mutating the XSD model.
!! 6. Create WSDL to use COCo encoder and File BC.
* Right click on the "Process Files" folder, and select New -> WSDL Document...
[{Image src='wsdl1.png' align='top' width='560' height='301' }]
* Specify File Name, select "Concrete WSDL document", and choose "File" binding with the "Poll and Write Back Reply" type (i.e. Request-Reply pattern).
[{Image src='wsdl2.png' align='top' width='737' height='505' }]
* In the "Request Configuration", specify inbound file name and polling diretory. Under the "Payload Processing" section, select "encoded data" as Message Type.[{Image src='wsdl3.png' align='top' width='737' height='665' }]
* Then click on "..." to select the XSD Element/Type. In our example, it's "DFHCOMMAREA" root element.
[{Image src='wsdl4_element_type.png' align='top' width='426' height='496' }]
* For the "Encoded Type", manually type in "cocoencoder-1.0" (no quotes).
[{Image src='wsdl5_encoded_type.png' align='top' width='737' height='665' }]
* In the "Response Configuration", specify outbound file name. Under the "Payload Processing" section, select "encoded data" as Message Type, select the XSD Element/Type same as in above step, and manually type in "cocoencoder-1.0" (no quotes) as "Encoded Type".
[{Image src='wsdl6_output.png' align='top' width='737' height='665' }]
* When finish, the WSDL is created and opened for review.
[{Image src='wsdl7.png' align='top' width='632' height='426' }]
At line 157 added 3 lines.
[Back to Top|UseCOCoEncoder#top]
At line 129 changed 1 line.
[Back to Top|Encoders#TableOfContent]
!! 7. Create BPEL for Business Logics.
* Open the skeleton BPEL that was generated earlier.
[{Image src='bp1.png' align='top' width='527' height='454' }]
* Drag and drop the WSDL (COCo.wsdl) into the BPEL editor canvas.
[{Image src='bp2_Dnd_wsdl.png' align='top' width='707' height='527' }]
* Drag and drop the WSDL (COCo.wsdl) into the BPEL editor canvas.
[{Image src='bp2_Dnd_wsdl.png' align='top' width='707' height='527' }]
* Drag and drop appropriate nodes (Receive, Reply, Assign) from the Palette into the BPEL editor canvas.
[{Image src='bp3.png' align='top' width='672' height='451' }]
* Edit the property of "Receive" service node by double clicking it.
[{Image src='bp4_receive_node.png' align='top' width='497' height='292' }]
* In the the property editor for the "Receive" node, create Input Variable.
[{Image src='bp5_receive_node_create_input.png' align='top' width='340' height='182' }]
* Similarly, edit the property of "Reply" service node by double clicking it, and create Output Variable.
[{Image src='bp6_reply_node.png' align='top' width='521' height='379' }]
* Double click the "Assign" node to launch the mapper.
[{Image src='bp7_assign_mapper.png' align='top' width='710' height='395' }]
* Incorporate the business logics in the mapper. In our example, we change the CA-OUT-NAME to "Jones Doe" and prepend the CA-OUT-CITY with "City Of ".
[{Image src='bp8_mapper.png' align='top' width='828' height='380' }]
At line 131 changed 9 lines.
!! 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:
[{Image src='ScreenshotApplyEncoding.PNG' align='top' }]
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:
[{Image src='ScreenshotApplyEncoding2.PNG' align='top' }]
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:
[{Image src='ScreenshotEncodingNode.PNG' align='top' }]
Please refer to the specific encoder wiki pages (for example, [custom encoder wiki|CustomDefined]) 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|UseCOCoEncoder#top]
At line 185 added 11 lines.
!! 8. Create Composite Application for the BPEL module.
* Create a new Project by selecting "Composite Application" as project type.
[{Image src='ca1.png' align='top' width='737' height='505' }]
* Specify the project name (in our example, "CobolCompApp").
[{Image src='ca2.png' align='top' width='737' height='505' }]
* Drag and drop the above BPEL module project into the CASA editor (CobolCompApp.casa).
[{Image src='ca3_dnd_JBI_module.png' align='top' width='870' height='505' }]
* Build the Composite Application project.
[{Image src='ca4_build_CA.png' align='top' width='809' height='396' }]
* After the successful build, the CASA editor should be updated automatically with the connections.
[{Image src='ca5.png' align='top' width='427' height='217' }]
At line 197 added 3 lines.
[Back to Top|UseCOCoEncoder#top]
At line 143 changed 1 line.
[Back to Top|Encoders#TableOfContent]
!! 9. Deploy the Composite Application (CA).
* Deploy the CA by selecting "Deploy" from the popup menu.
[{Image src='deploy1.png' align='top' width='712' height='303' }]
* You should see "Build Successfully" in the output panel.
[{Image src='deploy2.png' align='top' width='730' height='288' }]
* You should also see the CA deployed under Servers -> JBI -> Service Assemblies in the "Services" tab.
[{Image src='deploy3_service_tab.png' align='top' width='322' height='624' }]
At line 145 changed 3 lines.
!! Validator
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:
[{Image src='ScreenshotValidation.PNG' align='top' }]
[Back to Top|UseCOCoEncoder#top]
At line 149 changed 1 line.
Please note the encoding rule violations pointed out by the encoding rule validation plug-in.\\
!! 10. Run End-to-End (File-to-File) scenario with test data.
* Prepare a test COBOL copybook data and put it into the directory with input file name pattern specified in the WSDL. In our example, the input file name is inputCobol.dat.
[{Image src='run1_inputdata.png' align='top' width='842' height='224' }]
You can use a text editor to examine the input data before dropping it into the input directory.
{{{Key0001 John Doe Monrovia 99}}}
* If everything works correctly, you should see the expected output file generated in the directory. In our example, the output file generated is outputCobol.dat.
[{Image src='run2_outputdata.png' align='top' width='829' height='221' }]
{{{Key0001 Jones DoeCity of Monrovia 99}}}
At line 151 removed 31 lines.
\\
[Back to Top|Encoders#TableOfContent]
\\
!! Tester
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):
\\
[{Image src='ScreenshotEncoderTester.PNG' align='top' }]
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|Encoders#TableOfContent]
\\
!! 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:
[{Image src='ScreenshotUseEncoderInFileBC.PNG' align='top' }]
\\
\\
[Back to Top|Encoders#TableOfContent]
\\
!! 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:
[{Image src='ScreenshotAddLibrary.PNG' align='top' }]
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.
At line 183 changed 1 line.
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:
[Back to Top|UseCOCoEncoder#top]
At line 185 removed 26 lines.
{{{
//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("http://xml.netbeans.org/schema/newXMLSchema", "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.
At line 226 added 3 lines.
!! 11. Sample projects and test data.
* You can download the sample project used in this example [here|COCoEncoder_Projects.zip]
* You can also follow the links to download the [input data|inputCobol.dat], [output data]outputCobol.dat], the [Copybook file|DFHCOMMAREA.cpy].
At line 213 removed 31 lines.
[Back to Top|Encoders#TableOfContent]
\\
!! Encoder Providers That Have Been Implemented
* [Custom Defined|CustomDefined]
* [HL7|HL7]
* [COBOL Copybook|CobolCopybooks]
\\
[Back to Top|Encoders#TableOfContent]
\\
!! Installation
Please follow the steps outlined at the [Encoder Feature Installation Guide|EncoderInstallation] page to proceed with the encoder feature installation.
\\
[Back to Top|Encoders#TableOfContent]
\\
!! Write Your Own Encoder Provider
Please follow the steps outlined at the [Write Your Own Encoder Provider|CreateOwnEncoder] page to proceed with implementing your own encoder providers.
\\
[Back to Top|Encoders#TableOfContent]
\\
!! Tips, Tricks and Known Issues
Please read the [Tips, Tricks and Known Issues|EncoderTricksAndTips] 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|Encoders#TableOfContent]
\\
!! Contact
At line 231 added 2 lines.
[Back to Top|UseCOCoEncoder#top]
At line 246 changed 1 line.
Email: [soabi-encoders@sun.com|mailto:soabi-encoders@sun.com]
!! 12. Other links and resources
* [Introduction to Encoders|http://wiki.open-esb.java.net/Wiki.jsp?page=Introduction]
* [Introduction to COBOL Copybook Encoders|http://wiki.open-esb.java.net/Wiki.jsp?page=CobolCopybooks]
At line 248 changed 1 line.
[Back to Top|Encoders#TableOfContent]
|| 13. Any questions or feebacks?
\\
Please email: [soabi-encoders@sun.com|mailto:soabi-encoders@sun.com]

JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This page (revision-37) was last changed on 28-Sep-09 21:10 PM, -0700 by LixinTang