Smooks Dev Tools Reference Guide

- Smooks Configuration Editor - This chapter describes the following tabs of the Smooks Configur= ation Editor: - - - Process tab - Options tab - Sourc= e tab - -

- Process tab - The Process tab of the Smooks Configuration Editor helps to c= onfigure different types of transformations. - By default smooks configuration file is opened in this editor.I= f you have another default settings for editor opening - you should left click smooks configuration file and select:Open With->Smooks Configuration Editor. - The Process tab has two sections: - - Proce= ssing Task section - Selecte= d Task Details section - - You can see them on the picture below. -

- Two Sections of the Process tab. - - - - - - -

- Processing Task section - Using the popup menu in the Processing Task section you - can select which types of technologies(templating or mapping on= es) you will use for transofmation: - The descriptions of the popup menu options are in the fol= lowing table. - - Process Tab. Processing Task section. = - - - - - = - - - Option = - Description - Default - - - - - Add Task - Select one of the following tasks accord= ing to the necessary type of Source and Result types of the files: - - Input -this task is required and - appears automatically when Smooks c= onfig file is created. - You should just configure it proper= ly. - Java Mapping<= /emphasis> - Apply Templat= e - - - - = - = - - Delete - Click this option if you want to delete = some task from the section. - Note:you can't delete input task because it's r= equired. - - = - = - = - - Input Methods - Choose one of the following methods: - - System - Simple - Amharic(EZ+) - Cedilla - Cyrillic - Inuktitut - IPA - Multipress - SCIM Bridge Input Metho= d - SCIM Input Method - Thai-Lio - Tigrigna-Eritrean(EZ+)<= /para> - Tigrigna-Ethiopian(EZ+)= - Vietnamese - X input Method - - - System - = - - -

- Selected Task Details Section - The options of this section depends on the selected task in th= e Processing Task section. - Because there are 3 types of tasks there are 3 different sets of= its options in the Selected Task Details Section. - They will be described one by one. -

- Selected Task Details Section for Input Task. - On the picture below you can find an example of Select= ed Task Details Section view - if XML is selected as input type. - = -

- Selected Task Details Section for Input XML Task.= - - - - - - - As you can see on the picture above Input Configuratio= n section is empty for XML input file. - But this section has special configuration options for C= SV,EDI,JSON,Custom input files. - = - Here are the screens of these configuration options: - - CSV: -

- Selected Task Details Section for Input C= SV Task. - - - - - - - - EDI: -

- Selected Task Details Section for Input E= DI Task. - - - - - - - - JSON: -

- Selected Task Details Section for Input J= SON Task. - - - - - - - - Custom: -

