[Java] Document references

[vmikhailenko]

The application developers are now exposed to the concept of references via arguments of custom handlers.

They should now what these are and how you supposed to work with them.

We can also improve the APIs a bit as some of these look rather ugly.