On 11/25/05, Craig McClanahan <[EMAIL PROTECTED]> wrote: > On 11/25/05, Niall Pemberton <[EMAIL PROTECTED]> wrote: > > > > On 11/25/05, Martin Cooper <[EMAIL PROTECTED]> wrote: > > > On 11/24/05, Niall Pemberton <[EMAIL PROTECTED]> wrote: > > > > > > > > On 11/23/05, Martin Cooper <[EMAIL PROTECTED]> wrote: > > > > > On 11/22/05, Niall Pemberton <[EMAIL PROTECTED]> > > wrote: > > > > > > > > > > > > 1) Quite a few methods are declaring in the javadoc that they > > throw > > > > > > RuntimeExceptions, which are coming out on the checkstyle: > > > > > > > > http://jakarta.apache.org/commons/resources/checkstyle-report.html > > > > > > > > > > > > My preferenc is to removed these, but I can understand why they > > were > > > > put > > > > > > in. > > > > > > Opinions? > > > > > > > > > > > > > > > I think the code should say what it means. ;-) Looking at > > Resources.java > > > > , > > > > > the init() and destroy() methods declare that they throw > > > > ResourcesException > > > > > (and Javadoc that). All of the other methods do not declare that > > they > > > > throw > > > > > that exception, but the Javadocs say they do. If they really do (or > > > > can), > > > > > then they should declare that. If they don't, then we should remove > > the > > > > > Javadocs. > > > > > > > > They can throw those exceptions, but since they're derived from > > > > RuntimeExceptions it doesn't make any difference wether they're in the > > > > method signature or not. I've changed my mind and think we should > > > > leave them as it is - the javadoc informs people that they can be > > > > thrown - whether they choose to handle them or not is up to them. Sun > > > > does the same kind of thing in java.util.ResourceBundle in java 1.4 - > > > > its getObject() method has Runtime exceptions in the javadoc, but not > > > > the method signature. > > > > > > > > > OK. Now what is the justification for the init and destroy methods in > > > Resources to explicitly state that they throw ResourcesException, but > > not > > > the other methods? That seems a little odd. > > > > I agree it is inconsistent so I'm not going to try and justify it. At > > the end of the day IMO it doesn't matter which way you go and its just > > a question of whether inconsistency in this case matters enough to > > change things. If the consensus is it does, my preference would be to > > change the init/detroy method signatures simply because that > > represents the least amount of work. If you (or anyone else) has a > > strong opinion on this, then I'll go with that and get this put to > > bed. > > > I've seen a trend in API design towards explicity documenting (in Javadocs) > the RuntimeExceptions that a method might throw, but not declaring the > "throws" clause (because the language doesn't require you to use try/catch > around calls to those methods). My initial leaning would be towards this > (which would mean removing the throws on init/destroy) but leaving the docs > alone. > > I'm definitely +1 we should be consistent throughout the API, though ... and > that we need to address this now and not later.
OK I've changed the method signatures so that ResourceExceptions are not declared - just documented in the API. As well as Resources and implementations, I also noticed the same was true from ResourcesFactory and its implementations, so I changed them as well: http://svn.apache.org/viewcvs?rev=349025&view=rev Niall > > Craig > > > > -- > > > Martin Cooper > > > > > > > > > Niall > > > > > > > > > My tuppence. > > > > > > > > > > -- > > > > > Martin Cooper --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
