Hide Forgot
Date of First Response: 2009-12-03 22:00:04 project_key: SOA Len, please undertake a QE Review of the SOA-P ESB Services Guide and alert us to any material that is missing, erroneous or outdated. Thanks! Draft doc at: http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_SOA_Platform/5.0.0/html/ESB_Services_Guide/
Attachment: Added: Services_Guide.pdf
Attachment: Removed: Services_Guide.pdf
The chapter on the registry has to change - the jUDDI URLs and code are all v2-specific, we need to change the examples and text to match jUDDI v3.
Or maybe we need to have both version documented. Version 2 is still in the configurations inherited from EAP5.
4.5.1 ESB Notifier At the end of the section, list item esb - I suggest changing it to read like this: This attribute is optional. It is the name of the variable in the EsbMessage. - (The name can be an MVEL-type expression.) + The name can be an MVEL-type expression. By default, the variable is set as a named parameter on the body of the EsbMessage. + I.e. the attribute value 'TokenName' in Example 4.8. is equal to 'body.TokenName'. + A special value 'BODY_CONTENT' addresses the body directly. If one should decide to omit the esb attribute, the value of the bpm attribute is used instead.
I'm sorry if the following comments sound rude, I tried to be specific and go a subject directly... Section 1.1.1. extra dot: "e.-business directory." Section 1.1.1.6, Note should mention that inherited configurations (web, standard) Section 1.2, resource for jUDDIv3 configuration - jboss-as/server/production/deployers/esb.deployer/jbossesb-properties.xml Example 1.2 is invalid for jUDDIv3 even thou the surrounding text mentions v3. I suppose this chapter is going to be reworked. Section 1.3.2, footnote 2, I don't think that "In this case the "component" being referred to is actually the Java Virtual Machine." JVM cannot be embedded in the jUDDI registry. In fact, I don't understand what the first sentence of this Section is trying to express. We can say, that all components (ESB, WS...) of the server that has any relation to a registry, can use the same registry in the server. Then we can say that multiple instances of SOA-P can share the same registry via shared DB (the second sentence). Section 1.3.4, no file jbossesb.sar/META-INF/uddi.xml exists in the server. Example 1.7, invalid configuration for jUDDIv3 Example 1.8, I suggest to verify that this approach is still valid with jUDDIv3. Section 1.4.1, jbossesb-properties.xml should be listed with the whole path - jboss-as/server/*/deployers/esb.deployer/jbossesb-properties.xml. The same applies for other files as well. META-INF/uddi.xml is not present in the SOA-P. Section 2.1.1, "However, there is no way to specify multiple rule files in jboss-esb.xml." - this is not true. It is not possible to specify multiple rule files for a single BusinessRuleProcessor action. There can be multiple rule files - see bpm_orchestration4 QS. Section 2.2.1, I don't understand how the integration is done using "The ESBMessage". I think this should read something like - "The ESB Message, which is going to be inserted into the rule engine' working memory". Please make sure there is a space between ESB and Message, there is no class ESBMessage nor it is a word. The last thing applies to Section 2.2.2 as well. Section 2.2.3, "For all the subsequent messages bar the final one:", bar -> but Section 2.2.3, "In Enterprise Service Bus 4.6 and prior releases, the "continue" functionality for state-ful rule execution did not dispose of working memories if the value of the property was false or it was absent. " -> "In Enterprise Service Bus 4.6 and prior releases, the "continue" functionality for >>the<< >>stateful<< rule execution did not dispose >>the working memory<< if the value of the property was false or it was absent. " Section 2.2.4, "A DSL or DSLR (Domain Specific Language) file", or -> and Example 3.4 seems strange to me. This is how namespaces work for me: <property name="destinations"><namespace prefix="ord" uri="http://org.jboss.soa.esb/Order" /> There is no namespaces property and no route-to tag. Section 3.2.1, I don't see any reason for quotes here: provider "engine." Section 3.2.3, first occurence of 'EsbMessage' (note lowercase 's' and 'b'). I suggest unifying this through the whole document set. IMHO, we should call it 'ESB Message'. There is no class or datatype EsbMessage nor ESBMessage. Section 3.2.4.1 must contain an example of how to define a namespace in the rule. It is not obvious nor intuitive. Section 3.2.4.4, title "State-ful Rules" - > "Stateful", we use 'Stateful' word in JBoss community/world/user goups on daily basis - note stateful EJBs. There is no reason to invent a new way. Section 3.2.4.7, "The functionality of the Business Rule Processor (BRP) is identical to that of the Content-Based Router, but it, itself, does not do any routing." seems like an overengineered sentence to me. What about "The Business Rule Processor (BRP) is functional equivalent of the Content-Based Router except for the routing part."
text: 1.2.1. Introduction There is a section in the jbossesb-properties.xml file, entitled registry. The following properties can be used to configure this section: In the file ${SOA_ROOT}/server/${CONFIG}/deploy/jbossesb.sar/jbossesb- properties.xml there is section called registry which is used, as its name implies, to configure the registry. comment: The files are now in: find . -name jbossesb-properties.xml -print ./all/deployers/esb.deployer/jbossesb-properties.xml ./production/deployers/esb.deployer/jbossesb-properties.xml ./default/deployers/esb.deployer/jbossesb-properties.xml
Assigning back to David - the updated version of the doc is not here: http://documentation-stage.bne.redhat.com/docs/en-US/index.html
Link: Added: This issue related SOA-1693
Martin and Len, I have acted upon most of your feedback above. However, we will need subject matter experts to provide jUDDI 3 examples. I have provided comments below on those things that I have not changed. My responses are in CAPITALS. Example 1.2 is invalid for jUDDIv3 even thou the surrounding text mentions v3. I suppose this chapter is going to be reworked. (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) Example 1.7, invalid configuration for jUDDIv3 (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) Example 1.8, I suggest to verify that this approach is still valid with jUDDIv3. (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) Section 2.2.3, "For all the subsequent messages bar the final one:", bar -> but THIS IS CORRECT ENGLISH. NOT CHANGED. Example 3.4 seems strange to me. This is how namespaces work for me: <property name="destinations"><namespace prefix="ord" uri="http://org.jboss.soa.esb/Order" /> There is no namespaces property and no route-to tag. (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) Section 3.2.1, I don't see any reason for quotes here: provider "engine." QUOTATION MARKS ARE BECAUSE IT IS FIGURATIVE/ANALAGOUS LANGUAGE. IT IS NOT LITERALLY AN ENGINE IN THE MECHANICAL SENSE. :-) Section 3.2.4.1 must contain an example of how to define a namespace in the rule. It is not obvious nor intuitive. (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) Section 3.2.4.4, title "State-ful Rules" - > "Stateful", we use 'Stateful' word in JBoss community/world/user goups on daily basis - note stateful EJBs. There is no reason to invent a new way. CHANGED THIS FOR THE MOMENT BUT I AM NOT HAPPY WITH IT AS "STATEFUL" IS NOT A REAL WORD. WE WILL DISCUSS THIS WITHIN THE DOCS TEAM TO COME UP WITH A STANDARDISED WAY OF DEALING WITH THIS TERM ACROSS ALL RED HAT DOCS.
We need quite a lot of info from subject matter experts for this one.
4.5.1. ESBNotifier contains definition of globalProcessScope parameter and process-scope parameter that refers to globalProcessScope. 4.5.2. ESBActionHandler contains definition of process-scope parameter that refers to globalProcessScope but the globalProcessScope is not defined - I think it is missing for this action.
Organization of the 1st chapter is awkward - the content at the start of the chapter is at 1 n.n.n.n level - can we make this one level higher? 1.1. What is the Registry? 1.1.1. Introduction The JBoss SOA-P Registry provides applications and businesses with a central point at which information about services can be stored. The Registry is expected to provide both the same level of information and the same breadth of services as does a conventional "marketplace." Ideally, a registry should also facilitate the automatic discovery and execution of electronic commerce by providing a dynamic environment for business transactions. Therefore, a registry is more than a mere "e. business directory." It is a fundamental component of the Service-Oriented Architecture's infrastructure. 1.1.1.1. Why Does One Need It?
Wording in section #: 1.1.1.6. The Registry and the JBoss Service-Oriented Architecture Platform (in the note): The JBoss Enterprise Service Bus releases prior to, and including, Version 4.6, utilised a release of jUDDI release that implemented Version 2.0 of the UDDI specification for backing registries. =========== "release of jUDDI release"?
I think the following is correct - need to re-confirm the jUDDI URLs and URIs. 1) Example 1.2 is invalid for jUDDIv3 even thou the surrounding text mentions v3. I suppose this chapter is going to be reworked. (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) Jan 15 Update: Replace the text in example 1.2 with this: -------------------------- SOAP queryManagerURI http://localhost:8080/juddiv3/services/inquiry?wsdl lifeCycleManagerURI http://localhost:8080/juddiv3/services/publish?wsdl transportClass org.apache.ws.scout.transport.AxisTransport RMI queryManagerURI jnp://localhost:1099/InquiryService?org.apache.juddi.registry.rmi.Inquiry#inquire lifeCycleManagerURI jnp://localhost:1099/PublishService?org.apache.juddi.registry.rmi.Publish#publish transportClass org.apache.ws.scout.transport.RMITransport Local queryManagerURI org.apache.juddi.registry.local.InquiryService#inquire lifeCycleManagerURI org.apache.juddi.registry.local.PublishService#publish transportClass org.apache.ws.scout.transport.LocalTransport ==================================================================== 2) Example 1.7, invalid configuration for jUDDIv3 (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) <properties name="registry"> <property name="org.jboss.soa.esb.registry.implementationClass" value="org.jboss.internal.soa.esb.services.registry.JAXRRegistryImpl"/> <property name="org.jboss.soa.esb.registry.factoryClass" value="org.apache.ws.scout.registry.ConnectionFactoryImpl"/> <property name="org.jboss.soa.esb.registry.queryManagerURI" value="jnp://localhost:1099/InquiryService?org.apache.juddi.registry.rmi.Inquiry#inquire"/> <property name="org.jboss.soa.esb.registry.lifeCycleManagerURI" value="jnp://localhost:1099/PublishService?org.apache.juddi.registry.rmi.Publish#publish"/> <property name="org.jboss.soa.esb.registry.user" value="jbossesb"/> <property name="org.jboss.soa.esb.registry.password" value="password"/> <property name="org.jboss.soa.esb.scout.proxy.transportClass" value="org.apache.ws.scout.transport.RMITransport"/> </properties> ==================================================================== 3) Example 1.8, I suggest to verify that this approach is still valid with jUDDIv3. (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) Jan 15 Update: This is still correct. ==================================================================== 4) Section 2.2.3, "For all the subsequent messages bar the final one:", bar -> but THIS IS CORRECT ENGLISH. NOT CHANGED. Jan 15 Update: "Barring" sounds better, but OK. ==================================================================== 5) Example 3.4 seems strange to me. This is how namespaces work for me: <property name="destinations"><namespace prefix="ord" uri="http://org.jboss.soa.esb/Order" /> There is no namespaces property and no route-to tag. (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) Jan 15 Update: Here's the text from the fun_cbr quickstart - which does work - let's just use this: <!-- ESB XPath CBR Service --> <service category="Fun_CBRServices_ESB" name="XPath_FunCBRService_ESB" description="ESB Listener - for the native clients" invmScope="GLOBAL"> <listeners> <!-- Gateway --> <jms-listener name="TheGateway" busidref="xpathQuickstartGwChannel" is-gateway="true" /> </listeners> <actions mep="OneWay"> <action class="org.jboss.soa.esb.actions.ContentBasedRouter" name="ContentBasedRouter"> <property name="cbrAlias" value="XPath"/> <property name="destinations"> <namespace prefix="ord" uri="http://org.jboss.soa.esb/Order" /> <route-to service-category="BlueTeam" service-name="GoBlue" expression="/ord:Order[@statusCode='0']" /> <route-to service-category="RedTeam" service-name="GoRed" expression="/ord:Order[@statusCode='1']" /> <route-to service-category="GreenTeam" service-name="GoGreen" expression="/ord:Order[@statusCode='2']" /> </property> </action> </actions> </service> ==================================================================== 6) Section 3.2.1, I don't see any reason for quotes here: provider "engine." QUOTATION MARKS ARE BECAUSE IT IS FIGURATIVE/ANALAGOUS LANGUAGE. IT IS NOT LITERALLY AN ENGINE IN THE MECHANICAL SENSE. :-) Jan 15 Update: OK by me! ;-) ==================================================================== 7) Section 3.2.4.1 must contain an example of how to define a namespace in the rule. It is not obvious nor intuitive. (NEED INFORMATION FROM SUBJECT MATTER EXPERTS UPSTREAM.) Jan 15 Update: Here's a good example - also from a quickstart: [ldimaggi@ldimaggi quickstarts]$ pwd /opt/local/50_ER7_Jan14/jboss-soa-p.5.0.0/jboss-as/samples/quickstarts [ldimaggi@ldimaggi quickstarts]$ grep -ir "use namespaces" * fun_cbr/FunCBRRules-XPath.drl: xpathEquals expr "/order:Order/@statusCode", "0" use namespaces "order=http://org.jboss.soa.esb/Order" fun_cbr/FunCBRRules-XPath.drl: xpathEquals expr "/order:Order/@statusCode", "1" use namespaces "order=http://org.jboss.soa.esb/Order" fun_cbr/FunCBRRules-XPath.drl: xpathEquals expr "/order:Order/@statusCode", "2" use namespaces "order=http://org.jboss.soa.esb/Order" ==================================================================== 8) Section 3.2.4.4, title "State-ful Rules" - > "Stateful", we use 'Stateful' word in JBoss community/world/user goups on daily basis - note stateful EJBs. There is no reason to invent a new way. CHANGED THIS FOR THE MOMENT BUT I AM NOT HAPPY WITH IT AS "STATEFUL" IS NOT A REAL WORD. WE WILL DISCUSS THIS WITHIN THE DOCS TEAM TO COME UP WITH A STANDARDISED WAY OF DEALING WITH THIS TERM ACROSS ALL RED HAT DOCS. Jan 15 Update: I'd leave this as "stateful."
Section 3.3. Content-Based Routing Using Smooks Comment: We need to add a note that says: There is no native support for Freemarker inside the ESB (no action, no gateway, etc), any use of Freemarker must be in the context of Smooks. Comment: All the graphics in this section are unreadable. ------------------------------------- Section: 2.2.2. Rule Set Creation Text: One can create a rule set by using Red Hat Developer Studio. Comment: Should be "JBoss Developer Studio" ------------------------------------- Section: 2.2.1. Introduction Text: This the ESB Message, which is going to be inserted into the Rules Engine's working memory. ------------------------------------- Section: 3.2.4.1. XPath and Namespaces Text: The namespace-aware statements differ from the others in that it is a requirement thatthe extra expr Comment: "thatthe" ------------------------------------- Section: Figure 3.4. Message Splitting Text: ??? shows how to perform the by-order-item splitting operation Comment: Why the question marks?
Page 40 Note This release of the JBoss Service-Oriented Architecture Platform includes Smooks v1.1. Comment: We're shipping version 1.2.4
Section - text just under figure 4.4 Text: Directly from JBoss Developer Studio, by clicking on the Deploy Process Archive button. This is visible in the "Deployment" view; Comment: We should remind the users about having to configure the upload servlet used by the deployer (See SOA-1586) ---------------------------------------------------------- Section: 5.1. Orchestrating Web Services The reference to the webservice_bpel quickstart should be removed - we are not shipping the quickstart in SOA-P 5.0
Section: 3.3. Content-Based Routing Using Smooks Text: This release of the JBoss Service-Oriented Architecture Platform includes Smooks v1.1. This means that the split described above can be undertaken without defining the binding configurations that were demonstrated in Resources One and Two.) For details on how to do this, one needs to refer to the section entitled "FreeMarker Transforms using Node Models" in the Smooks User Guide . That document can be found at http://docs.codehaus.org/display/MILYN/Smooks+User+Guide . Comment: (Thanks to Tom for supplying this): The Node Model Templating functionality (templating without having to define a Java Model) is available in Smooks v1.1+. Sounds like the "split" config talked about in the comment is using a fully defined Java object model, which is fine, and the comment is just trying to tell the user that they also have this other option of using the Node Model functionality, hence doing away with the need to define a Java Object model. I think I'd just remove the reference to Smooks versions in the first comment and say.... "The split described above can be undertaken without defining the binding configurations that were demonstrated in Resources One and Two.) For details on how to do this see the section on <insert link to section on Node Models>" That sound OK? T.
Link: Added: This issue related JBQA-3012
All tasks completed apart from the issue with the graphics, which we are investigating.
One more text error - see attached screen shot
Attachment: Added: Screenshot-3.png
Fixed it.
The description of the http-gateway is incomplete - we need to add these subjects: http://community.jboss.org/wiki/HTTPGateway#Response_Handling http://community.jboss.org/wiki/HTTPGateway#Asynchronous_Responses http://community.jboss.org/wiki/HTTPGateway#Synchronous_Responses http://community.jboss.org/wiki/HTTPGateway#Response_Information http://community.jboss.org/wiki/HTTPGateway#Payload_Encoding http://community.jboss.org/wiki/HTTPGateway#Exception_to_HTTP_Status_Code_Mapping http://community.jboss.org/wiki/HTTPGateway#Response_Timeout http://community.jboss.org/wiki/HTTPGateway#Security http://community.jboss.org/wiki/HTTPGateway#Protected_Methods__Allowed_User_Roles http://community.jboss.org/wiki/HTTPGateway#Authentication_Method_and_Security_Domain http://community.jboss.org/wiki/HTTPGateway#Transport_Guarantee http://community.jboss.org/wiki/HTTPGateway#SSLHTTPS http://community.jboss.org/wiki/HTTPGateway#Integration_with_ESB_Security (This one is not yet complete)
That information was added to the Programmers' Guide, not the Services Guide. 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. Thanks,
Link: Added: This issue is a dependency of SOA-1932