Hide Forgot
Affects: Documentation (Ref Guide, User Guide, etc.) Date of First Response: 2009-12-09 15:42:20 project_key: SOA Len, please find attached the draft copy of the SOA-P 5.0 Programmers' Guide for Phase 1 QE. Please alert us to any information that is missing, erroneous or out-of-date. Many thanks.
Attachment: Added: Programmers_Guide.pdf
Link: Added: This issue depends SOA-1661
Section: 4.1.1. Listeners Text: Listeners encapsulate the end-points for ESB-aware message reception. Upon receipt of a message, a Listener feeds that message into a "pipeline" of message processors. These process the message before routing the result to the "replyTo" end-point. The action processing that takes place in the pipeline may consist of steps in which the message is transformed by one processor, then some business logic is applied by the next and so on, before the result is routed to eitehr the next step in the pipeline, or to another end-point. Comment: Misspelling: eitehr ------------------- Section: 4.1.2. updated Routers Text: Tools like StaticWiretap and StaticRouter can... Comment: StaticWiretap is printed in bold, StaticRouter in italics ------------------- Section: 4.3. Updated What is a Service? Text: The JBoss Enterprise Service Bus does not impose restrictions with regard to what should constitute a service. Comment: Section 3.1 stated: '...In the JBoss Enterprise Service Bus, a service is defined as "a list of action classes that process a Message in a sequential manner." How about changing the opening line in 4.3 to: In the JBoss Enterprise Service Bus, a service is defined as "a list of action classes that process a Message in a sequential manner." Within this definition, the JBoss Enterprise Service Bus does not impose restrictions with regard to what should constitute a service. ------------------- Section: 6.1.5. Updated. Configuring for a Remote Service Invoker Text: log4j-1.2.14.jar stax-1.2.0.jar scout-1.2.0.aop.jar commons-logging-1.1.jar jboss-aop-jdk50-1.5.6.GA.jar javassist-3.6.0.GA.jar juddi-core-3.0.0.jar juddi-ws-3.0.0.jar (no such file in 5.0 ER5) xercesImpl-2.8.0.jar Comment: In ER5, the files are named: log4j.jar stax-ex.jar scout-1.2.aop.jar commons-logging.jar jboss-aop-jdk50.jar javassist.jar juddi-core-3.0.0.aop.jar xercesImpl.jar ------------------- Section 9.1. Overview Text: http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd Comment: 404 not found error. The correct link is: http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.2.0.xsd ------------------- Section Table 9.6, Table 9.7 Comment: Why are these pages in landscape mode? ------------------- 11.1.1. Updated. Transformers & Converters Comment: Formatting of columns is corrupted for XsltAction 11.1.1. SmooksAction Comment: The note refers to smooks 1.1 - we are shipping 1.2 in SOA-P 5.0 ------------------- Section: 11.3. Updated. Scripting 9 Text: 1. "script": Path (on classpath) to Groovy script. Properties Comment: There is no footnote #9. Text: ScriptingAction 10 Executes a script using the Bean Scripting Framework (BSF ), receiving the message, payloadProxy, action configuration and logger as variable input. Some notes: 11 12 1. JBoss ESB 4.7 contains BSF 2.3.0, which has less language support than BSF 2.4.0 (for 13 14 15 example: no Groovy , and non-functioning Rhino ). A future version will contain BSF 2.4.0, 16 17 which will support Groovy and Rhino . 18 2. BSF does not provide an API to pre-compile, cache and reuse scripts. Because of this, each execution of the ScriptingAction will go through the compile step again. Please keep this in mind while evaluating your performance requirements. 19 3. When including BeanShell scripts in your application, it is advised to use a .beanshell 20 extension instead of .bsh, otherwise the JBoss BSHDeployer might pick it up. Comment: The page only inlcudes footnote #10. ------------------- Section 11.5. Updated. Routing Subsection: ContentBasedRouter Text: Regex is configured in exactly the same way as XPath. The only difference being that it uses Regex expressions (as opposed to XPath ones.) JBoss Rules: <action process="split" name="ContentBasedRouter" class="org.jboss.soa.esb.actions.ContentBasedRouter"> <property name="cbrAlias" value="Drools"/> <property name="ruleSet" value="MyESBRules-XPath.drl"/> <property name="ruleLanguage" value="XPathLanguage.dsl"/> <property name="ruleReload" value="true"/> <property name="destinations"> <route-to destination-name="express" service-category="ExpressShipping" service-name="ExpressShippingService"/> <route-to destination-name="normal" service-category="NormalShipping" service-name="NormalShippingService"/> </property> </action> See the "What is Content-Based Routing?" chapter in the Services Guide for more information on content-based routing. Comment: The text refers to Regex, but has Drools in the example code. -------------------
Reviewed this version of the doc - see attached - downloaded from: http://documentation-stage.bne.redhat.com/docs/en-US/index.html The HTTP gateway is still not there.
Attachment: Added: Dec_9_reviewed_Programmers_Guide.pdf
Link: Added: This issue depends SOA-1701
Assigning back to David for final edits pre-beta.
One more thing - MessageAlerts are not documented in the programmers' guide yet either.
Len, I have made these changes as you suggested. Check that the HTTP Gateway information is correct. You should be able to see it now that the doc-stage can show the correct versions of the document. It is being published now and will be available in a few hours. The missing footnotes is, however, an outstanding issue. Each of those footnotes referenced the full URL of the hyperlinks in the body text. There is a problem whereby they are not displaying.
The edits look fine - except for the footnotes - what's the problem blocking these?
I have rewritten the section to work around the footnote bug.
5.0.0 Beta1 doc is available on http://redhat.com/docs/JBoss_SOA_Platform/
See highlights in attachment programmers_1.jpg for duplicated text
Attachment: Added: programmers_1.jpg
See highlights in attachment programmers_2.jpg for explicit reference to Rosetta code. Can we remove this paragraph?
Attachment: Added: programmers_2.jpg
See highlights in attachment programmers_3.jpg for minor grammar error.
Attachment: Added: programmers_3.jpg
See highlights in attachment programmers_4.png for reference to the old XSD version and minor grammar error. (Can we change this graphic to text?)
Attachment: Added: programmers_4.png
See highlights in attachment programmers_5.png for minor grammar error.
Attachment: Added: programmers_5.png
Section: 4.2. Meta-Data and Filters Text: org.jboss.soa.esb.gateway.original.file.name If the message was received via a file-related gateway node, then this element will contain the name of the original file from which the message was sourced. org.jboss.soa.esb.gateway.file The file from which the Message was sourced. This will only be present if this gateway is file- based. Comment: It looks like these file descriptions are for the same file. =================================== Section: 4.3.1. The "ServiceInvoker" Text: From a client's perspective, the Courier interface and its various implementations can be used to interact with services. Comment: From Kevin: '...The Courier interface is a lower level, transport specific, interface. Not sure why it is being referenced in the docs though as people should really be using the service invoker...' So - can we remove references to the Courier interface? =================================== Section: 4.3.4. Updated. The InVM Transport Text (in a note): One may not be able to achieve all of the ACID (Atomicity, Consistency, Isolation, Durability) semantics, particularly when it is used in conjunction with other transactional resources such as databases. This is because of the volatility of the InVM queue. However, the performance benefits of InVM will outweigh this downside in the majority of cases. In situations in which full ACID semantics are required, Red hat recommend that you use one of the other transactional transports, such as the Java Message Service or a database. Comment: This should read "Red Hat recommends" =================================== Section: Examples 4.8 and 4.9 Text: The following example illustrates the declaration of a service which, (without being exposed through a web service end-point), "wishes" to validate the request/response messages: Example 4.8. Enabling the GLOBAL InVM Scope for a Service Example 4.9. Enabling GLOBAL InVM Scope for a Service Comment: The exampple titles refer to GLOBAL InVM Scope, not the service declaration. =================================== Section: 5.3. Content-Based Routing Text: Sometimes it is necessary for the Enterprise Service Bus to dynamically route messages to their sources. Some scenarios in which this might be the case are when the original destination is no longer available, the service has moved or the application simply wants to have more control over where messages go based on either content, time-of-day or other such factors. The Content-Based Routing mechanism within the JBoss ESB can be used to route messages based on arbitrarily complex rules. These rules can be defined in XPath or JBoss Rules notation. Section: Can we also add the new Regex CBR feature to this section. =================================== Section: 7.1. Fail-Over and Load-Balancing Support Text: It is important have redundancy in mind when one is designing mission-critical systems. The JBoss Enterprise Service Bus includes built-in fail-over, load balancing and delayed message re-delivery, all of which will help one build a robust architecture. When one uses a SOA, it is implied that Comment: "When one uses an SOA, it is implied that" =================================== Section: 7.1.3. Protocol Clustering Text: Some Java Message Service providers can be clustered. JBossMessaging is one of these, which is why it was chosen as the JMS provider for the Enterprise Service Bus. When one clusters this JMS, one remove a single point of failure from one's architecture (see the next diagram.) Comment: "When one clusters this JMS, one removes a single point" =================================== Section: Figure 7.3. Example of Protocol Clustering Using JMS Text: One should read the documentation on "Clustering for JBossMessaging," if one wants to enable this functionality. Both JBoss ESB replication and JMS clustering can be used together, as shown in the following illustratin. Comment: "illustation" =================================== Section: 7.1.3. Protocol Clustering Text (in a note) If one is using JMS clustering in this way, one will obviously need to ensure that the configuration is correct. For instance, if one place all of one's ESB services within a JMS cluster, there could be no expected benefit from replication. Comment: "For instance, if one places all" =================================== Section: 7.2. Scheduling of Services Text: JBoss ESB 5.0 supports two types of providers: 1. Bus Providers, which supply messages to action processing pipelines via messaging protocols such as JMS and HTTP. This type is "triggered" by the underlying messaging provider. 2. Schedule Providers, which supply messages to action processing pipelines based on a schedule- driven model. (In other words, where the underlying message delivery mechanism, such as the file system, offers no support for triggering the ESB when messages are available for processing, a scheduler periodically triggers the listener to check for new messages.) Scheduling is new to the JBoss ESB and not all of the listeners have been migrated over to this model yet. JBoss ESB 5.0 offers a <schedule-listener> as well as 2 <schedule-provider> types: <simple-schedule> and <cron-schedule>. The <schedule-listener> is configured with a "composer" class, which is an implementation of the org.jboss.soa.esb.listeners.ScheduledEventMessageComposer interface. Comment: From Kevin: '...It is definitely not new, and has been there for some time. We should remove that sentence from the docs as it is completely meaningless, even if the functionality was new...' =================================== 7.2.5. Updated. Quartz Scheduler Property Configuration See soa-1729 and 1730 Do we also remove this section? =================================== Section: 8.1.1. JBossESB and the Fault Models Text (in a note): You should use care when retransmitting Messages to services. JBossESB currently has no notion of retained results and cannot detect retransmissions within the service, so any duplicate Messages will be delivered to automatically. This may mean that your service receives the same Message multiple times (if, for example, it was the initial service response that became lost rather than the initial request. As such, your service may attempt to perform the same work.) If using re-transmission (either explicitly or through the ServiceInvoker fail-over mechanisms), you will have to deal with multiple requests within your service to ensure it is idempotent. Comment: "so any duplicate Messages will be delivered automatically" =================================== Section: 8.2.4. Component Specifics Text: In this section we shall look at specific components and services within JBossESB. Comment: The sections starting with 8.2.5. Gateways should be subsections. =================================== 9.2. Providers Text: As an example, a provider configuration for JMS would be as follows: <providers> <provider name="JBossMQ"> <property name="connection-factory" value="ConnectionFactory" /> <property name="jndi-URL" value="jnp://localhost:1099" /> <property name="protocol" value="jms" /> <property name="jndi-pkg-prefix" value="com.xyz"/> <bus busid="local-jms"> <property name="destination-type" value="topic" /> <property name="destination-name" value="queue/B" /> <property name="message-selector" value="service='Reconciliation'" <property name="persistent" value="true"/> </bus> </provider> </providers> Comment: Can we replace the reference to JBossMQ with: <provider name="JBossMessaging" connection-factory="ConnectionFactory"> ===================================
We should add a note or table to the section that describes routing actions. There has been confusion over which of these actions do/do not terminate the action pipeline. Th etable should read: Does not terminate the action chain: org.jboss.soa.esb.actions.Aggregator org.jboss.soa.esb.actions.EchoRouter org.jboss.soa.esb.actions.routing.http.HttpRouter org.jboss.soa.esb.actions.routing.JMSRouter org.jboss.soa.esb.actions.routing.email.EmailRouter org.jboss.soa.esb.actions.StaticWiretap org.jboss.soa.esb.actions.routing.email.EmailWiretap Does terminate the action chain: org.jboss.soa.esb.actions.ContentBasedRouter org.jboss.soa.esb.actions.StaticRouter (Kevin mentioned that he thought that some router actions that do not by default terminate the action chain do allow for explicitly enabling that behavior, I don't see that in the javadocs or code.)
Another small comment: 9.9.2. URL Patterns The <.http-gatewar> also supports a urlPattern:: "gatewar"
Link: Added: This issue related SOA-1769
Link: Added: This issue related SOA-1809
Link: Added: This issue related SOA-1810
The SyncServiceInvoker out of the box action is not in the programmers guide. It is in the ESB 4.7 Programmers' Guide: http://www.jboss.org/jbossesb/docs/4.7/manuals/html/ProgrammersGuide.html It looks like it was added to the guide in late Oct 2009. http://jira.jboss.org/jira/browse/JBESB-2919
I've made all requested changes, with two exceptions: I did not convert programmers_4.png to text. I made the changes to the Courier Interface paragraph cited. There are other references to the courier interface in the section but I did not touch these. They are scattered throughout and it would require quite a great deal of rewriting.
Small point to add to the description of the FTP gateway listener: Depending on how the files used to invoke the gateway are created and have content written to them, it is possible for the listener to access a file before its content is completely written. To avoid this timing issue, a temporary file should first be created and fully populated with the intended content. Once the content in the temporary file is complete, it should be moved to the directory/filename configured for the FTP gateway listener.
NOTE: We are not accepting any further QE feedback, unless they are mission-critical issues that would result in data loss. We are closing this stage of the process for this release.