Bug 780673 (SOA-3115)

Link: Added: This issue relates to SOA-3114

Reminder that Documentation Stage has now been moved to this server:  

http://documentation-stage-01.lab.eng.bne.redhat.com/

Parent: Added: SOA-3147

1) Unify the glossary:
  - Javabean Cartridge / JavaBean Cartridge
  - templating engine / template engine
  - Javabean / JavaBean

2) Correct:
Page 2 -- withinthe ESB pipeline --> within the
Page 7 -- FreeMarker is a templating engine --> template engine
glossary dependent -- page 9 -- Javabean binding --> JavaBean
Page 11 -- functionality.Each --> functionality. Each
glossary dependent -- page 11 -- Javabean --> JavaBean
? Page 13 -- beanId --> BeanId
Page 14 -- nanoSeconds --> nanoseconds
Page 18 -- propeties --> properties
glossary dependent -- page 40 -- Javabean --> JavaBean
Page 41 -- determins --> determines
Page 50 -- ontoor --> onto
Page 60 -- Java Binding Configuratons --> Java Binding Configurations
Page 62 -- Html Reporting --> HTML Reporting
glossary dependent -- page 65 -- FreeMarker is a very powerful templating engine --> FreeMarker is a very powerful template engine
glossary dependent -- page 75 -- javabean cartridge
Page 102 -- namesaces --> namespaces

Chapter 1)
 - non- XML --> non-XML
 - This is the ability to change data between many formats including XML, CSV, EDI, and Java --> missing full stop
 - Figure 1.1. Transformation --> poor quality - unreadable
 - or, as templates from which XML --> extra comma
 - these message --> these messages
 - employ this feature is used to "enrich" --> employing this feature is used to "enrich"
 - Figure 1.4. Message Enrichment --> poor quality - unreadable
 - in order to read from, and write to, it. --> extra comma

=== global ===
Example style should contain numbering and label

Chapter 2)
 - To support visitor logic implement either the SAX or DOM filters through one or both of the following interfaces: org.milyn.delivery.sax.SAXElementVisitor org.milyn.delivery.dom.DOMElementVisitor. --> separate the two interfaces somehow -- comma, "and" or graphically
 - generate an event stream, to which visitor logic --> extra comma ?
 - This event model has an advantage it that it can applied --> This event model has an advantage *in* that it can *be* applied
 - Figure 2.2. Implementing Visitor Logic --> poor quality - unreadable
 - Now, it must be executed: --> extra comma ?
 - They instruct Smooks as to which message fragments it is to apply visitor logic, and also as work as simple look-up values for non-visitor logic. --> rewrite (The selectors instruct Smooks as to which message fragments to apply visitor logic, and also function as simple look-up values for non-visitor logic.)
 - functionality.Each cartridge --> functionality. Each cartridge (space)
 - Example 2.3. Setting the filter type to SAX in Smooks 1.3 --> duplicates previous note
 - example 1 in chapter 2.6 --> missing syntax highlighting
 - When adding or retrieving objects from the BeanContext --> emphasize BeanContext as class name
 - PUUID: UniqueId bean. This bean provides unique identifiers for the filtering ExecutionContext. --> emphasize PUUID?
 - PTIME: Time bean. This bean provides time-based data for the filtering ExecutionContext. --> emphasize PTIME?
 - This is where message fragment events are used to trigger routing of message fragments to external end-points such as when you when splitting and routing. --> too much "when"
 - Remember is that Smooks can generate output in either (or both) of the ways listed above in a single filtering pass of a message stream. --> rewrite
 - public void filterSource(Source source, Result... results) throws SmooksException --> syntax highlighting
 - Smooks can work with standard JDK StreamResult and DOMResult result types, as well as these specialist ones: --> emphasize class names, next item list -- emphasize class names? simple result is a class or not?
 - (You can apply visitor logic c to the event stream before serialization.) --> extra "c"
 - chapter 2.6.3 --> emphasize class names and "Smooks.filterSource"
 - Smooks is also able to generate different types of output during the Smooks.filterSource --> emphasize Smooks.filterSource
 - By default, it terminates at the end of the targeted fragment, (that is, on the visitAfter event.) --> correct punctuation
 - This is the default selector name-space, ad is used where no other name-space is defined.  --> "ad" = "as"?
 - This is the default target profile that is applied to all of the resources in the Smooks configuration file, where no other a target-profile has been defined. --> "no other a"?
 - The exception here is System.in, which will never be closed. --> System.in?
 - (the default istrue). --> is true
 - The exception here is System.out and System.err, which are never closed. --> System.out and System.err?

