How about this idea: Define a new annotation "StableImplUnstableInterface" which means consumers can't assume stability but producers can't change things. Mark all toStrings with this annotation.
Then, in a lazy fashion, as the need arises to change various toString methods, diligence can be done first to see if any legacy code depends on a method in a compatibility-breaking manner, those dependencies can be fixed, then the method is changed and remarked as unstable. Conversely, there might be circumstances where a toString method might be marked as stable. (Certainly it's reasonable to assume the Integer.toString returns a parsable result, for example, the point being that for some classes it makes sense to have a stable spec for toString). Over the years one would hope that the StableImplUnstableSpec annotations would disappear. Sent from my iPhone > On May 12, 2016, at 1:40 PM, Sean Busbey <bus...@cloudera.com> wrote: > > 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 > --------------------------------------------------------------------- To unsubscribe, e-mail: common-dev-unsubscr...@hadoop.apache.org For additional commands, e-mail: common-dev-h...@hadoop.apache.org
