[core] indicate replacement methods in the javadoc

Created by: jmini

PR #2946 has deprecated some methods.

This PR adds a Javadoc note to indicate the replacement method.

cc @jimschubert