Deprecate Observable#throttle for Observable#debounce and RxJava-named methods

[L8D]

Is this good? The docs and perhaps the tests need to be updated.

Closes #284

[mattpodwysocki]

@L8D Yes, you need to update all docs, tests and so forth for this to be accepted

[mattpodwysocki]

@headinthebox @benjchristensen can you weigh in here as to the correct semantics of debounce and the RxJava named throttle* methods?

[headinthebox]

I have discussed this soo many times that my memory has gotten blurry. I do know that @benjchristensen thinks the .NET semantics are too UI specific and that we needed something else for the server side.

I would say, switch to the names and semantics of RxJava https://github.com/ReactiveX/RxJava/wiki/Filtering-Observables.

[jwooley]

I would be concerned by the amount of breaking code this change would make. if you decide to go forward with the change, make sure to provide sufficient guidance to assist devs fixing their code that this change would cause.

[mattpodwysocki]

@jwooley we're deprecating, not removing, so you can get a warning and not an error. Just saying by the next major revision, they will likely be gone

[benjchristensen]

@mattpodwysocki Thanks for making this change, it really helps to clarify the language. Here is the original RxJava issue with links to definitions of debounce: ReactiveX/RxJava#368

Here is a snippet from it:

---

Here is a good place to get a description of throttle versus debounce: http://drupalmotion.com/article/debounce-and-throttle-visual-explanation

Debounce: Think of it as "grouping multiple events in one". Imagine that you go home, enter in the elevator, doors are closing... and suddenly your neighbor appears in the hall and tries to jump on the elevator. Be polite! and open the doors for him: you are debouncing the elevator departure. Consider that the same situation can happen again with a third person, and so on... probably delaying the departure several minutes.

Throttle: Think of it as a valve, it regulates the flow of the executions. We can determine the maximum number of times a function can be called in certain time. So in the elevator analogy.. you are polite enough to let people in for 10 secs, but once that delay passes, you must go!

Other links includes:

• http://unscriptable.com/2009/03/20/debouncing-javascript-methods/
• http://www.illyriad.co.uk/blog/index.php/2011/09/javascript-dont-spam-your-server-debounce-and-throttle/

---

We have the following operators in RxJava:

• throttleLast/sample=> https://github.com/ReactiveX/RxJava/wiki/Filtering-Observables#sample-or-throttlelast
• throttleFirst => https://github.com/ReactiveX/RxJava/wiki/Filtering-Observables#throttlefirst (this is more efficient than throttleLast as it doesn't need to store and throw away values)
• throttleWithTimeout/debounce => https://github.com/ReactiveX/RxJava/wiki/Filtering-Observables#throttlewithtimeout-or-debounce

For better or worse we use aliases to try and and make it clear that sample and debounce are different forms of throttle.

[mattpodwysocki]

@benjchristensen @headinthebox sounds good. @L8D do you want me to make the doc changes for you as well as the tests? We should also add a "Deprecated APIs section as well as to not trip people up.

[L8D]

@mattpodwysocki I can't tell if you made the changes for me atm, but if you did thanks. Otherwise, I'll be making another PR later today.

[mattpodwysocki]

@L8D yeah, I made the change, and I'm deprecating others while I'm at it.