- Selected Task Details Section for Input C= ustom Task. - - - - - - - - - All the input task configuration positions can be found i= n the table below: = - - Selected Task Details Section. Options for Input Task.</t= itle> = - <tgroup cols=3D"3"> - <colspec colnum=3D"1" align=3D"left" colwidth=3D"1*"/> - <colspec colnum=3D"2" align=3D"left" colwidth=3D"3*"/> - <colspec colnum=3D"3" align=3D"left" colwidth=3D"1*"/> = = - <thead> - <row> - <entry>Option</entry> = - <entry>Description</entry> - <entry>Default</entry> - </row> - </thead> - <tbody> - <row> - <entry>Input type</entry> - <entry>Select your type of input file. - If don't find your type in the list,you should u= se Custom type: - <itemizedlist> - <listitem><para>No Input</para></listitem> - <listitem><para>XML</para></listitem> - <listitem><para>Java</para></listitem> - <listitem><para>XSD/WSDL</para></listitem> - <listitem><para>CSV</para></listitem> - <listitem><para>EDI</para></listitem> - <listitem><para>JSON</para></listitem> - <listitem><para>Custom</para></listitem> - </itemizedlist> - </entry> - <entry>XML</entry> - </row> = - = - <row> - <entry>Input configuration - - </entry> - <entry> - <itemizedlist> - <listitem><para><emphasis>No Input</emphasis> -n= o info required</para></listitem> - <listitem><para><emphasis>XML</emphasis> -no inf= o required</para></listitem> - <listitem><para><emphasis>Java</emphasis> -no in= fo required</para></listitem> - <listitem><para><emphasis>XSD/WSDL</emphasis> -n= o info required</para></listitem> - <listitem><para><emphasis>CSV</emphasis></para><= itemizedlist> - <listitem><para><emphasis>Fields</emphasis> = -Comma separated list of CSV record field names - </para></listitem> - <listitem><para><emphasis>Separator Characte= r</emphasis> -Field separator character. Default of ','. - </para></listitem> - <listitem><para><emphasis>Quote Character</e= mphasis> -Quote character. Default of '"'. - </para></listitem> - <listitem><para><emphasis>Record Name</empha= sis> -Name of csv record element.Default:csv-record</para></listitem> - <listitem><para><emphasis>Root Name</emphasi= s> -Name of csv root element.Default:csv-set</para></listitem> - <listitem><para><emphasis>indent</emphasis> = -Add indentation character data to the generated event stream. This simply= makes - the generated event stream easier to rea= d in its serialized form. Useful for - testing etc.Default:true - </para></listitem> - <listitem><para><emphasis>Skip Lines</emphas= is> -Number of lines to skip before processing starts. Default of 0. - = - </para></listitem> - </itemizedlist> - </listitem> - <listitem><para><emphasis>EDI</emphasis></para> - <itemizedlist> - <listitem><para><emphasis>Target Profile</e= mphasis> -Defines the target profile - </para></listitem> - <listitem><para><emphasis>Encoding</emphasi= s> -The character encoding. Default "UTF-8"</para></listitem> - <listitem><para><emphasis>Mapping Model</em= phasis> -Defines the EDI Mapping Model configuration for processing the = - EDI message stream to a stream of SAX e= vents that can be processed by Smooks.</para></listitem> - <listitem><para><emphasis>Validate</emphasi= s> -This attribute turns on/off datatype validation in the EDI Parser. - Validation is on by default. - It makes sense to turn datatype validat= ion off on the EDI Reader = - if the EDI data is being bound into a J= ava Object model. - </para></listitem> - </itemizedlist> - </listitem> - <listitem><para><emphasis>JSON</emphasis></para> - <itemizedlist> - <listitem><para><emphasis>Target Profile= </emphasis> -Defines the target profile</para></listitem> - <listitem><para><emphasis>Array Element = Name</emphasis> -The element name of a array element. Default of 'element'. - </para></listitem> - <listitem><para><emphasis>Encoding</emph= asis> -encoding: The default encoding of any JSON message = - InputStream processed by this Reader= . Default of 'UTF-8'.</para></listitem> - <listitem><para><emphasis>Illegal Elemen= t Name Char Replacement</emphasis> -If illegal characters are encountered i= n a JSON element name then they are replaced with this value. - By default this is not defined, so t= hat the reader doesn't doesn't search for illegal characters. - </para></listitem> - <listitem><para><emphasis>Indent</emphas= is> -Add indentation character data to the generated event stream. This si= mply makes - the generated event stream easier to= read in its serialized form. Useful for - testing etc.Default:false. - </para></listitem> - <listitem><para><emphasis>Key Prefix on = Numeric</emphasis> -The prefix character to add if the JSON node name start= s with a number. - By default this is not defined, so t= hat the reader doesn't search for element names that start with a number. - </para></listitem> - <listitem><para><emphasis>Key Whitespace= Replacement</emphasis> -The replacement character for whitespaces in a JSO= N map key. - By default this not defined, so that= the reader doesn't search for whitespaces. - </para></listitem> - <listitem><para><emphasis>Null Value Rep= lacement</emphasis> -The replacement string for JSON NULL values. Default i= s ""(an empty string). </para></listitem> - <listitem><para><emphasis>Root Name</emp= hasis> -The element name of the document root. Default of 'json'. - </para></listitem> - <listitem><para><emphasis>Key Maps</emph= asis> -Defines a JSON element name mapping - The "from" key will be replaced with= the "to" key or the contents of the element. - </para></listitem> = = - </itemizedlist> - </listitem> - <listitem><para><emphasis>Custom</emphasis></par= a> - <itemizedlist> - <listitem><para><emphasis>Target Profile= </emphasis> -</para></listitem> - <listitem><para><emphasis>Class</emphasi= s> -Custom reader class.</para></listitem> - <listitem><para><emphasis>Handlers</emph= asis> -Set a handler on the reader instance e.g. an EntityResolver, ErrorHa= ndler etc. - </para></listitem> - <listitem><para><emphasis>Features</emph= asis> -Reader Features List</para></listitem> - <listitem><para><emphasis>Parametres</em= phasis> -Resource Parameters</para></listitem> - = - </itemizedlist> - </listitem> - </itemizedlist></entry> - <entry><itemizedlist> - <listitem><para><emphasis>CSV</emphasis></para><= itemizedlist> - <listitem><para>not defined</para></listitem> - <listitem><para>','</para></listitem> - <listitem><para>'"'</para></listitem> - <listitem><para>csv-record</para></listitem> - <listitem><para>csv-set</para></listitem> - <listitem><para>true</para></listitem> - <listitem><para>0</para></listitem> - </itemizedlist> - </listitem> - <listitem><para><emphasis>EDI</emphasis></para> - <itemizedlist> - <listitem><para>not defined</para></list= item> - <listitem><para>UTF-8</para></listitem> - <listitem><para>not defined</para></list= item> - <listitem><para>true</para></listitem> - </itemizedlist> - </listitem> - <listitem><para><emphasis>JSON</emphasis></para> - <itemizedlist> - <listitem><para>not defined</para></list= item> - <listitem><para>element</para></listitem> - <listitem><para>UTF-8</para></listitem> - <listitem><para>not defined</para></list= item> - <listitem><para>false</para></listitem> - <listitem><para>not defined</para></list= item> - <listitem><para>not defined</para></list= item> - <listitem><para>""(an empty string)</par= a></listitem> - <listitem><para>'json'</para></listitem> - <listitem><para>not defined</para></list= item> = - </itemizedlist> - </listitem> - <listitem><para><emphasis>Custom</emphasis></par= a> - <itemizedlist> - <listitem><para>no defaults</para></list= item> - = - </itemizedlist> - </listitem> - </itemizedlist></entry> - </row> = - <row> - <entry>Input Data</entry> - <entry>You should select a data file using <emphasis= >Add</emphasis> and <emphasis>Delete</emphasis> buttons</entry> - <entry></entry> - </row> - <row> - <entry>Input Model View</entry> - <entry>Using this view you can see the structure of = your input file.If the file has been changed, to see the changes - click <emphasis>Refresh</emphasis>link.</entry> - <entry></entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id=3D"mapping_task"><title>Selected Task Details secti= on for Java Mapping Task. - Selected Task Details section for this task is present= ed by the graf, - that lighten the process of java mapping. -

- Selected Task Details Section for Mapping Task.</= title> - <mediaobject> - <imageobject> - <imagedata fileref=3D"images/reference/reference= _7.png" scale=3D"90"/> - </imageobject> - </mediaobject> - </figure> - <para> This graphical editor allow you to perform drug/drop = operations with the nodes of transform data to map the source data to targe= t data. - When you save the changes in the graphical editor the correc= t Smooks configuration file content will be generated. </para> - = - </section> - <section><title>Selected Task Details section for Template Task.</ti= tle> - <para>Selected Task Details section for this task is presented b= y the graf, - that is similar to the one in the <link linkend=3D"mapping_t= ask">previous section</link>. - </para> - <figure> - <title>Selected Task Details Section for Template Task.</tit= le> - <mediaobject> - <imageobject> - <imagedata fileref=3D"images/reference/reference_7a.= png" scale=3D"90"/> - </imageobject> - </mediaobject> - </figure> - </section> - </section> - - </section> - <section id=3D"options_tab"> - <title>Options Tab - This section describes Options tab of the Smooks Configu= ration File editor, gives short recommendations how this tab can be used du= ring the project configuring. -

