Package com.flyingspaniel.nava.callback

Interface Summary

Interface	Description
Callback<IN,OUT>	Interface for a javascript/node.js like callback (and chain) Warning: The generics are mainly for documentation and decoration.
Callback.ProducesMore<IN,OUT,MORE>	Implement this (rare) if your callback produces "more" than a single output This will be used by a single followup callback as its more...
Callback.ProducesMultiple<IN,OUT>	Implement this if your callback produces multiple single outputs to be used by multiple followup callbacks as their IN argument.

Class Summary

Class	Description
AbstractCallback<IN,OUT>	Abstract implementation of a Callback, which also implements Emit.IListener. Subclasses need only implement callback().
AbstractCallback.Canned<IN,OUT>	Inner class mainly for tests, allows for canned results
AbstractCallback.NOP<IN>	Class that does nothing (just calls failFast), then returns input unchanged
CallbackAnd	Immutable Utility classes/data-structures to group a Callback with associated inputs, outputs, or exceptions Input and Output are package visible, and are used internally by Callbacks and/or CallbackExecutor
CallbackExecutor	Class to execute callbacks, and manage their links, using two ExecutorServices
Callbacks	Utilities for dealing with Callbacks

Exception Summary

Exception	Description
CallbackAnd.Xception	Represents an Exception thrown by a Callback Unlike the two others this is public cause users might want to catch it

Author:

Morgan Conrad

Code for using and linking together callbacks, inspired by node.js / javascript Due to language differences (this isn't written for Java 8) it is only a quasi-port. Though many of the classes are generified as aids to documentation, ultimately there are unchecked casts involved, so if you listen for a String but get a Date bad things will happen.

Typical Usage:

1. Implement Callback, perhaps by extending AbstractCallback. Usually the more... part is ignored.
2. You must test for an incoming Exception. And easy way is to call failFast() or failSlow()
3. If your callback returns lots of "optional extra" information, (rare) extend Callback.ProducesMore
4. If it produces multiple results that can be processed in parallel, extend Callback.ProducesMultiple
5. Hook up your callbacks, either manually, or by using Callbacks.chainUp()
6. You can run them synchronously (nice for testing) using Callbacks.runSync()
7. Run them asynchronously ("fire and forget" mode) using CallbackExecutor.submitCallback()
8. There are many examples in AbstractCallback, or the code in CallbacksTest

Notes:

• Multiple callback options, choosing according to status, was considered and, for now, rejected. It added a lot of complexity, is not a feature in JavaScript, and is more suited for an Emitter.
• Putting the link to the next callback somewhere else (e.g. in a Collection of Callbacks) was strongly considered and, for now, rejected. It has advantages and disadvantages.
• The ProducesMore and ProducesMultiple options likely introduce tricky state in your Callbacks. Be wary.