Chapter 3)
 - all examples --> highlight syntax and add numbering
 - Edifact Java Compiler --> emphasize in whole document
 - URN --> emphasize in whole document
===================================================
 - specialist XML reader. --> special?
 - By setting the rootElementName and recordElementName attributes, you can modify the csv-set and csv-record element names. The same rules apply for these names. --> emphasize element & attribute names
 - $ignore$ --> emphasize in whole text
 - To execute this configuration, use this code: --> following example is a mix of two examples (Java and Smooks configuration with an explanation)
 - If you are just interested in binding fixed-length records directly to a list or map of a Java type that reflects the data in your fixed-length records, --> fixed-length unbreakable hyphen mark
 - FixedLengthListBinder or the FixedLengthMapBinder classes: --> emphasize class names
 - EDI processing in Smooks supported through the http://www.milyn.org/xsd/smooks/edi-1.2.xsd configuration name-space. --> missing verb, following item list -- emphasize attribute names
 - (using Java bindings a la jb:bean). "a la"?
 - whole next paragraphs --> emphasize element names (medi:segment, minOccurs, maxOccurs etc)
 - by a regex pattern match on the full segment, where the segcode attribute defines the regex pattern (for instance, segcode="1A\*a.*"). -- correct emphasizing -- brackets
 - Segments and segments containing child segments can be separated into another file for easier future reuse. --> following item list -- emphasize mentioned terms
 - do the same also with next item lists
 - You can put the type system to a number of uses, including: --> following list item -- either end all items with a dot or leave them without dots
 - TO run under Ant, create and execute the EJC task. This code shows you how to do so: --> "TO" = "To", emphasize Ant and EJC(?)
 - UN/EDIFACT interchanges are supported through a specialized variant of the base edi:reader. --> "base"="basic"?
 - UNEdifactReaderConfigurator --> class name
 - This example code shows you how to process a D03B UN/EDIFACT message interchange: --> following example is a mix of two examples (reading, writing)
 - To reader offers multiple solutions to this problem. --> ???
 - JSON NULL values. --> JSON null values.
 - Note: This feature is deprecated. Instead, you should now manage the JSON stream Ssurce character encoding by supplying a java.io.Reader to the Smooks.filterSource() method. --> put in note style
 - java.io.Reader to the Smooks.filterSource() method. --> un-emphasize "to the"
 - YAML allows you to use characters in the key name that are not allowed in the XML element name. To reader offers multiple solutions to this problem. It can search and replace white spaces, illegal characters and the number in key names that start with a number. You can also use it to replace one key name with a completely different one. The following sample code demonstrates all of these features: --> duplicates description of the same situation with JSON -- rewrite not to be identical, because it disrupts the reader
 - The element with the anchor obtains the id. attribute containing the name from the anchor as the attribute value. --> extra period after id
 - YamlReaderConfigurator --> emphasize class name
 - org.milyn.delivery.JavaSource --> class name
 - The CSV and fixed-length readers allow you to execute string manipulation functions on the input data before that the data is converted into SAX events. --> that the?