- Options tab of the Smooks Configuration File edito= r - - - - - - = -

- Smooks Configuration section - = - In the Smooks Configuration secti= on of Options Tab - only one element is availible:Smooks Platform Version - -

- Smooks Configuration section of Options tab</ti= tle> - <mediaobject> - <imageobject> - <imagedata fileref=3D"images/reference/referen= ce_9.png" scale=3D"90"/> - </imageobject> - </mediaobject> - </figure> - <para>This parameter is not rechangable, - and is set according to the vesion of the Smooks libra= ries that are added to the project. - </para> - </section> - = - <section> - <title>Filter Settings Filter section - = - In Filter Settings section you can set - the following global options responsible for Smooks filter= ing configuring: -

- Filter Settings section of Options tab - - - - - - - This behavior can be turned off using this global config= uration parameter and can be overriden on a per fragment basis by targettin= g a Visitor implementation at that fragment that takes ownership of the Res= ult writer (in the case of SAX filtering), or simply modifies the DOM (in t= he case of DOM filtering). As an example of this, see the FreeMarkerTemplat= eProcessor. = - -

- Options Tab. Filter Settings section. = - - - - - = - - - Option = - Description - Default - - - - - Stream Filter Type - Determines the type of processing model= that will be used. - Please refer to - Filtering Process Selection section - of the official Smooks User Guide for more= information about these models: - - SAX - DOM - - - DOM - = - = - - Default Serialization is On - Defines whether default serialization s= hould be switched on. - Default serialization being turned on lead= s to locating StreamResult/DOMResult - to the Result objects provided to the Smoo= ks.filterSource method and to - serialization all the events to that Resul= t. - true - = - - - -

= -

- - Source Tab - This section provides information about Smooks Source Ed= itor Page. -

- XML Source Editor - You can use this editor to edit the Smooks Configura= tion file directly. -

- Graphical Editor - - - - - - -

- Error underlining in Graphical Editor - If the Smooks tools can't = understand the configuration - file or the configuration file is illegal (XML structu= re isn't right for Smooks - Configuration file, etc.), the error is underlined. -

- Graphical Editor - - - - - - - -

- = -

- Smooks Configuration File Validator - Smooks configuration file validator will validate yo= ur Smooks configuration file. Just right-click on the file and then click = on the Validate button. The validator can be enabled/d= isabled in Window -> Preferences -> Validation: - = -

- Validation: Smooks Configuration File Validator= - - - - - - - = - You can set up your Smooks validator to include, exc= lude groups to validate and specify rules for validation. Just click on the= Settings button and use the options provided: - = -

- Smooks Configuration File Validator Settings</t= itle> - <mediaobject> - <imageobject> - <imagedata fileref=3D"images/source_editor/smo= oks_conf_validator_settings.png" scale=3D"90"/> - </imageobject> - </mediaobject> - </figure> - - = - </section> - </section> - </section> -</chapter> - -<chapter diffmk:change=3D"added" xml:base=3D"file:///home/vchukhutsina/rep= os/ochik_jboss/smooks/docs/reference/en/modules/summary.xml"> - <?dbhtml filename=3D"summary.html"?> - <title diffmk:change=3D"added"><diffmk:wrapper diffmk:change=3D"added"= >Summary</diffmk:wrapper> - In conclusion, with this= document you know all the capabilities of Smooks Tools and could easily st= art with them. - The chapters above walked you through the steps on how to create a= nd configure some XML to JAVA mapping project. = - If you have questions or suggestions concerned both the documentat= ion and tools behavior, - you are welcome to JBoss Tools Users forum. - Please, use Jira to report bugs and requests on documentation. - = -

- <diffmk:wrapper diffmk:change=3D"ad= ded">Other relevant resources on the topic</diffmk:wrapper> - All JBoss Developer Studio/JBoss Tools release documentation you can fi= nd at - http://docs.j= boss.org/tools in the corresponding release directory. - = - The latest documentation builds are available at http://download.jboss.org/= jbosstools/nightly-docs. -For = more information about Smooks technology please visit - - Smooks Technology Home Page - = -

- - - +]> + + + + Smooks Dev Tools Reference Guide + + + + + = + + + = + = + + + Xue(Dart) + Peng + + + 2009,2010 + JBoss by Red Hat + + + Version: 1.1.0.GA + + + + + + PDF version + + + + + + + = + + + + + JBoss Tools + Smooks + JBDS + + + Introduction + This chapter gives you a short introduction to Smooks, Smooks tools= and its installation. + First, have a look at the key features of Smooks tools: +

+ Key Features of Smooks Tools + Here, we provide you with a key functionality which is integrated = in Smooks tools. + + = + Key Functionality for Smooks Tools + + = + + + + = + + + Feature + Benefit + Chapter + + + = + + = + + Smooks Configuration File Wizard + Smooks tools allows to create/edit the Smooks configura= tion file for Java2Java data transformation. + + Smooks Configuration File Wiz= ard + + + = + + Smooks Editor + Smooks Editor helps configure the created Smooks config= uration file. + + Smooks Editor + + + = + + = + +

+ = + = + = +

+ What is Smooks? + + Smooks is a Java Framework/= Engine for processing XML and non XML + data (CSV, EDI, Java, JSON etc). + + + + + Transformation: Perform a wi= de range of + Data Transforms. Supports many different Source and Result types + -XML/CSV/EDI/Java/JSON to XML/CSV/EDI/Java/JSON. + + + Java Binding: Bind into a Ja= va Object + Model from any data source (CSV, EDI, XML, Java, JSON etc). + + + + Huge Message Processing: Pro= cess huge + messages (GBs) - Split, Transform and Route message fragments to JMS= , File, + Database etc destinations. Route multiple message formats to multiple + destinations in a single pass over a message. + + + + Message Enrichment: Enrich a= message with + data from a Database, or other Datasources. + + + + Combine: Combine the above f= eatures in + different ways e.g. add Message Enrichment as part of a Splitting and + Routing process. + + + +

+ Smooks + + + + + + + For more informations about Smooks, please visit Smooks official= site. +

