commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Niall Pemberton <niall.pember...@gmail.com>
Subject Re: [resources] Preparation for a Release Candidate
Date Fri, 25 Nov 2005 22:10:13 GMT
On 11/25/05, Craig McClanahan <craigmcc@apache.org> wrote:
> On 11/25/05, Niall Pemberton <niall.pemberton@gmail.com> wrote:
> >
> > On 11/25/05, Martin Cooper <martinc@apache.org> wrote:
> > > On 11/24/05, Niall Pemberton <niall.pemberton@gmail.com> wrote:
> > > >
> > > > On 11/23/05, Martin Cooper <martinc@apache.org> wrote:
> > > > > On 11/22/05, Niall Pemberton <niall.pemberton@blueyonder.co.uk>
> > 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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message