I guess the first question we should cover is if you're using PayPal's Instant Payment Notification service to receive the notification from PayPal that your user has completed some type of PayPal transaction. If you're not using that, but will instead log into PayPal's site every day and process the transactions, then you don't need to worry about the Listener and the delegates, nor indeed the whole process of getting the request parameters from PayPal. You could then just use the button or link components to either start a transaction for a single item or add the item to a PayPal shopping cart. You could also pretty much skip the rest of this email.
Let me briefly try to convince you of the benefits of notifications and delegates...
A Success Story
Imagine a small one-man company named ACME. ACME takes orders from its customers and sends them along to its supplier, ZYX. The supplier then phones ACME to confirm that the order was received and give some details about when ACME can expect its shipment. As the company grows, the CEO gets too many responsibilities to continue to interface with the ZYX and handle all the order management, so he hires an assistant and installs a PBX switchboard to route calls from ZYX to his assistant. The CEO teaches his new assistant the responsibilities of order management and assigns the assistant to "handle" those responsibilities. As a result of its new efficiency, ACME grows, all the employees gets rich from their stock options, and everyone lives happily ever after.
Decoding the Story
The above (fairly contrived) example demonstrates the general idea of notifications and delegates. You could say that the callback from supplier ZYX is analogous to the PayPal IPN. The switchboard in this case is the equivalent of an NSNotificationCenter; it detects an incoming call and then directs the call (the NSNotification message) to the appropriate listener. In this case, the switchboard is programmed to detect a call from company ZYX and forward it to the assistant who has been assigned, or "delegated," the responsibility of handling calls from ZYX. Once the assistant, (the delegate) receives the call, it does one of the things it knows how to do with the call, depending on the type of message it receives.
Back to reality... Notifications and delegates are simple design patterns that you'll see scattered throughout Cocoa and WebObjects. They're very useful, and not really too complicated.
Similarly, a delegate is a way to pass the responsibility for processing certain off to another class. Using delegates allows you to "loosely couple" classes together and customize behavior by assigning the delegate class you need in a particular instance. The delegate need only implement a certain set of methods so that it can handle the messages you're going to pass to it. You could even have multiple delegates with different behavior and swap them as necessary at runtime.
How It Relates to WOPayPal
I use a notification mechanism to broadcast the message to handle different conditions of the PayPal notification to the "listener" (subscribed to receive certain notifications) which then forwards the message to the assigned "delegate." In the case of WOPayPal, the delegate just has to implement the methods to handle the PayPal messages that you're interested in. There are 5 methods in the delegate interface:
- Tell PayPal how to find your application and where to send the IPN messages in your IPN preferences.
That's pretty much the story of WOPayPal. I hope that this helps clarify what's going on in the framework, and how you can easily leverage it. At the very least, if you have a copy of the source code, you can copy out the relevant portions of the DirectAction class. Please let me know if you have further questions. I promise not to be so long-winded in the future.