+ What is Smooks Tools? + + Smooks tools is a set of graphical tools for editing Smooks config= uration file + based on Eclipse. +

+ Smooks Form editor + + + + + + + The easiest way to use the Smooks Configuration Editor is to creat= e a project + (Java project, an ESB project, etc.), right-click on it and select New -> Other + to open the New wizard. Drill into Smooks -= > Smooks Configuration File + and continue through the wizard. We recommend using a minimum Smooks le= vel of 1.1 or 1.2, but if you're using it in a deployed service, it depends= on what version your runtime supports. + Once the file is created, it will open in the Smooks Configuration Edit= or. +

+ How to install Smooks dev tools? + + The Smooks tools was included by the = JBoss Tools since 3.0.0 + Beta1 version. You can download the JBoss T= ools from JB= oss download site. + Smooks tools (JBoss Tools)= run with the latest Eclipse and + other required plug-ins (GEF, EMF, etc.). + You should download the latest IDE for Java EE developers from Eclipse site. It co= ntains many plug-ins ( + GEF, EMF, etc. ) required by Smooks dev tools. + The Smooks Configuration depends on having all of the appropriate = Smooks runtime jars in the path of the Eclipse Plug-in or Java Project in t= he Eclipse workspace. + = + The easiest solution is to do the following: + + 1) Download the Smooks distribution from here: http://= www.smooks.org/mediawiki/index.php?title=3DDownloads . + Grab the latest "ALL" distribution (as of today, it is the Smooks v.1= .2.2 "ALL" distribution) and it will include binaries, examples, etc. + 2) Extract files from the archive somewhere on your ma= chine. + 3) In your Eclipse workspace, copy the Smooks jars int= o a directory of your Eclipse plug-in or Java project named "lib". + 4) For your Eclipse Plug-in or Java Project, right-cli= ck on the project and select Properties. + 5) Select the "Java Build Path" item in the Properties= list, select the Libraries tab, and click "Add JARs" + + 6) In the Jar Selection dialog, select all the jars in= the "lib" directory mentioned in step 3 and click OK. + + 7) Click OK to = close the Properties dialog. Now you should see a "Referenced Libraries" no= de that appeared in your project hierarchy in Eclipse. + + + = + + Now let's progress to more advanced topics. +

+ + + + = + + + + + JBoss Tools + Smooks + JBDS + + + Tasks + This chapter describes the main tasks a user can be faced during= Smooks tools usage. +

+ New Smooks Configuration File Creation + Select the project where you want to create new Smooks Conf= iguration File and right-click on it, + select in the menu New &= gt; Other, then find + Smooks > Smooks Confi= guration File. + Click the + Next + button. +

+ Selecting Smooks Configuration File Wizard + + + + + + + The first wizard page is a file path creation page. Select t= he + src + folder to be the files container, and input the name + smooks-config.xml. Click + Next. +

+ Choosing the configuration file container and the file = name + + + + + + + The second wizard page allow you to select Smooks configurat= ion file version. Select the appropriate one and click Finish to complete the wizard. +

+ Input Task Configuring + = + Input task configuring = is an obligatory step for your smooks project creation. + You can configure it on the Process page of the editor: look f= or the "Input Task" in the Process Map at the top of the page. + +

+ Input Task Configuring + + + + + + + Select it and you will see all the properties to set for the= Input reader of your Smooks configuration. + "Input type" corresponds to the type of data that you will be = working with. = + For example, to work with incoming CSV (Comma-separated Values= ) data, you would specify "CSV" in the drop-down list. + Each reader type has slightly different configuration details = that must be set in the "Input configuration" area. + For instance, the CSV reader requires you to specify details s= uch as the encoding, quote character, separator character, and the list of = incoming fields. = + The EDI reader requires the encoding and the path to the Mappi= ng Model describing the incoming data. = + In the Input data section, you specify so= me sample data that conforms to your reader configuration. = + + = + + Once you've specified your reader configuration and sample dat= a, you can see the input model rendered in a tree form in the Inp= ut model section. + On the picture below you can see the correct configuration of = some XML input task. + +

+ Input Task Configuring + + + + + + +

+ "Java Mapping" or "Apply Template"? + = + Though there are many options in Smooks as far as what you c= an do with input = + data such as transformation, routing, and persistence, this ve= rsion = + of the Smooks Configuration Editor focuses only on these areas= : = + mapping to java and applying templates to create different out= put formats. = + If you have a set of Java classes you want to use the incoming= data for, = + you can use the "Java Mapping" task to specify those classes a= nd use drag and + drop to map between the input model generated by the reader an= d elements in the output model. + Or if you simply want to transform your output to one or more = formats, you can use the "Apply Template" = + task to map it to a CSV file, XML or XSD file (and other forma= ts in the future). + Note + Now you can't transform your output directly, + using only Input and Template tasks. + You should use Mapping as an interagent between these = tasks. + + +

+ Java Mapping Task + = + + If you decide to do Java Mapping, you need to make sure that y= our Input reader has been set up and you have some sample data specified. + Then you should select Input Task in the = Process tab and click the plus (+) sign to the right of the icon. + Select Java Mapping from the popup menu a= nd it will appear to the right, connected to Input Task. Then select Java Mapping task. + +

+ Java Mapping configuration + + + + + + + Another method of adding Java Mapping e= lement = + to the canvas in the Processing Tasks section is to right clic= k Input Task + element and select Java Mapping in the po= pup menu +

+ Java Mapping configuration + + + + + + = + + Right-click on the canvas in an empty space and select "Add -&= gt;Java Class". + +

+ Java Mapping configuration + + + + + + + + Java Bean Creation wizard appears. + Specify a unique identifier for the new class, the class path, = + whether it's an array or not, and if it is a collection, also = specify the collection class. + If the Java class is specified, you'll see a list of the prope= rties in the box below. + Click Finish when you're done. + Now with the input and output models on the canvas, you can cl= ick and drag = + from the various input elements to corresponding output elemen= ts. = + Make sure to connect collection elements to corresponding coll= ection elements. + Finally your mapping should look nearly like the one on the pi= cture below. + +

+ Final Mapping schema + + + + + + +

