Migrate sample code from USAGE.md into samples collection

[andregasser]

As discussed here, the code in USAGE.md should be merged into our samples collection, currently available in the sample and the sample-kotlinmodules.

Main tasks include:

• Check if samples present in USAGE.md are entirely missing in our samples collection. If yes, add a sample to the samples collection for Java and Kotlin each.
• Delete USAGE.md

[andregasser]

@bocops I had a look ad USAGE.md. Honestly, I am not sure how to migrate that example code into a working code sample, as the OAuth flow involved requires an URL to be opened in a browser (so the user can log in).

If I am not mistaken, our client always uses an access token at the end, which is set using .accessToken(...) in our client builder. The interactive login process using OAuth in the browser that happens before, is probably not a good candidate to put in a code sample. Or am I missing something here?

[bocops]

I just saw your PR #88, probably makes sense to leave a note here in the context of those changes first.

From personal experience with trying out the original library a month ago, getting the whole OAuth flow correctly was the trickiest part, and in hindsight two choices of the original README plus samples seem to be the main culprits:

1. The use of urn:ietf:wg:oauth:2.0:oob as the redirect URI throughout made it seem as if I had to work with that, when actually that is the worst choice of all.
2. The use of a password grant type (via the Authenticator classes of the samples) made it seem as if that's a viable alternative, when it really isn't.

In combination, I spent too much time on trying to get horribly wrong authentication flows to work, before reading up on OAuth elsewhere and finding out that it's actually not that hard to do right. ;)

So my suggestions would be to:

• get rid of all occurrences of urn:ietf:wg:oauth:2.0:oob anywhere in sample code.
• if we want to keep Authenticator classes somewhere (so that developers can get credentials for the other samples to work somehow), we should clarify that these classes themselves are not good examples of how to implement authentication. This could be done by moving them out of the same directory as the samples - or at least by explicitly commenting the code along those lines and not directly calling it from the samples. The Authenticators could still write to a local file that the other samples read from, if we want to have samples that work out of the box.
• have one example that at least hints at the proper authentication flow with a custom redirect_uri for which the library user then needs to declare some sort of intent depending on the platform they are developing for. We should have that example even if it is incomplete, because that would have been the most helpful example for me.

[bocops]

Reviewing your PR #88 now, I see the use of placeholder strings throughout, like in GetTagTimeline.java:

final String instance = "<YOUR INSTANCE>";
final String hashtag = "<YOUR HASHTAG>";

Would it perhaps be better to read these from the command line and comment the variables, so that library users can just compile and run to immediately see some first results? We could then even add the necessary commands to USAGE.md (replacing code samples) or any other file or Wiki page where it fits best. So, using the above example again:

// Example: find statuses with a hashtag (here: "bigbone") on a Mastodon instance (here: "fosstodon.org")

$ java GetTagTimeline.java "fosstodon.org" "bigbone"

In the case of samples that need authentication, if we want to keep Authenticator clases and their configuration file output, this could be two commands like:

// Example: search for some term (here: "Gargron") on a Mastodon instance (here: "mastodon.social");
// returns accounts, statuses and hashtags

$ java Authenticator.java // only necessary once; ATTENTION: some authentication data will be stored in a local plain-text file
$ java PerformSimpleSearch.java "mastodon.social" "Gargron"