As a downstream user of Hadoop, it would be much clearer if the toString functions included the appropriate annotations to say they're non-public, evolving, or whatever.
Most downstream users of Hadoop aren't going to remember in-detail exceptions to the java API compatibility rules, once they see that a class is labeled Public/Stable, they're going to presume that applies to all non-private members. On Thu, May 12, 2016 at 9:32 AM, Colin McCabe <cmcc...@apache.org> wrote: > Hi all, > > Recently a discussion came up on HADOOP-13028 about the wisdom of > overloading S3AInputStream#toString to output statistics information. > It's a difficult judgement for me to make, since I'm not aware of any > compatibility guidelines for InputStream#toString. Do we have > compatibility guidelines for toString functions? > > It seems like the output of toString functions is usually used as a > debugging aid, rather than as a stable format suitable for UI display or > object serialization. Clearly, there are a few cases where we might > want to specifically declare that a toString method is a stable API. > However, I think if we attempt to treat the toString output of all > public classes as stable, we will have greatly increased the API > surface. Should we formalize this and declare that toString functions > are @Unstable, Evolving unless declared otherwise? > > best, > Colin > > --------------------------------------------------------------------- > To unsubscribe, e-mail: common-dev-unsubscr...@hadoop.apache.org > For additional commands, e-mail: common-dev-h...@hadoop.apache.org > -- busbey --------------------------------------------------------------------- To unsubscribe, e-mail: common-dev-unsubscr...@hadoop.apache.org For additional commands, e-mail: common-dev-h...@hadoop.apache.org