+ Apply Template Task + = + The "Apply Template" task works very similarly to the "Java Mapping" task, where you map between an in= put model and an output model. + Select the Java Mapping task you want to = use as the input model in the Process Map pane and click the plus (+) sign = to the right of the icon. + +

+ Apply Template configuration + + + + + + + + Select "Apply Template" from the popup menu and it will appear= to the right, connected to the task you created it from. Then select the "= Apply Template" task. + Once you've defined your template model, you can click and dra= g from the various input elements to corresponding output elements in the t= emplate. Make sure to connect collection elements to corresponding collecti= on elements + +

+ Smooks Configuration testing using Smooks Run Configuration= + = + This option is intended to view the results of Smooks transf= orming procedure. + For more detailed information about this option please go here. +

+ + + + = + + + + + JBoss Tools + Smooks + JBDS + + + Reference + This chapter includes detailed reference information about Smook= s Tools. +

+ Smooks Configuration Editor + This chapter describes the following tabs of the Smooks Configur= ation Editor: + + + Process tab + Options tab + Sourc= e tab + +

+ Process tab + The Process tab of the Smooks Configuration Editor helps to c= onfigure different types of transformations. + By default smooks configuration file is opened in this editor.I= f you have another default settings for editor opening + you should left click smooks configuration file and select:Open With->Smooks Configuration Editor. + The Process tab has two sections: + + Proce= ssing Task section + Selecte= d Task Details section + + You can see them on the picture below. +

+ Two Sections of the Process tab. + + + + + + +

+ Processing Task section + Using the popup menu in the Processing Task section you + can select which types of technologies(templating or mapping on= es) you will use for transofmation: + The descriptions of the popup menu options are in the fol= lowing table. + + Process Tab. Processing Task section. = + + + + + = + + + Option = + Description + Default + + + + + Add Task + Select one of the following tasks accord= ing to the necessary type of Source and Result types of the files: + + Input -this task is required and + appears automatically when Smooks c= onfig file is created. + You should just configure it proper= ly. + Java Mapping<= /emphasis> + Apply Templat= e + + + + = + = + + Delete + Click this option if you want to delete = some task from the section. + Note:you can't delete input task because it's r= equired. + + = + = + = + + Input Methods + Choose one of the following methods: + + System + Simple + Amharic(EZ+) + Cedilla + Cyrillic + Inuktitut + IPA + Multipress + SCIM Bridge Input Metho= d + SCIM Input Method + Thai-Lio + Tigrigna-Eritrean(EZ+)<= /para> + Tigrigna-Ethiopian(EZ+)= + Vietnamese + X input Method + + + System + = + + +

+ Selected Task Details Section + The options of this section depends on the selected task in th= e Processing Task section. + Because there are 3 types of tasks there are 3 different sets of= its options in the Selected Task Details Section. + They will be described one by one. +

+ Selected Task Details Section for Input Task. + On the picture below you can find an example of Select= ed Task Details Section view + if XML is selected as input type. + = +

+ Selected Task Details Section for Input XML Task.= + + + + + + + As you can see on the picture above Input Configuratio= n section is empty for XML input file. + But this section has special configuration options for C= SV,EDI,JSON,Custom input files. + = + Here are the screens of these configuration options: + + CSV: +

+ Selected Task Details Section for Input C= SV Task. + + + + + + + + EDI: +

+ Selected Task Details Section for Input E= DI Task. + + + + + + + + JSON: +

+ Selected Task Details Section for Input J= SON Task. + + + + + + + + Custom: +

