incubator-kato-spec mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Poole <spoole...@googlemail.com>
Subject Re: Kato API javadoc
Date Mon, 06 Apr 2009 21:28:29 GMT
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