On part 2, I have now seen that NotifyEmail, NotifyJMS, NotifySQLTable, NotifyTopics, NotifyUtils have been defined in source code. None of these are documented (neither in their source code nor in the Message Action Guide) and neither do they appear in the document we know and love.
I believe that is because we didn't really finish the testing. Perhaps you could build up some quickstarts that demonstrate all of these (and tests them) and then contribute something back to the docs.
Please feel free to setup a Jira and attach your changes (quickstarts & docs). That would be a welcome addition.
Any comment on the first part of my original question?
If the current action class ends normally (no Exception is thrown), and you specified an OK notification class, then it will be invoked with the message returned by the corresponding action class.
If an Exception was thrown by the action class, and you specified an error notification class, then that 'exception handling' class will be invoked
Thank you for your reply. But how is the current action class defined?
In all the examples I have seen in the quickstarts, Notifier actions are mixed in with quickstarts, sonething like this: A, B, C, N1, D, N2 where A,B,C,D are non-notifier actions within a service, and N are notifier action instances which both define NotificationLists of type OK and type error.
I now send a message to that service. Action A is executed and returns normally, action B executes and throws an exception. What happens? What is the current action class in this case and how does it relate to the two notifiewrs N1 and N2 in the chain?
I have looked in the Programmer's Guide, and there is some mention of error handling in action chains(section "Error handling when processing messages"), but it does not mention the interaction with Notifiers. MessageActionGuide, where the Notifier class is documented, does not mention it either.
Any help appreciated.
That should read, "Notifier actions are mixed in with other actions within a service"
Let's try an example with an explanation:
<action name="notificationAction" class="org.jboss.soa.esb.actions.Notifier"> <property name="okMethod" value="notifyOK" /> <property name="notification-details"> <NotificationList type="ok"> <target class="NotifyConsole"/> <target class="NotifyFiles"> <file append="false" URI="@results.dir@/goodresults.log"/> </target> </NotificationList> <NotificationList type="err"> <target class="NotifyConsole"/> <target class="NotifyFiles"> <file append="false" URI="@results.dir@/badresults.log"/> </target> </NotificationList> </property> </action>
If there is an exception thrown by an action in the chain/pipeline then the "err" path will be taken for the notification action.
If there are no exceptions thrown by any action in the chain/pipeline then the "ok" path will be taken for the notification action.
At least this is how I understand it to work. Another team member who has explored it more can confirm or correct these ideas.
The action pipeline works in two stages, normal processing followed by outcome processing.
In the first stage the pipeline calls the process method(s) on each action (by default it is called process) in sequence until the end of the pipeline has been reached or an error occurs.
At this point the pipeline reverses (the second stage) and calls the outcome method on each preceding action (by default it is processException or processSuccess). It starts with the current action (the final one on success or the one which raised the exception) and travels backwards until it has reached the start of the pipeline.
The Notifier is an action which does no processing of the message during the first stage (it is a no-op) but sends the specified notifications during the second stage.
OK. Thank you. I think i've got it. So, the way I see it now:
When executing an action chain within a service, execution may proceed normally (without an exception being raised at any action in the chain) or exceptionally (with an exception being raised at one action in the chain).
The Notifier action can be used to send a notification to one or more locations, depending on whether action chain execution is normal or exceptional. Locations where notifications can be sent are console, file, queue, email, SQL table (and a few others) - all of which can be used to store the notifications sent.
To enable notifications, the Notifier action can be placed anywhere within the action chain, and is used to specify (i) the list of locations (NotificationList) to be notified upon normal execution, and (ii) the list of locations to be notified upon exceptional execution. Locations to be notified upon normal execution are included in NotificationList of type "OK", and locations to be notified upon exceptional execution are included in NotificationList of type "err". Placing multiple Notifier actions is permitted and will result in notification being sent to each location in the recipient list.
And some other details left out concerning method naming...