+ Selected Task Details Section for Input C= ustom Task. + + + + + + + + + All the input task configuration positions can be found i= n the table below: = + + Selected Task Details Section. Options for Input Task.</t= itle> = + <tgroup cols=3D"3"> + <colspec align=3D"left" colnum=3D"1" colwidth=3D"1*"></colsp= ec> + <colspec align=3D"left" colnum=3D"2" colwidth=3D"3*"></colsp= ec> + <colspec align=3D"left" colnum=3D"3" colwidth=3D"1*"></colsp= ec> = + <thead> + <row> + <entry>Option</entry> = + <entry>Description</entry> + <entry>Default</entry> + </row> + </thead> + <tbody> + <row> + <entry>Input type</entry> + <entry>Select your type of input file. + If don't find your type in the list,you should u= se Custom type: + <itemizedlist> + <listitem><para>No Input</para></listitem> + <listitem><para>XML</para></listitem> + <listitem><para>Java</para></listitem> + <listitem><para>XSD/WSDL</para></listitem> + <listitem><para>CSV</para></listitem> + <listitem><para>EDI</para></listitem> + <listitem><para>JSON</para></listitem> + <listitem><para>Custom</para></listitem> + </itemizedlist> + </entry> + <entry>XML</entry> + </row> = + = + <row> + <entry>Input configuration + + </entry> + <entry> + <itemizedlist> + <listitem><para><emphasis>No Input</emphasis> -n= o info required</para></listitem> + <listitem><para><emphasis>XML</emphasis> -no inf= o required</para></listitem> + <listitem><para><emphasis>Java</emphasis> -no in= fo required</para></listitem> + <listitem><para><emphasis>XSD/WSDL</emphasis> -n= o info required</para></listitem> + <listitem><para><emphasis>CSV</emphasis></para><= itemizedlist> + <listitem><para><emphasis>Fields</emphasis> = -Comma separated list of CSV record field names + </para></listitem> + <listitem><para><emphasis>Separator Characte= r</emphasis> -Field separator character. Default of ','. + </para></listitem> + <listitem><para><emphasis>Quote Character</e= mphasis> -Quote character. Default of '"'. + </para></listitem> + <listitem><para><emphasis>Record Name</empha= sis> -Name of csv record element.Default:csv-record</para></listitem> + <listitem><para><emphasis>Root Name</emphasi= s> -Name of csv root element.Default:csv-set</para></listitem> + <listitem><para><emphasis>indent</emphasis> = -Add indentation character data to the generated event stream. This simply= makes + the generated event stream easier to rea= d in its serialized form. Useful for + testing etc.Default:true + </para></listitem> + <listitem><para><emphasis>Skip Lines</emphas= is> -Number of lines to skip before processing starts. Default of 0. + = + </para></listitem> + </itemizedlist> + </listitem> + <listitem><para><emphasis>EDI</emphasis></para> + <itemizedlist> + <listitem><para><emphasis>Target Profile</e= mphasis> -Defines the target profile + </para></listitem> + <listitem><para><emphasis>Encoding</emphasi= s> -The character encoding. Default "UTF-8"</para></listitem> + <listitem><para><emphasis>Mapping Model</em= phasis> -Defines the EDI Mapping Model configuration for processing the = + EDI message stream to a stream of SAX e= vents that can be processed by Smooks.</para></listitem> + <listitem><para><emphasis>Validate</emphasi= s> -This attribute turns on/off datatype validation in the EDI Parser. + Validation is on by default. + It makes sense to turn datatype validat= ion off on the EDI Reader = + if the EDI data is being bound into a J= ava Object model. + </para></listitem> + </itemizedlist> + </listitem> + <listitem><para><emphasis>JSON</emphasis></para> + <itemizedlist> + <listitem><para><emphasis>Target Profile= </emphasis> -Defines the target profile</para></listitem> + <listitem><para><emphasis>Array Element = Name</emphasis> -The element name of a array element. Default of 'element'. + </para></listitem> + <listitem><para><emphasis>Encoding</emph= asis> -encoding: The default encoding of any JSON message = + InputStream processed by this Reader= . Default of 'UTF-8'.</para></listitem> + <listitem><para><emphasis>Illegal Elemen= t Name Char Replacement</emphasis> -If illegal characters are encountered i= n a JSON element name then they are replaced with this value. + By default this is not defined, so t= hat the reader doesn't doesn't search for illegal characters. + </para></listitem> + <listitem><para><emphasis>Indent</emphas= is> -Add indentation character data to the generated event stream. This si= mply makes + the generated event stream easier to= read in its serialized form. Useful for + testing etc.Default:false. + </para></listitem> + <listitem><para><emphasis>Key Prefix on = Numeric</emphasis> -The prefix character to add if the JSON node name start= s with a number. + By default this is not defined, so t= hat the reader doesn't search for element names that start with a number. + </para></listitem> + <listitem><para><emphasis>Key Whitespace= Replacement</emphasis> -The replacement character for whitespaces in a JSO= N map key. + By default this not defined, so that= the reader doesn't search for whitespaces. + </para></listitem> + <listitem><para><emphasis>Null Value Rep= lacement</emphasis> -The replacement string for JSON NULL values. Default i= s ""(an empty string). </para></listitem> + <listitem><para><emphasis>Root Name</emp= hasis> -The element name of the document root. Default of 'json'. + </para></listitem> + <listitem><para><emphasis>Key Maps</emph= asis> -Defines a JSON element name mapping + The "from" key will be replaced with= the "to" key or the contents of the element. + </para></listitem> = = + </itemizedlist> + </listitem> + <listitem><para><emphasis>Custom</emphasis></par= a> + <itemizedlist> + <listitem><para><emphasis>Target Profile= </emphasis> -</para></listitem> + <listitem><para><emphasis>Class</emphasi= s> -Custom reader class.</para></listitem> + <listitem><para><emphasis>Handlers</emph= asis> -Set a handler on the reader instance e.g. an EntityResolver, ErrorHa= ndler etc. + </para></listitem> + <listitem><para><emphasis>Features</emph= asis> -Reader Features List</para></listitem> + <listitem><para><emphasis>Parametres</em= phasis> -Resource Parameters</para></listitem> + = + </itemizedlist> + </listitem> + </itemizedlist></entry> + <entry><itemizedlist> + <listitem><para><emphasis>CSV</emphasis></para><= itemizedlist> + <listitem><para>not defined</para></listitem> + <listitem><para>','</para></listitem> + <listitem><para>'"'</para></listitem> + <listitem><para>csv-record</para></listitem> + <listitem><para>csv-set</para></listitem> + <listitem><para>true</para></listitem> + <listitem><para>0</para></listitem> + </itemizedlist> + </listitem> + <listitem><para><emphasis>EDI</emphasis></para> + <itemizedlist> + <listitem><para>not defined</para></list= item> + <listitem><para>UTF-8</para></listitem> + <listitem><para>not defined</para></list= item> + <listitem><para>true</para></listitem> + </itemizedlist> + </listitem> + <listitem><para><emphasis>JSON</emphasis></para> + <itemizedlist> + <listitem><para>not defined</para></list= item> + <listitem><para>element</para></listitem> + <listitem><para>UTF-8</para></listitem> + <listitem><para>not defined</para></list= item> + <listitem><para>false</para></listitem> + <listitem><para>not defined</para></list= item> + <listitem><para>not defined</para></list= item> + <listitem><para>""(an empty string)</par= a></listitem> + <listitem><para>'json'</para></listitem> + <listitem><para>not defined</para></list= item> = + </itemizedlist> + </listitem> + <listitem><para><emphasis>Custom</emphasis></par= a> + <itemizedlist> + <listitem><para>no defaults</para></list= item> + = + </itemizedlist> + </listitem> + </itemizedlist></entry> + </row> = + <row> + <entry>Input Data</entry> + <entry>You should select a data file using <emphasis= >Add</emphasis> and <emphasis>Delete</emphasis> buttons</entry> + <entry></entry> + </row> + <row> + <entry>Input Model View</entry> + <entry>Using this view you can see the structure of = your input file.If the file has been changed, to see the changes + click <emphasis>Refresh</emphasis>link.</entry> + <entry></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id=3D"mapping_task"><title>Selected Task Details secti= on for Java Mapping Task. + Selected Task Details section for this task is present= ed by the graf, + that lighten the process of java mapping. +