Chapter 4)
 - all examples --> highlight syntax and add numbering
 - all list items --> highlight terms being exaplained where appropriate
 - src: this can be a file or anything else that is meaningful to the RuleProvider. . It is mandatory. --> too many periods..
 - but you can specify multiple ruleBase elements and have as many RuleProviders you need. --> as many as you need
 - e.-mail address. --> e-mail address
 - standard .properties file format --> emphasize .properties
 - "Is the product in the targeted order item fragment within the age eligibility constraints of the customer specified in the order header details?" --> not english quotation marks
 - the contextual data is references using the normal FreeMarker notation. --> rewrite
 - Smooks) : --> remove extra space
 - e.-mail address is in a valid format. --> e-mail
 - Finally, you need to confirm that the total for each order item does not exceed 50.00 (price * quantity is greater than 50.00). --> exceed 50, greater than 50?
 - The message bundle for the rules defined in rules/customer.properties is located in the rules/i18n/customer.properties file: --> following example -- check syntax of comments inside
 - The message bundle for the rule defined in rules/product.properties is located in the rules/i18n/product.properties file: --> following example -- check syntax of comments inside
 - The message bundle for the rule defined in rules/order-rules.csv is located in the rules/i18n/order-rules.properties file: --> following example -- check syntax of comments inside

Chapter 5)
 - all list items --> highlight terms being exaplained where appropriate
 - whole document --> english quotation marks
 - Install the schema in your IDE to avail yourself of its auto-completion functionality. --> rewrite
 - The Javabean Cartridge sets the following conditions to Java beans: --> following item list -- all end with a period or all without
 - ((1), (2), (3) - all accepts (4)) --> too many parenthesis -- (1, 2, 3 - all accepts 4) -- what does it mean all accepts? -- the hyphen is written as minus (rewrite)
 - all description of the above configuration contain too many parenthesis -- quite unreadable with the doubles -- ((
 - all terms in the above configuration should be emphasized -- for example "execOnElement"
 - (see the beanIdRef attribute values and how the reference the beanId values defined on (2) and (3)) --> see ... and how the reference the beanId? -- rewrite
 - Configuration (2) creates the com.acme.Header bean instance. --> missing bullet
 - ontoor the Header.customerNumber --> onto?
 - (3) Configuration (3) creates the ListOrderItem bean instance for holding the OrderItem instances. --> too much "3"
 - (4) Configuration (4) --> too much "4"
 - (one example being that the DateDecoder [decoder="Date"]). --> that?
 - The decodeParam iformat s based on the ISO 8601 standard for date formatting. --> probrably "format is"
 - Here is an Integer example: --> following note is much the same as the previous one, rewrite not to be so redundant -- readability
 - (for instance, the numeric value 876592.00 might be represented as "876_592!00"jb:bean element for some reason). --> rewrite, insert some space probably
 - In order to decode this value as (for isntalce) --> for instance?
 - which is a simple expression that you can applied to the Sting value before decoding it. --> you can applied?
 - that operates on the value String --> that operates on the String value
 - (The 'instanceMethod part is optional. --> "'"?
 - There are three ways in which you can declare which definition language you want to use: --> rewrite these three ways, details follow:
 - For example. --> For example: <example style>....</example style>
 - Note:If you have a definition with your default language that includes a ':' then you must prefix that definition with 'default:' else you will run into an Exception. --> put into note style
 - MVEL as factory definition language --> is it a heading or what?
 - If MVEL where the default language then we couldn’t do anything to improve --> where? -- probably was or were
 - Binding Key Value Pairs into Maps --> heading?
 - On the config: --> label the examples better
 - as part of a model driven transform --> transformation
 - Merging Multiple Data Entities Into a Single Binding --> heading?
 - The ValueBinder class is the visitor that does the value binding. --> heading?
 - The value binding XML configuration is part of the JavaBean schema from Smooks 1.3 on: http://www.milyn.org/xsd/smooks/javabean-1.4.xsd. The element for the value binding is value. --> following item list -- end all items with a period or without
 - default : The default value for if the selected data is null or an empty string. --> rewrite
 - "Example" following above list item --> emphasize somehow
 - "Message" --> convert to example description
 - "The Configuration" --> convert to example description
 - The value binder can be programmatic configured using the org.milyn.javabean.Value Object.  --> programmatically, "Object" = "object"
 - "The Message:" --> convert to example description
 - "The Java Model (not including getters/setters):" --> convert to example description
 - "The Configuration Code:" --> convert to example description... do the same rules as for headings apply here? -- "Code"="code"?
 - "The Execution Code:" --> convert to example description... do the same rules as for headings apply here? -- "Code"="code"?
 - The optional "-p" properties file parameter allows specification of additional config parameters: --> next list item is nested, so the bullets have to be indented more
 - The Html Reporting tool --> HTML?
 - your Source data --> "Source"="source"?
 - Note the "$TODO$" tokens. --> emphasize $TODO$ in other way
 - This will mean that some of the JavaSource bean instances may be visible in the JavaResult. --> meant?

Chapter 6)
 - two kinds of template --> templates
 - split-message fragments --> split message fragments
 - Use <ftl:outputTo>, to --> Use <ftl:outputTo> to (extra comma?)
 - types of external template --> types of external templates?

Chapter 7)
 - all examples --> highlight syntax and add numbering

Chapter 8)
 - all examples --> add numbering
 - by adding two more "pens." --> "pens".

