lucene-java-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael-O <1983-01...@gmx.net>
Subject Re: Excessive use of IOException without proper documentation
Date Sun, 04 Nov 2012 17:25:37 GMT
Hi Simon,

there are generally two very good resources how exceptions should be 
handled in Java. I will quote both:

1. Oracle's JavaDoc Style Guide: 
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#throwstag
2. Joshua Bloch's book Effective Java, chapter 9: 
http://my.safaribooksonline.com/book/programming/java/9780137150021

Am 2012-11-02 22:27, schrieb Simon Willnauer:
> Hey,
>
> On Fri, Nov 2, 2012 at 2:20 PM, Michael-O <1983-01-06@gmx.net>
> wrote:
>> Hi,
>>
>> why does virtually every method (exaggerating) throw an IOE? I know
>> there might be a failure in the underlying IO (corrupt files,
>> passing checked exc up, etc) but
>>
>> 1. Almost none of the has a JavaDoc on it
>
> what should the javadoc say? I mean it would repeat itself all the
> time no?

At least one would know why this one is thrown. See source one.

>> 2. Throwing an IOE from most of the methods doesn't really help.
>> You cannot create separate catch blocks. You have to rip your code
>> apart in tens of try catch blocks.
>>
>> Here is a simple example: Both IndexSearcher#search and
>> IndexSearcher#doc throw an IOE with any further documentation. I
>> don't have the chance to detect where the exception has happened
>> nor I can pass something reasonable back to the user. And both
>> methods are keypoints in Lucene.
>
> can you elaborate what you would change to make this easier
> digestible for you? I mean specialized exceptions class would be a
> mess here really.

Not only for me but for everyone.

Generally, good exception handling should setup a simple exception 
hierarchy, not more than three levels. Two base classes for checked and 
unchecked exceptions. A main exception for a logical group like 
searching, retreival, query checking, etc.

LuceneException
|-- SearchException
|-- RetrievalException
|-- ...

One should really wrap IOE in something like 'new 
SearchException("Failed to read the index", ioe)'. I would at least know 
that this one came from the index searcher.

Really advisable are items 61, 62 and especially 63.

>> E.g., there are exceptions thrown in IndexSearcher without any
>> message. Simply empty stubs.
>
> I agree we should fix them. I already committed some fixes to
> IndexSearcher. Can you come up with a patch that fixes some more in
> core?
>
> running grep -R "new.*Exception()" * | wc -l
>
> yields 82 in core so there is room for improvement.
>
>>
>> Lucene 4.0 received a complete API overhaul. Why was no action
>> taken to clean up exception management?
>
> I'd really like to hear what you have in mind. can you elaborate?

Continuing my answer from above. Have you ever worked with the Spring 
Framework? They apply a very nice exception translation pattern. All 
internal exceptions are turned to specialized unchecked exceptions like
AuthenticationExceptoin, DaoAccessException, etc.

Lucene has already good exceptions like CorruptIndex, IndexNotFound, 
LockObtainFailed, etc.

Of course, such a step would break backwards-compat but this is possible 
for 5.0 and this would require a general consensus of the devs improving 
this issue.

I think that such a great framework can do better to inform programmers 
and users what has really failed especially if you design a public API.
We have succeeded exceptional results with the Lucene framework. I am 
someone who likes giving help back to OSS projects.

Hopefully, this is enough input for this message. We could discuss this 
further is there is a real interest from the devs.

Mike

---------------------------------------------------------------------
To unsubscribe, e-mail: java-user-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-user-help@lucene.apache.org


Mime
View raw message