Date of First Response: 2008-10-24 04:56:19 project_key: SOA Let's collect all comments for Darrin for the ./docs/esb/Services_Guide.pdf in this JIRA
Security: Added: Public
Got the fixes for SOA-978 from https://svn.corp.jboss.com/repos/soa/trunk/build-tools/docs/esb/
Services guide in the SVN repository still has SOA-978 present.
Page 2, foot note 1: The link http://1www.w3.org/1TR/12003/1WD-ws-arch-20030808/1#id2617708 is invalid. It doesn't work even after removing "1" from "1www".
Btw. by page I mean page numbers as written in the document, not real sheets which are shown by the PDF viewer.
Image on the 2nd page is really ugly - it's quality is very bad.
"1.1.6. The Registry and JBossESB The registry plays a central role within JBoss SOA." I think that both title and paragraph should refer to the same thing (e.g. JBoss SOA, not JBoss ESB).
On page 5, example of registry configuration should be formatted better. There are extra empty lines.
Moreover, the registry now contains interceptors as well. So this should be included into the example - see jboss-as/server/produciton/deploy/jbossesb.sar/jbossesb-properties.xml. Anything about caching interceptor SHOULD NOT be there since it doesn't work currently.
Page 8, numbered list, 2. "The configuration of jUDDI itself in esb.juddi.xml." - verb is missing, I suggest "itself is in".
Page 11, "They can all can connect to the same database" - doubled "can"
3.3. RMI using the juddi.war or jbossesb.sar The JBoss SOA includes juddi.war in the jUDDI-registry directory. When deployed this brings up the regular webservices but also an RMI service. You also need to deploy a datasource which points to your jUDDI database. An example file is supplied for MySQL. This is quite strange, there are two juddi.war files in the SOA-P. First in deploy/jbossesb.sar/ and second in deploy/juddi-service.sar. Only the first contains the configuration shown in the examples later in the text. They are definitely not in the jUDDI-registry directory. So it would be good to correct the directory name.
5.1. Scout and jUDDI pitfalls • Make sure to put our version of the jaxr-api-1.0.jar, scout-0.7rc2-embedded.jar and the juddi-embedded.jar first. The versions of these libraries that are included with the JBoss Application Server are incompatiable. This should get resolved in future release of JBoss Application Server. I did not find any jaxr*jar or juddi-embedded.jar in SOA-P, so what is that thing reffered as "our version"? I only found scout-1.0rc2.aop.jar or scout.jar (version 1.0rc1).
Page 23, another reference to non-existing jUDDI-registry directory: • Make sure to read the README in the jUDDI-registry directory, for instructions regarding prepopulating your own jUDDI database.
Page 23, section 5.2 More Information Link needs update: *The JBoss jUDDI wiki http://www.jboss.org/community/docs/DOC-11217
Page 27, section 7.1 Introduction * The BusinessRuleProcessor action class The class is in fact BusinessRulesProcessor (note the extra "s" in Rules)
Starting secion 7.1. EsbMessage and ESBMessage are mentioned several times. We should unify the upper/lowercase style.
Page 33, Figure 7.1. is invalid, the structure of the archive has changed: META-INF/ META-INF/MANIFEST.MF META-INF/deployment.xml META-INF/jboss-esb.xml org/ org/jboss/ org/jboss/soa/ org/jboss/soa/esb/ org/jboss/soa/esb/samples/ org/jboss/soa/esb/samples/quickstart/ org/jboss/soa/esb/samples/quickstart/businessrules/ org/jboss/soa/esb/samples/quickstart/businessrules/dvdstore/ org/jboss/soa/esb/samples/quickstart/businessrules/dvdstore/Customer.class org/jboss/soa/esb/samples/quickstart/businessrules/dvdstore/OrderHeader.class org/jboss/soa/esb/samples/quickstart/businessrules/dvdstore/OrderItem.class org/jboss/soa/esb/samples/quickstart/businessrules/test/ org/jboss/soa/esb/samples/quickstart/businessrules/test/SendJMSMessage.class org/jboss/soa/esb/samples/quickstart/businessrules/ReviewMessage.class org/jboss/soa/esb/samples/quickstart/businessrules/UpdateCustomerStatus.class MyBusinessRules.drl MyBusinessRulesDiscount.drl MyRoutingRules.drl jbm-queue-service.xml map_order_components.groovy smooks-res.xml
Page 39, "3. xpathGreaterThan" The rule is in fact called "xpathLessThan".
Page 39, " Figure 1 shows a service" It refers to Figure 9.2. so the "1" should be changed to "9.2"
Page 40, section CBR Action Configuration Attributes In the following table, the text gets out of the page. Probably because the line should be broken before "org".
Page 45, Figure 10.1 is useless because the texts in the image can't be read. It has poor quality.
I just wanted to remind that the last page of the document is 46 and the rest is missing.
Why it is not possible to click on the links in the document?
I'm done with the review.
outstanding items * not sure what the issue is with the image on page 2 * "Moreover, the registry now contains interceptors as well. So this should be included into the example - see jboss-as/server/produciton/deploy/jbossesb.sar/jbossesb-properties.xml. Anything about caching interceptor SHOULD NOT be there since it doesn't work currently." This needs to be fixed in ESB Services Guide source document * "3.3. RMI using the juddi.war or jbossesb.sar The JBoss SOA includes juddi.war in the jUDDI-registry directory. When deployed this brings up the regular webservices but also an RMI service. You also need to deploy a datasource which points to your jUDDI database. An example file is supplied for MySQL. This is quite strange, there are two juddi.war files in the SOA-P. First in deploy/jbossesb.sar/ and second in deploy/juddi-service.sar. Only the first contains the configuration shown in the examples later in the text. They are definitely not in the jUDDI-registry directory. So it would be good to correct the directory name." This needs to be fixed in ESB Services Guide source document * "5.1. Scout and jUDDI pitfalls • Make sure to put our version of the jaxr-api-1.0.jar, scout-0.7rc2-embedded.jar and the juddi-embedded.jar first. The versions of these libraries that are included with the JBoss Application Server are incompatiable. This should get resolved in future release of JBoss Application Server. I did not find any jaxr*jar or juddi-embedded.jar in SOA-P, so what is that thing reffered as "our version"? I only found scout-1.0rc2.aop.jar or scout.jar (version 1.0rc1). " This needs to be fixed in ESB Services Guide source document *"Page 23, another reference to non-existing jUDDI-registry directory: • Make sure to read the README in the jUDDI-registry directory, for instructions regarding prepopulating your own jUDDI database. " This needs to be fixed in ESB Services Guide source document *"Page 39, "3. xpathGreaterThan" The rule is in fact called "xpathLessThan"." I assume you are referring to the "xpathLowerThan" rule *"Page 45, Figure 10.1 is useless because the texts in the image can't be read. It has poor quality." We are constrained by a maximum image width of 430px, this diagram has to be completely re-thought * "Why it is not possible to click on the links in the document?" Are there any particular links you were having problems with? What PDF viewer, what OS? Versions?
More comments Section 5.1 Make sure to put our version of the jaxr-api-1.0.jar, scout-0.7rc2-embedded.jar and the juddi-embedded.jar first. The versions of these libraries that are included with the JBoss Application Server are incompatiable. This should get resolved in future release of JBoss Application Server. (I don't think that the paragraph is at all applicable to 4.3. It should be deleted.) Section 6.1 (Rules Service) (This section of the guide refers to Rule "facts," but does not define this term in the context of JBoss Rules. Why don't we add some brief definitions such as: Fact ( application data ) Working Memory ( stateful collection of facts ) Production Memory ( the rules ) Inference Engine ( JBoss Rules & RETE ) Agenda ( conflict resolution ) Salience ( priority ) REF: http://www.cooug.org/brsig/event_details/presentations/2006_June_20_DRules.pdf 7.1. Introduction (Rules Services) When a message gets send to the BusinessRulesProcessor a rule set executes over the objects in the message and updates either of those objects or the message. ("sent") 7.3. Rule Service Consumers The consumer of a rule service has little to worry about. There is no need for the consumer to creating rulebases or working memories, inserting facts or firing the rules. ("to be creating") 7.4. Configuration A dsl and dslr (domain specific language) files ("dsl and dslr (domain specific language) files") 9.1. Introduction (Content Based Routing) When a message gets send to the CBR, a certain rule set will evaluate the message content and return a set of Service destinations. ("sent") 9.2. Three Different Routing Action Classes In this case the message is simply filter out. ("filtered") Figure 2 shows an example where the MessageType is used to determine to which destination the Message is going to be send. ("sent") 9.4. XPath Domain Specific Language 2. xpathEquals <element>, <value> : yields true if the element is found and it's value equals the value. 3. xpathGreaterThan <element>, <value> : yields true if the element is found and it's value is greater than the value. 4. xpathLessThan <element>, <value> : yields true if the element is found and it's value is lower then the value. (its, not it's) 9.5. Configuration Now that we have seen all the individual pieces how does it all tie together? It basically all comes down to configuration at this point, which is all done in your jboss-esb.xml. (Now that we have seen all the individual pieces, how does it all tie together? It all comes down to configuration at this point, which is all done in your jboss-esb.xml.) Each ESBMessage is passed on to in this case the ContentBasedRouter action class which is loaded with a certain rule set. (Each ESBMessage is passed on to the ContentBasedRouter action class which is loaded with a certain rule set.) It uses the rule set JbossESBRules.drl, which matches two destinations, name 'xml-destination' and 'serializeddestination'. (It uses the rule set JbossESBRules.drl, which matches two destinations, named 'xml-destination' and 'serializeddestination'.) Table 9.2. CBR Action Configuration Properties Optional property which tells the RuleService to use a stateful session where facts will be remembered between invokations. ("invocations") 9.8. RuleAgent We should not have the same URL duplicated in two separate footnotes on the same page. One reference to the URL in a footnote is sufficient. 10.1. Introduction (Content Based Routing with Smooks) An example of this might be a huge order message with thousands/millions of order items per message. (Is this realistic? Millions of order items in one message?) In this case, we're just binding the data into HahMaps. ("HashMaps") Figure 10.1. Message Splitting - The text in this image is not clear enough to be read. Resource configurations #1 and #2 are there to bind data from the source message into Java Object in the Smooks bean context. In this case, we're just binding the data into HahMaps. The Map being populated in configuration #2 is recreated and repopulated for every order item as the message is being filtered. The populated Java Objects (from resources #1 and #2) are use to populate a FreeMarker template (resource #4), which gets applied on every order item, with the result of the templating operation being output to a FileResourceStream (resource #3). The FileResourceStream (resource #3) also gets applied on every order item, managing the file output for the split messages. (Where are these numbers defined? There are no numbers in the figure.) Chapter 11 - Message Transformation The JBoss ESB supports message data transformation through several of mechanisms. ("several mechanisms") 12.3. Creation and Deployment of a Process Definition There are three mechanisms that you can use to deploy a process defination. ("definition") (You can only deploy if the server is configured to accept jBPM process deployments. See the Admin Guide for more details.)
12.5.2. ESBActionHandler under normal processing the signal will be send by the JBossESB callback Service. ("sent") 12.5.3. jBPM to ESB Exception Handling Only if the call was made from the EsbActionHandler it makes sense to report back the exception to jBPM. ("does it make sense") 12.5.4. Scenerio 1: Time-out it maybe that you want to limit how long you want to wait ("may be") 13.1. Orchestrating Web Services JBossESB provides WS-BPEL support via its Web Service components. For details on these components and how to configure and use them, see the Message Action Guide. (We don't have a message action guide. In which of the SOA-P docs is this information?) 13.2. Orchestration Diagram (One of these four footnotes is sufficient.) 1 http://www.active-endpoints.com/ 2 http://www.active-endpoints.com/ 3 http://www.active-endpoints.com/ 4 http://www.active-endpoints.com/ 13.3. Process Deployment and Instantiation In the previous paragraph we create the process definition and we quietly assumed we had an instance of it to explain the process flow. But now that we have created the processdefinition.xml, we can deploy it to jBPM using the IDE, ant or the jbpm-console (as explained in Chapter 1). (That's chapter 12. ;-) Chapter 14 - The Message Store In JBossESB 4.2 the Message Store is also used for storing messages that need to be redelivered in the event of failures. (This is release 4.3.)
15.2. Authentication When a service needs to call another services. and that service requires authentication, another authentication process will be performed. ("needs to call another service") If the ESB detects that a Message has a SecurityContext check that the SecurityContext is still valid and if so re-authentication is not performed. ("a SecurityContext, it checks") 15.3. JBossESB SecurityContext This value can be specified globally in jbossesb-properties.xml of overridden per-service by specifying the value in jboss-esb.xml. ("or overridden per-service") 15.7. SecurityService The default implementation is based on JAAS, but this can be customized by implementing the above interface and configuring the custom SecurityService be used in jbossesb-properties.xml. ("to be used")
Changes done as per: https://jira.jboss.org/jira/browse/SOA-972?focusedCommentId=12436088#action_12436088
Changes done as per https://jira.jboss.org/jira/browse/SOA-972?focusedCommentId=12435917#action_12435917
resolved by mistake
Link: Added: This issue related JBESB-2260
With the exception of the confusing jUDDI examples in chapter 3 all these items have been resolved. I created SOA-1107 for clarification of the jUDDI items.
Assigning to QE to verify that the change is (also) in the 4.3 CP01 docs.
* This is missing from the example on page 5, see jboss-as/server/produciton/deploy/jbossesb.sar/jbossesb-properties.xml: <property name="org.jboss.soa.esb.registry.interceptors" value="org.jboss.internal.soa.esb.services.registry.InVMRegistryInterceptor"/> * Page 38, "??? shows an example" * Page 39, "JbossESBRules.drl", note the lowercase "b" * 12.5.2 ESBActionHandler, after discussion with Len, we suggest the following formulation "under normal procesing, the JBossESB callback Service will send the signal" What about the outstanding issues? I don't feel like closing this issue until they are fixed or reported in a separate JIRA...
Link: Added: This issue is duplicated by SOA-1174
The only outstanding item was reported in SOA-1107, re comment of 5th January SOA-1174 should be the QE JIRA for this doc in 4.3.CP01. If the issues raised on this JIRA have been resolved then please close it and add all further feedback to SOA-1174
SOA-1174 is tracking these 4.3 CP01 doc changes Items from SOA-972 * This is missing from the example on page 5, see jboss-as/server/produciton/deploy/jbossesb.sar/jbossesb-properties.xml: <property name="org.jboss.soa.esb.registry.interceptors" value="org.jboss.internal.soa.esb.services.registry.InVMRegistryInterceptor"/> * Page 38, "??? shows an example" * Page 39, "JbossESBRules.drl", note the lowercase "b" * 12.5.2 ESBActionHandler, after discussion with Len, we suggest the following formulation "under normal procesing, the JBossESB callback Service will send the signal" These have been resolved. -------------------------------- SOA-1107 is tracking the other (UDDI example) doc change. -------------------------------- We should close this (SOA-972) doc review JIRA as the live issues are tracked in these ^ JIRAs. Closing as a duplicate of these issues.
See SOA-1107, SOA-1174