Chapter 9)
 - The above configuration shows routing using the ‘beanId’ attribute. It is also possible to route using an attribute named ‘routeOnElement' --> period

Chapter 10)
 - When it has been enabled, the HTMLReportGenerator incurs a significant performance overhead and with large message, can even result in OutOfMemory exceptions. --> , with large message,

Chapter 12)
 - (Gbs in size). --> GB
 - Performance Hint: --> Performance hint:
 - This can be done in one of 2 ways --> This can be done in one of two ways
 - 2 FreeMarker templates.--> two FreeMarker templates.
 - and a seconds to cover the item elements. --> and a second
 - You will notice the ?TEMPLATE-SPLIT-PI? --> style not to run from the main text
 - it effectively generates output into the location of the ?TEMPLATE-SPLIT-PI? --> style not to run from the main text
 - That's it This is available as a runnable example in the Tutorials section. --> rewrite
 - This approach to performing a One-to-One Transformation of a huge message works simply because the only objects in memory at any one time are the order header details and the current order-item details (in the Virtual Object Model).? --> unreadable -- also period followed by question mark
 - if the messages needs to have all the order items reversed in order (or sorted).? --> rewrite -- also period followed by question mark
 - order items in an an order message --> just one "an"
 - (based on content - "Content Base Routing") --> use correct hyphen, not minus sign
 - "destination1" required XML via the file system, --> requires
 - Smooks offers to approaches to creating the split messages: --> two
 - where you configure Smooks to extract data from the source message and and into --> two "and"
 - Basic Splitting and Routing As stated above, --> Basic Splitting and Routing -- should be heading probably

Chapter 13)
 - basic <resource-config> --> unbreakable dash
 - This can be a Java Class name --> This can be a Java class name
 - in the the resource element --> in the the resource element -- two "the"
 - selector e.g. if the resource is a Visitor instance, it knows the selector is an XPath, selecting a Source message fragment. --> split somehow, maybe ;
 - Refer to http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/XMLReader.html for more details. --> invalid link
 - parse(InputSource) :--> remove extra space
 - instance, which you then set on the Smookscode> i --> rewrite
 - ... Other Smooks configurations e.g. <jb:bean> configs for binding the binary data into Java objects... --> comments in examples -- should really be comments; <!-- --> for xml
 - smooks.filterSource(...); --> add style and numbering to the whole example

Chapter 15)
 - the transform_ quick starts in particular. --> correct the quickstart name
 - Transform_XML2POJO quick starts --> transform_XML2POJO2 quickstart
 - quick start called /samples/quickstarts/transform_XML2POJO2/ --> quickstart called transform_XML2POJO2
 - The quick start runs --> quickstart
 - This is configuration is designed to transform a DVD Store message into Java Objects. --> this is ... is
 - This is configuration is designed to transform a DVD Store message into Java Objects. --> this is ... is -- second time

Release Notes Text: Added: Corrected problems where appropriate.

Closing - QE doc reviews are complete.