incubator-kato-spec mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicholas Sterling <Nicholas.Sterl...@Sun.COM>
Subject Re: Kato API javadoc
Date Mon, 06 Apr 2009 22:11:35 GMT

I personally prefer unchecked exceptions, Steve.  Let me see if I can 
articulate why.

If a sustaining engineer is working on a problem with a customer, s/he 
may write a little program using this API to rummage around in each of 
the stream of core files they will get as they try various experiments.  
The sustaining engineer thinks s/he knows the situation: that an image 
contains a single process, that it is a Java program, that a particular 
thread exists, that a particular class is being used, etc.  Sure, they 
could codify their assumptions by writing explicit checks, but it would 
be more straightforward to just write the code saying "give me thread 
X."  They will be sorely tempted to do that; it's easier, and such code 
will be easier to grok when passed around.

Unfortunately, if they do that and the API returns special values for 
exceptional conditions, then if one of their assumptions *is* violated 
their analyzer is going to blow up in some strange way, perhaps 
downstream a bit from the violated assumption, and now they're debugging 
their analyzer instead of the customer's problem.

If, however, unchecked exceptions are used, then the sustaining engineer 
could just assume everything they expect to be there actually is there, 
and the API will tell them if they are wrong -- clearly, and precisely 
at the location of the violated assumption.  Aha!  There is no thread 
X.  99% of the time there assumptions will be correct, so let them just 
assume what they want to.  And the 1% of the time they are wrong, it 
isn't a brain-teaser in its own right.

It is because I am hoping that the API will prove useful for such ad-hoc 
analysis that I prefer not to encumber the API by requiring explicit 
tests or exception-handling.

Of course, people writing serious generic diagnostic tools can't assume 
anything; their tools will have to deal with all possibilities, 
everything the API could return.  Regardless of whether we use special 
values or exceptions, they'll have to code for the uncommon case.  
Honestly, I think *checked* exceptions would be best for them, because 
they couldn't forget to catch an exception.  But checked exceptions 
place constraints on the API's evolution, and again, they make life 
harder for the sustaining engineer who thinks s/he knows the situation 
(by requiring explicit handling for each exception).

Just my 2 cents.

Nicholas



Steve Poole wrote:
> On Mon, Apr 6, 2009 at 6:46 PM, Nicholas Sterling <Nicholas.Sterling@sun.com
>   
>> wrote:
>>     
>
>   
>> In particular, JavaReference and JavaVMInitArgs could use enums if we
>> dropped support for 1.4.2 clients.  Even if we don't, perhaps they could use
>> a sort of manual equivalent (like Josh Bloch's enums in his "Effective Java"
>> book).
>>
>> Should DataUnavailable be DataUnavailableException?  (Too bad there isn't a
>> shorter convention for naming exceptions then tacking on the "Exception"
>> suffix.)
>>
>>     
>
> One of the things I'd really like to do is see if we can remove the need for
> these exceptions altogether.   We talked about having a model where the API
> never returned null.   The idea would be that in the cases where the API had
> no data it would return a static empty instance  that could be compared
> somehow to see if was the DataUnavailable  instance.  Something like...
>
>     Foo instance =  api.getFoo();
>
>     if(instance==Foo.NODATA) {
>             ...
>     }
>
> or
>
>     Foo data =  api.getFoo();
>
>     if(data instanceof DataUnavailable ) {
>             ...
>     }
>
>
> The reason for not having nulls -  (is that a double negative?)   is that
> coping with unexpected optional data (or missing data) is easy and should
> make everyones code more robust.
>
>
>
>   
>> Nicholas
>>
>>
>>
>>
>> Nicholas Sterling wrote:
>>
>>     
>>> Steve Poole wrote:
>>>
>>>       
>>>> Also, I'm seeing methods that return Iterator with no type (e.g. in
>>>>         
>>>>> JavaMethod).  Is that just a temporary placeholder which will ultimately
>>>>> get
>>>>> a type?
>>>>>
>>>>>
>>>>>           
>>>> That's an interesting question.   The reason for there being no type info
>>>> is
>>>> that the API was designed to compile and run on 1.4.2.
>>>> We need to decide if that still makes sense.   I know that 1.4 is out of
>>>> support by Sun and IBM.    What about Oracle?
>>>>
>>>>
>>>>         
>>> Steve, I was hoping that we do *not* need to give people the ability to
>>> write such tools in 1.4.2, but we *do* need to  give people the ability to
>>> analyze 1.4.2 dump artifacts using a tool written in Java 6.  Since no
>>> 1.4.2-based code would be linked against the API, the API would be free to
>>> use generics and other features (enums would help a lot, I suspect) that
>>> came later.  That is, a provider would have to understand 1.4.2 dump
>>> artifacts, but it could be compiled under JDK 6.
>>>
>>> Or maybe I'm not on the same page...
>>>
>>> Nicholas
>>>
>>>
>>>       
>>>>> Nicholas
>>>>>
>>>>>
>>>>>
>>>>> Steve Poole wrote:
>>>>>
>>>>>
>>>>>
>>>>>           
>>>>>> Well at last ! -  we actually have the API javdoc available -  it's
>>>>>> here
>>>>>>
>>>>>> http://hudson.zones.apache.org/hudson/view/Kato/job/kato.api-head/javadoc/
>>>>>>
>>>>>> I'm certainly not going to hold this up as a the greatest javadoc
in
>>>>>> the
>>>>>> world but its a good place to start.  I do feel that we have  finally
>>>>>> arrived :-)
>>>>>>
>>>>>> The API has lots of "DTFJ"ness to it that needs to go but I'm really
>>>>>> interested in intitial reactions to the javadoc -  is the form of
the
>>>>>> API
>>>>>> what you expected?
>>>>>>
>>>>>>
>>>>>> Moving on - there is still code needed to make the API work (we need
to
>>>>>> get
>>>>>> the hprof support working)   but  we can make progress in the interim.
>>>>>>  I
>>>>>> want to move quickly towards having a regular heat beat where we
are
>>>>>> moving
>>>>>> through the usecases that we have.  To do that we need to  get  up
to
>>>>>> speed
>>>>>> with the API shape as it stands today.    Stuart has published some
>>>>>> info
>>>>>> on
>>>>>> the  API but its not really sufficent for educational needs :-)
>>>>>>
>>>>>> Is it worth holding a conference call so that we can walk through
the
>>>>>> API
>>>>>> to
>>>>>> explain why its the shape it is or is everyone comfortable with just
>>>>>> more
>>>>>> doc?
>>>>>>
>>>>>> Cheers
>>>>>>
>>>>>> Steve
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>             
>>>>         
>>>       
>
>   

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message