+ Selected Task Details Section for Mapping Task.</= title> + <mediaobject> + <imageobject> + <imagedata fileref=3D"images/reference/reference= _7.png" scale=3D"90"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para> This graphical editor allow you to perform drug/drop = operations with the nodes of transform data to map the source data to targe= t data. + When you save the changes in the graphical editor the correc= t Smooks configuration file content will be generated. </para> + = + </section> + <section><title>Selected Task Details section for Template Task.</ti= tle> + <para>Selected Task Details section for this task is presented b= y the graf, + that is similar to the one in the <link linkend=3D"mapping_t= ask">previous section</link>. + </para> + <figure float=3D"0"> + <title>Selected Task Details Section for Template Task.</tit= le> + <mediaobject> + <imageobject> + <imagedata fileref=3D"images/reference/reference_7a.= png" scale=3D"90"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + </section> + + </section> + <section id=3D"options_tab"> + <title>Options Tab + This section describes Options tab of the Smooks Configu= ration File editor, gives short recommendations how this tab can be used du= ring the project configuring. +

+ Options tab of the Smooks Configuration File edito= r + + + + + + = +

+ Smooks Configuration section + = + In the Smooks Configuratio= n section of Options Tab + only one element is availible:Smooks Platform Version + +

+ Smooks Configuration section of Options tab</ti= tle> + <mediaobject> + <imageobject> + <imagedata fileref=3D"images/reference/referen= ce_9.png" scale=3D"90"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>This parameter is not rechangable, + and is set according to the vesion of the Smooks libra= ries that are added to the project. + </para> + </section> + = + <section> + <title>Filter Settings Filter section + = + In Filter Settings section you can set + the following global options responsible for Smooks filter= ing configuring: +

+ Filter Settings section of Options tab + + + + + + + This behavior can be turned off using this global config= uration parameter and can be overriden on a per fragment basis by targettin= g a Visitor implementation at that fragment that takes ownership of the Res= ult writer (in the case of SAX filtering), or simply modifies the DOM (in t= he case of DOM filtering). As an example of this, see the FreeMarkerTemplat= eProcessor. = + +

+ Options Tab. Filter Settings section. = + + <= /colspec> + <= /colspec> + <= /colspec> + = + + + Option = + Description + Default + + + + + Stream Filter Type + Determines the type of processing model= that will be used. + Please refer to + Filtering Process Selection section + of the official Smooks User Guide for more= information about these models: + + SAX + DOM + + + DOM + = + = + + Default Serialization is On + Defines whether default serialization s= hould be switched on. + Default serialization being turned on lead= s to locating StreamResult/DOMResult + to the Result objects provided to the Smoo= ks.filterSource method and to + serialization all the events to that Resul= t. + true + = + + + +

= +

+ + Source Tab + This section provides information about Smooks Source Ed= itor Page. +

+ XML Source Editor + You can use this editor to edit the Smooks Configura= tion file directly. +

+ Graphical Editor + + + + + + +

+ Error underlining in Graphical Editor + If the Smooks tools can't understand the configuration + file or the configuration file is illegal (XML structu= re isn't right for Smooks + Configuration file, etc.), the error is underlined. +

+ Graphical Editor + + + + + + + +

+ = +

+ Smooks Configuration File Validator + Smooks configuration file validator will validate yo= ur Smooks configuration file. Just right-click on the file and then click = on the Validate button. The validato= r can be enabled/disabled in Window -= > Preferences -> Validation: + = +

+ Validation: Smooks Configuration File Validator= + + + + + + + = + You can set up your Smooks validator to include, exc= lude groups to validate and specify rules for validation. Just click on the= Settings button and use the options= provided: + = +

+ Smooks Configuration File Validator Settings</t= itle> + <mediaobject> + <imageobject> + <imagedata fileref=3D"images/source_editor/smo= oks_conf_validator_settings.png" scale=3D"90"></imagedata> + </imageobject> + </mediaobject> + </figure> + + = + </section> + </section> + </section> +</chapter> + + = +<chapter xml:base=3D"file:///home/vchukhutsina/repos/ochik_jboss/smooks/do= cs/reference/en/modules/summary.xml"> + <?dbhtml filename=3D"summary.html"?> + <title>Summary + In conclusion, with this document you know all the capabilities = of Smooks Tools and could easily start with them. + The chapters above walked you through the steps on how to create a= nd configure some XML to JAVA mapping project. = + If you have questions or suggestions concerned both the documentat= ion and tools behavior, + you are welcome to JBoss Tools Users forum. + Please, use Jira to report bugs and requests on documentation. + = +

+ Other relevant resources on the topic + All JBoss Developer Studio/JBoss Tools release documentation= you can find at + http://docs.jboss.o= rg/tools in the corresponding release directory. + = + The latest documentation builds are available at http://download.jbos= s.org/jbosstools/nightly-docs. +For more information about Smooks technology please visit + + Smooks Technology Home Page + = +

+ + + Modified: trunk/smooks/docs/reference/en/modules/introduction.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/smooks/docs/reference/en/modules/introduction.xml 2010-03-09 18:2= 4:28 UTC (rev 20714) +++ trunk/smooks/docs/reference/en/modules/introduction.xml 2010-03-09 18:5= 5:57 UTC (rev 20715) @@ -45,7 +45,7 @@ Smooks Editor Smooks Editor helps configure the created Smooks config= uration file. - Smooks Editor + Smooks Editor = @@ -64,7 +64,7 @@ What is Smooks? = Smooks is a Java Framework/Engine for process= ing XML and non XML - data (CSV, EDI, Java, JSON etc). + data (CSV, EDI, Java, JSON etc).It provides: @@ -121,13 +121,46 @@ - The easiest way to use the Smooks Configuration Editor is to creat= e a project +

+ Adding Smooks jars + = + During your development, you probably will be faced with the = + necessity to include some additional Smooks jars to your project. + This problem can be solved in such a way: + + Create the folder named "lib" inside your project,if it = doesn't exist yet. + Copy all the Smooks jars you need to include into the lib directory. + + Right-click on the project and select Properties. + Select the "Java Build Path" item in the Properties lis= t, then the Libraries tab, and click "Add JARs". + + In the Jar Selection dialog, select all the jars in the= "lib" directory you want to include and click OK. + + Now you should see all the jars = + included to your project hierarchy. + + = +

+ Smooks Form editor + + + + + + + +

+ Modified: trunk/smooks/docs/reference/en/modules/references.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/smooks/docs/reference/en/modules/references.xml 2010-03-09 18:24:= 28 UTC (rev 20714) +++ trunk/smooks/docs/reference/en/modules/references.xml 2010-03-09 18:55:= 57 UTC (rev 20715) @@ -9,17 +9,8 @@ Reference - This chapter includes detailed reference information about Smook= s Tools. -

- Smooks Configuration Editor - This chapter describes the following tabs of the Smooks Configur= ation Editor: - - - Process tab - Options tab - Sourc= e tab - -

+ This chapter includes detailed reference information about all t= abs of the Smooks Configuration Editor. +

Process tab The Process tab of the Smooks Configuration Editor helps to c= onfigure different types of transformations. By default smooks configuration file is opened in this editor.I= f you have another default settings for editor opening @@ -62,7 +53,7 @@ Add Task Select one of the following tasks accord= ing to the necessary type of Source and Result types of the files: - Input -this task is required and + Input - this task is required and appears automatically when Smooks c= onfig file is created. You should just configure it proper= ly. Java Mapping<= /emphasis> @@ -210,36 +201,36 @@ - No Input -n= o info required - XML -no inf= o required - Java -no in= fo required - XSD/WSDL -n= o info required + No Input - = no info required + XML - no in= fo required + Java - no i= nfo required + XSD/WSDL - = no info required CSV<= itemizedlist> - Fields = -Comma separated list of CSV record field names + Fields = - Comma separated list of CSV record field names - Separator Characte= r -Field separator character. Default of ','. + Separator Characte= r - Field separator character. Default of ','. - Quote Character -Quote character. Default of '"'. + Quote Character - Quote character. Default of '"'. - Record Name -Name of csv record element.Default:csv-record - Root Name -Name of csv root element.Default:csv-set - indent = -Add indentation character data to the generated event stream. This simply= makes + Record Name - Name of csv record element.Default:csv-record + Root Name - Name of csv root element.Default:csv-set + indent = - Add indentation character data to the generated event stream. This simpl= y makes the generated event stream easier to rea= d in its serialized form. Useful for testing etc.Default:true - Skip Lines -Number of lines to skip before processing starts. Default of 0. + Skip Lines - Number of lines to skip before processing starts. Default of 0. = EDI - Target Profile -Defines the target profile + Target Profile - Defines the target profile - Encoding -The character encoding. Default "UTF-8" - Mapping Model -Defines the EDI Mapping Model configuration for processing the = + Encoding - The character encoding. Default "UTF-8" + Mapping Model - Defines the EDI Mapping Model configuration for processing the = EDI message stream to a stream of SAX e= vents that can be processed by Smooks. - Validate -This attribute turns on/off datatype validation in the EDI Parser. + Validate - This attribute turns on/off datatype validation in the EDI Parser. Validation is on by default. It makes sense to turn datatype validat= ion off on the EDI Reader = if the EDI data is being bound into a J= ava Object model. @@ -248,40 +239,40 @@ JSON - Target Profile= -Defines the target profile - Array Element = Name -The element name of a array element. Default of 'element'. + Target Profile= - Defines the output transformation profile + Array Element = Name - The element name of a array element. Default of 'element'. - Encoding -encoding: The default encoding of any JSON message = + Encoding - encoding: The default encoding of any JSON message = InputStream processed by this Reader= . Default of 'UTF-8'. - Illegal Elemen= t Name Char Replacement -If illegal characters are encountered i= n a JSON element name then they are replaced with this value. + Illegal Elemen= t Name Char Replacement - If illegal characters are encountered = in a JSON element name then they are replaced with this value. By default this is not defined, so t= hat the reader doesn't doesn't search for illegal characters. - Indent -Add indentation character data to the generated event stream. This si= mply makes + Indent - Add indentation character data to the generated event stream. This s= imply makes the generated event stream easier to= read in its serialized form. Useful for testing etc.Default:false. - Key Prefix on = Numeric -The prefix character to add if the JSON node name start= s with a number. + Key Prefix on = Numeric - The prefix character to add if the JSON node name star= ts with a number. By default this is not defined, so t= hat the reader doesn't search for element names that start with a number. - Key Whitespace= Replacement -The replacement character for whitespaces in a JSO= N map key. + Key Whitespace= Replacement - The replacement character for whitespaces in a JS= ON map key. By default this not defined, so that= the reader doesn't search for whitespaces. - Null Value Rep= lacement -The replacement string for JSON NULL values. Default i= s ""(an empty string). - Root Name -The element name of the document root. Default of 'json'. + Null Value Rep= lacement - The replacement string for JSON NULL values. Default = is ""(an empty string). + Root Name - The element name of the document root. Default of 'json'. - Key Maps -Defines a JSON element name mapping + Key Maps - Defines a JSON element name mapping The "from" key will be replaced with= the "to" key or the contents of the element. = = Custom - Target Profile= - - Class -Custom reader class. - Handlers -Set a handler on the reader instance e.g. an EntityResolver, ErrorHa= ndler etc. + Target Profile= - Defines the output transformation profile + Class - Custom reader class. + Handlers - Set a handler on the reader instance e.g. an EntityResolver, ErrorH= andler etc. - Features -Reader Features List - Parametres -Resource Parameters + Features - Reader Features List + Parametres - Resource Parameters = @@ -353,7 +344,7 @@

- This graphical editor allow you to perform drug/drop = operations with the nodes of transform data to map the source data to targe= t data. + This graphical editor allows you to perform drag&= drop operation with the nodes of transformed data to map the source data to= target data. When you save the changes in the graphical editor the correc= t Smooks configuration file content will be generated. =

@@ -444,7 +435,7 @@ DOM - DOM + SAX = = @@ -453,7 +444,7 @@ Default serialization being turned on lead= s to locating StreamResult/DOMResult to the Result objects provided to the Smoo= ks.filterSource method and to serialization all the events to that Resul= t. - true + false = @@ -520,5 +511,5 @@ =