You are viewing a plain text version of this content. The canonical link for it is here.

Posted to kato-spec@incubator.apache.org by Steve Poole <sp...@googlemail.com> on 2009/04/04 15:30:06 UTC

Kato API javadoc

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

Re: Kato API javadoc

Posted by Stuart Monteith <st...@stoo.me.uk>.

Hi,
	The TCK harness that's checked in finds all of the necessary classes,  
executes all the "configure*" methods it finds, then calls a method  
that is configured to get the JVM to generate a system dump, javacore,  
or whatever. In one usecase we get the JVM to SIGSEGV. Then the  
harness executes another JVM that execute the jUnit testcases for the  
same set of classes, making available an instance of the Image and  
JavaRuntime for the dump that was generated by the previous JVM. The  
trick is really down to generating the dump programatically -  
something I'd like to do with hprof at some point.

I assume -target 1.4 would just complain. However, a build step to  
make two classes from one is interesting - would just need to decide  
on a mechanism.

Regards,
	Stuart


On 6 Apr 2009, at 21:34, Nicholas Sterling wrote:

> Hi, Stuart.
>
> Interesting.  Yes, that is convenient being able to keep it all  
> together that way -- it would be a shame to lose that.  Hmmm.  I  
> suppose you could have some build step that rips out testXXX methods  
> and compiles for the target VM??
>
> I don't think "-target 1.4" would help (?).
>
> In any case, as you say, it's not the end of the world.
>
> Nicholas
>
> p.s.  Will coordination of the two VMs complicate things?  I suppose  
> you just have to run the target to completion before starting the  
> client?
>
>
> Stuart Monteith wrote:
>> Hi Nicholas,
>>   You are definitely on the same page. One thing we need to rethink  
>> is the TCK.
>>
>> The TCK tests each look something like this:
>>
>> /**
>> * Testcase to  find a Java thread called "quack".
>> */
>> public class DuckTests extends Testcase {
>>   String threadName="quack";
>>
>>   public void configure() {
>>      Thread thread = new Thread(threadName, Runnable);
>>      thread.start()
>>   }
>>
>>   public void testQuack() {
>>      JavaRuntime jr = *getJavaRuntime*();
>>
>>      Iterator threads =  *jr.getThreads*();
>>      while(threads.hasNext()) {
>>         JavaThread next = (JavaThread) threads.next();
>>
>>         if  (threadName.equals(next.getName())) {
>>            // success
>>            return;
>>         }
>>      }
>>
>>      fail("Couldn't find thread \""+threadName+"\"");
>> }
>>
>> The TCK would on the first instance run the configure() method,  
>> then cause the JVM to generate a dump that can be read through our  
>> API. It would then would run jUnit and execute the testQuack()  
>> method. This way we have a nice, self contained test that includes  
>> the setup of a JVM and the test of the API to read the resultant  
>> dump in the same place. You'll notice that the constant for the  
>> name of the thread is shared by the JVM dumping and the JVM that  
>> would be running the testcases, which helps consistency enormously.
>>
>> It makes sense to do it this way, but only when the API is at the  
>> same level as the JVM that is being configured to generate a dump.
>>
>> If Kato is to support 1.4.2, the TCK will need to support it, but  
>> that is something that will just have to be fixed as the API evolves.
>>
>> I don't believe it would be an enormous problem.
>> For example, we could have a class to configure and another to run  
>> the tests, each compiled to different levels:
>>
>> /**
>> * Configuration for DuckTests
>> */
>> public class DuckConfiguration extends TestCase {
>>   String threadName="quack";
>>
>>   public void configure() {
>>      Thread thread = new Thread(threadName, Runnable);
>>      thread.start()
>>   }
>> }
>>
>> /**
>> * Testcase to find Duck thread with API.
>> */
>> public class DuckTests extends DuckConfiguration {
>>
>>   public void testQuack() {
>>      JavaRuntime jr = getJavaRuntime();
>>
>>      Iterator<JavaThread> threads =  jr.getThreads().iterator();
>>      while(threads.hasNext()) {
>>         JavaThread next = (JavaThread) threads.next();
>>
>>         if  (threadName.equals(next.getName())) {
>>            // success
>>            return;
>>         }
>>      }
>>
>>      fail("Couldn't find thread \""+threadName+"\"");
>> }
>>
>> So, in summary, my view is that there is nothing stopping us using  
>> Java 5.0 language features, we just need to structure the TCK to  
>> take this into account.
>>
>> Regards,
>>   Stuart
>>
>>
>> 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
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>
>>>>
>>>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.

Hi, Stuart.

Interesting.  Yes, that is convenient being able to keep it all together 
that way -- it would be a shame to lose that.  Hmmm.  I suppose you 
could have some build step that rips out testXXX methods and compiles 
for the target VM??

I don't think "-target 1.4" would help (?).

In any case, as you say, it's not the end of the world.

Nicholas

p.s.  Will coordination of the two VMs complicate things?  I suppose you 
just have to run the target to completion before starting the client?


Stuart Monteith wrote:
> Hi Nicholas,
>    You are definitely on the same page. One thing we need to rethink 
> is the TCK.
>
> The TCK tests each look something like this:
>
> /**
> * Testcase to  find a Java thread called "quack".
> */
> public class DuckTests extends Testcase {
>    String threadName="quack";
>
>    public void configure() {
>       Thread thread = new Thread(threadName, Runnable);
>       thread.start()
>    }
>
>    public void testQuack() {
>       JavaRuntime jr = *getJavaRuntime*();
>
>       Iterator threads =  *jr.getThreads*();
>       while(threads.hasNext()) {
>          JavaThread next = (JavaThread) threads.next();
>
>          if  (threadName.equals(next.getName())) {
>             // success
>             return;
>          }
>       }
>
>       fail("Couldn't find thread \""+threadName+"\"");
> }
>
> The TCK would on the first instance run the configure() method, then 
> cause the JVM to generate a dump that can be read through our API. It 
> would then would run jUnit and execute the testQuack() method. This 
> way we have a nice, self contained test that includes the setup of a 
> JVM and the test of the API to read the resultant dump in the same 
> place. You'll notice that the constant for the name of the thread is 
> shared by the JVM dumping and the JVM that would be running the 
> testcases, which helps consistency enormously.
>
> It makes sense to do it this way, but only when the API is at the same 
> level as the JVM that is being configured to generate a dump.
>
> If Kato is to support 1.4.2, the TCK will need to support it, but that 
> is something that will just have to be fixed as the API evolves.
>
> I don't believe it would be an enormous problem.
> For example, we could have a class to configure and another to run the 
> tests, each compiled to different levels:
>
> /**
> * Configuration for DuckTests
> */
> public class DuckConfiguration extends TestCase {
>    String threadName="quack";
>
>    public void configure() {
>       Thread thread = new Thread(threadName, Runnable);
>       thread.start()
>    }
> }
>
> /**
> * Testcase to find Duck thread with API.
> */
> public class DuckTests extends DuckConfiguration {
>
>    public void testQuack() {
>       JavaRuntime jr = getJavaRuntime();
>
>       Iterator<JavaThread> threads =  jr.getThreads().iterator();
>       while(threads.hasNext()) {
>          JavaThread next = (JavaThread) threads.next();
>
>          if  (threadName.equals(next.getName())) {
>             // success
>             return;
>          }
>       }
>
>       fail("Couldn't find thread \""+threadName+"\"");
> }
>
> So, in summary, my view is that there is nothing stopping us using 
> Java 5.0 language features, we just need to structure the TCK to take 
> this into account.
>
> Regards,
>    Stuart
>
>
> 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
>>>>>
>>>>>
>>>>>
>>>>>       
>>>
>>>   
>>

Re: Kato API javadoc

Posted by Stuart Monteith <st...@stoo.me.uk>.

Hi Nicholas,
    You are definitely on the same page. One thing we need to rethink is 
the TCK.

The TCK tests each look something like this:

/**
 * Testcase to  find a Java thread called "quack".
 */
public class DuckTests extends Testcase {
    String threadName="quack";

    public void configure() {
       Thread thread = new Thread(threadName, Runnable);
       thread.start()
    }

    public void testQuack() {
       JavaRuntime jr = getJavaRuntime();

       Iterator threads =  jr.getThreads();
       while(threads.hasNext()) {
          JavaThread next = (JavaThread) threads.next();

          if  (threadName.equals(next.getName())) {
             // success
             return;
          }
       }

       fail("Couldn't find thread \""+threadName+"\"");
}

The TCK would on the first instance run the configure() method, then 
cause the JVM to generate a dump that can be read through our API. It 
would then would run jUnit and execute the testQuack() method. This way 
we have a nice, self contained test that includes the setup of a JVM and 
the test of the API to read the resultant dump in the same place. You'll 
notice that the constant for the name of the thread is shared by the JVM 
dumping and the JVM that would be running the testcases, which helps 
consistency enormously.

It makes sense to do it this way, but only when the API is at the same 
level as the JVM that is being configured to generate a dump.

If Kato is to support 1.4.2, the TCK will need to support it, but that 
is something that will just have to be fixed as the API evolves.

I don't believe it would be an enormous problem.
For example, we could have a class to configure and another to run the 
tests, each compiled to different levels:

/**
 * Configuration for DuckTests
 */
public class DuckConfiguration extends TestCase {
    String threadName="quack";

    public void configure() {
       Thread thread = new Thread(threadName, Runnable);
       thread.start()
    }
}

/**
 * Testcase to find Duck thread with API.
 */
public class DuckTests extends DuckConfiguration {

    public void testQuack() {
       JavaRuntime jr = getJavaRuntime();

       Iterator<JavaThread> threads =  jr.getThreads().iterator();
       while(threads.hasNext()) {
          JavaThread next = (JavaThread) threads.next();

          if  (threadName.equals(next.getName())) {
             // success
             return;
          }
       }

       fail("Couldn't find thread \""+threadName+"\"");
}

So, in summary, my view is that there is nothing stopping us using Java 
5.0 language features, we just need to structure the TCK to take this 
into account.

Regards,
    Stuart


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
>>>>
>>>>
>>>>
>>>>       
>>
>>   
>

Re: Kato API javadoc - error handling

Posted by Stuart Monteith <st...@stoo.me.uk>.

That addresses the issue.
The last time I has to call an API with the visitor API I ended up using 
an unchecked exception to abort it if the visit wasn't going to be 
interesting. I did feel ashamed about doing that though :-)

Nicholas Sterling wrote:
> How about having visitObject return a boolean saying whether traversal 
> should continue?
>
> Nicholas
>
>
> Stuart Monteith wrote:
>> I think with the visitor pattern we'd have to weigh up the typical 
>> usage patterns against the loss of control it implies.
>> Certainly for the heap, you might typically do a linear scan as the 
>> locality of objects implies nothing about their relationship to one 
>> another - using a bidirectional cursor is pointless.. The loss of 
>> control means that the entire heap will be scanned, regardless of 
>> what occurs.
>>
>> I think better with examples, so say we are counting all of the 
>> instances of classes, by name:
>>
>>
>>   final Foo outside_class = ...;
>>
>>   HeapVisitor visitor = new HeapVisitor() {
>>       HashMap<String,Long> classCount = new HashMap<String,Long>();
>>       Foo inside_class = ...;
>>
>>       void visitObject( JavaObject obj )  {
>>           // Both outside_class and inside_class are visible.
>>           // Var outside_class cannot be modified, of course,
>>           // but fields in the object it refers to may.
>> 1         JavaClass clazz = obj.getJavaClass();
>> 2         String className = clazz.getName();
>>           Long count= classCount.get(className);
>>                  if (count.longValue() == 0) {
>>             classCount.put(className, 1);
>>          } else {
>>             classCount.put(className, count+1);
>>          }
>>       }
>>
>>       void handleDataUnavailable( JavaObject obj ) {
>>           // Same here.
>>           // If we didn't put this method here, the default
>>           // would just throw a DataUnavailableException.
>>       }
>>            void HandleCorruptDataException(JavaObject obj) {
>>       }
>>   };
>>
>>    try{
>>       JavaHeap heap = factory.getJavaHeap(...);
>>    }catch(CorruptDataException e) {
>>    }catch(DataUnavailableException e) {
>>    }
>>   heap.visit( visitor );
>>
>> We could get CorruptDataException at 1 and 2, one would be because of 
>> the JavaObject, the other would be because of the JavaClass it 
>> referred to. I would posit that the exception information should be 
>> sufficient to properly report the problem in most cases as the 
>> processing done in a visitor method would be to do only with the 
>> object it is passed, and anything fairly close to it, such as its 
>> classes and fields.
>>
>> Of course, how well would this work for smaller items, such as fields 
>> in classes, classes in classloaders, etc.
>> With fields, I tend to want to address them by name or get all of 
>> them from a class.
>>
>>
>>
>> Nicholas Sterling wrote:
>>> That last example, the JDBC sanitizer, is much more conventional -- 
>>> there's no handler stack.  It is essentially a combination of the 
>>> Template and Visitor design patterns.  The Template pattern is often 
>>> applied to Java exceptions, so I don't think this would be thought 
>>> of as unusual.
>>>
>>> Instance variables in the anonymous class would be accessible to 
>>> both the method doing the work and the method handling the 
>>> exceptions.  And the class could access final variables outside it:
>>>
>>>    final Foo outside_class = ...;
>>>
>>>    HeapVisitor visitor = new HeapVisitor() {
>>>
>>>        Foo inside_class = ...;
>>>
>>>        void visitObject( JavaObject obj ) {
>>>            // Both outside_class and inside_class are visible.
>>>            // Var outside_class cannot be modified, of course,
>>>            // but fields in the object it refers to may.
>>>        }
>>>
>>>        void handleDataUnavailable( JavaObject obj ) {
>>>            // Same here.
>>>            // If we didn't put this method here, the default
>>>            // would just throw a DataUnavailableException.
>>>        }
>>>    };
>>>
>>>    JavaHeap heap = factory.getJavaHeap(...);
>>>    heap.visit( visitor );
>>>
>>> Does something like that seem reasonable?
>>>
>>> Nicholas
>>>
>>>
>>>
>>> Daniel Julin wrote:
>>>> It seems to me that with all this discussion of polymorphic and 
>>>> stackable
>>>> error handlers, we're rapidly re-inventing much of the Java exception
>>>> facility, and probably rediscovering a lot of the same design
>>>> considerations that the original designers of that Java exception 
>>>> facility
>>>> faced...
>>>>
>>>> As far as I can tell, the one major difference is that, with Java
>>>> exceptions, once an exception is thrown, the flow of control is 
>>>> irrevocably
>>>> interrupted and can only resume after the exception handler, not 
>>>> back at
>>>> the point where the exception was thrown. This means that if you do 
>>>> want
>>>> fine control over your errors but don't want to interrupt a whole 
>>>> sequence
>>>> of operations, you're forced to put an explicit try/catch block at 
>>>> every
>>>> line of the program. Whereas with these proposed handlers, a single
>>>> top-level handler could presumably take care of all the errors in a
>>>> sequence of operations without interrupting that sequence.
>>>>
>>>> Is that a correct interpretation? And is there no practical way to 
>>>> achieve
>>>> the same effect with actual Java exceptions? Some sort of "continue"
>>>> statement inside a catch block, maybe?
>>>>
>>>>
>>>> On the other hand, one thing that Java try/catch blocks offer is 
>>>> controlled
>>>> access to the local variables of the method in which the try/catch 
>>>> block
>>>> resides, and to the private instance members of the object. The 
>>>> proposed
>>>> handlers, since they are executing in a separate object and a separate
>>>> method, would not enjoy a similar access. Whether this limitation 
>>>> would
>>>> prove bothersome in practice, will depend on the actual usage 
>>>> scenarios
>>>> that we face...
>>>>
>>>>
>>>> -- Daniel --
>>>>
>>>>
>>>>
>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-14 05:39:40 PM:
>>>>  
>>>>> If we were to end up doing something like this, would we use 
>>>>> checked or
>>>>> unchecked exceptions?  If we use checked exceptions, the client will
>>>>> still have to catch the exception or say that the method throws it.
>>>>> Presumably that would defeat the purpose...
>>>>>
>>>>> Good idea on the comparison code.  I'm a little concerned that people
>>>>> may think we are overengineering the whole exception thing; once 
>>>>> we have
>>>>> the comparison code, we can run it by some folks and see whether 
>>>>> their
>>>>> brains short-circuit.
>>>>>
>>>>> It might be helpful as a reference point to consider an example with
>>>>> another API.  I was sufficiently frustrated by the unreadability 
>>>>> of my
>>>>> JDBC clients that I wrote a pair of classes, Query and Querier, that
>>>>> hide gory details, and I think it makes a big difference.  Among the
>>>>> hidden are the binding of variables and iterating through result 
>>>>> sets,
>>>>> but probably the biggest benefit is from hiding the 
>>>>> exception-handling
>>>>> logic (it closes the ResultSet for you on an exception). This is 
>>>>> what it
>>>>> looks like to use it:
>>>>>
>>>>>     // Create a query to get recent bugs.
>>>>>     static final Query recent_bugs_query = new Query(
>>>>>         "bugs submitted against a PRODUCT in the last NUM DAYS",
>>>>>         "select id, synopsis from bugs " +
>>>>>        " where product = ? and date_submitted > sysdate - ?"
>>>>>     );
>>>>>     ...
>>>>>     // Given a Connection conn and values for PRODUCT and NUM DAYS,
>>>>>     // query the DB for recent bugs and display the resulting rows.
>>>>>     new Querier( recent_bugs_query, conn, product, num_days ) {
>>>>>         public void doRow() throws SQLException {
>>>>>             System.out.println( rs.getString(1) + " " + rs.getString
>>>>>     
>>>> (2) );
>>>>  
>>>>>         }
>>>>>     }
>>>>>
>>>>> A major benefit was getting rid of that awful doubly-nested catch 
>>>>> block
>>>>> (closing the ResultSet in the catch block may throw an exception, 
>>>>> so it
>>>>> requires its own try-catch -- gaah!).
>>>>>
>>>>> The default Querier throws an exception, but you can extend 
>>>>> Querier and
>>>>> override the handleException() method to do whatever is 
>>>>> appropriate for
>>>>> your app, and they use your custom Querier throughout your 
>>>>> program, e.g.
>>>>>
>>>>>     class MyQuerier extends Querier {
>>>>>         void handleException( Exception ex ) {
>>>>>             ....
>>>>>         }
>>>>>     }
>>>>>
>>>>> Perhaps we could use a similar approach, for example providing a
>>>>> HeapQuerier class from which clients create anonymous classes to 
>>>>> do what
>>>>> they want.
>>>>>
>>>>> Nicholas
>>>>>
>>>>>
>>>>>
>>>>> Steve Poole wrote:
>>>>>  
>>>>>> On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
>>>>>> Nicholas.Sterling@sun.com> wrote:
>>>>>>
>>>>>>
>>>>>>    
>>>>>>> And a Handler (whatever it should really be called) would have 
>>>>>>> access
>>>>>>>         
>>>> to
>>>>  
>>>>>>> the previous Handler on the stack, so it could do
>>>>>>>
>>>>>>>   void handleJavaObjectUnavailable(...) {
>>>>>>>       // do some stuff, then defer to the guy beneath us on the 
>>>>>>> stack:
>>>>>>>       prevHandler().handleJavaObjectUnavailable(...);
>>>>>>>   }
>>>>>>> Nicholas
>>>>>>>
>>>>>>> This is cool -  The callback approach is sort of a half way
>>>>>>>         
>>>> housebetween a
>>>>  
>>>>>> DOM and SAX model.  It could allow us to have a default "no nulls"
>>>>>>       
>>>> approch
>>>>  
>>>>>> for an implementation but still allows for users of the API to do
>>>>>>       
>>>> something
>>>>  
>>>>>> different.
>>>>>>
>>>>>> I think we should create some comparison code segments to see 
>>>>>> what it
>>>>>>       
>>>> could
>>>>  
>>>>>> look like.
>>>>>>
>>>>>>
>>>>>>    
>>>>>>> Nicholas Sterling wrote:
>>>>>>>
>>>>>>>
>>>>>>>      
>>>>>>>> Daniel Julin wrote:
>>>>>>>>
>>>>>>>>
>>>>>>>>        
>>>>>>>>> I like that approach a lot, because it may also address the other
>>>>>>>>>             
>>>> concern
>>>>  
>>>>>>>>> that a proposed "default reasonable behavior" may not be 
>>>>>>>>> appropriate
>>>>>>>>>             
>>>> for
>>>>  
>>>>>>>>> all usage scenarios. We could probably come-up with a variety of
>>>>>>>>>             
>>>> handlers
>>>>  
>>>>>>>>> for various common behaviors, like printing a simple error 
>>>>>>>>> message,
>>>>>>>>> completely ignoring the error, and lots of other creative 
>>>>>>>>> responses.
>>>>>>>>>
>>>>>>>>> Incidentally, nothing in this discussion is particularly 
>>>>>>>>> specific to
>>>>>>>>>             
>>>> the
>>>>  
>>>>>>>>> Kato API, is it? Are we saying that, in general, we don't like
>>>>>>>>>             
>>>> exceptions
>>>>  
>>>>>>>>> as the standard mechanism to report errors in Java, and that 
>>>>>>>>> we're
>>>>>>>>> inventing new patterns?  If so, have any useful patterns been
>>>>>>>>>             
>>>> proposed
>>>>  
>>>>>>>>> and
>>>>>>>>> documented previously in the literature?
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>             
>>>>>>>> I just looked around a little, and am only seeing suggestions 
>>>>>>>> for how
>>>>>>>>           
>>>> the
>>>>  
>>>>>>>> *client* can abstract out the exception-handling logic using the
>>>>>>>>           
>>>> Template
>>>>  
>>>>>>>> design pattern.  So far I haven't seen any advice for API 
>>>>>>>> designers.
>>>>>>>>
>>>>>>>> By the way, it occurred to me that the setter can have a 
>>>>>>>> generic name
>>>>>>>> because overloading will allow us to have a method for each
>>>>>>>>           
>>>> condition:
>>>>  
>>>>>>>>   factory.setHandler( new DataUnavailableHandler( ... ) {
>>>>>>>>       ...
>>>>>>>>   } );
>>>>>>>>
>>>>>>>> Also, it might make sense to push the handler on a stack rather
>>>>>>>>           
>>>> replace
>>>>  
>>>>>>>> what is there.  That will allow independent modules to modify just
>>>>>>>>           
>>>> that
>>>>  
>>>>>>>> behavior they need to and then remove those modifications when 
>>>>>>>> they
>>>>>>>>           
>>>> are no
>>>>  
>>>>>>>> longer needed.  It also means that we can have just one Handler
>>>>>>>>           
>>>>> () class for
>>>>>  
>>>>>>>> all the handlers, e.g.
>>>>>>>>
>>>>>>>>   // Temporarily override the handling of DataUnavailable errors.
>>>>>>>>   factory.pushHandler( new Handler( ... ) {
>>>>>>>>       void handleJavaObjectUnavailable(...) {
>>>>>>>>           // handling specific for JavaObjects
>>>>>>>>       }
>>>>>>>>       void handleDataUnavailable(...) {
>>>>>>>>           // handling for all other DataUnavailable conditions
>>>>>>>>       }
>>>>>>>>       // All handler methods not overridden will simply call 
>>>>>>>> the same
>>>>>>>> method
>>>>>>>>       // for the object beneath us on the stack.  If we get to the
>>>>>>>>           
>>>> bottom,
>>>>  
>>>>>>>> the
>>>>>>>>       // handler there will throw an exception.
>>>>>>>>   } );
>>>>>>>>   // Do some work that might cause an exception.  This might 
>>>>>>>> include
>>>>>>>> calling
>>>>>>>>   // an independently written module that also wants to 
>>>>>>>> temporarily
>>>>>>>> override
>>>>>>>>   // some handler, but they will pop that before returning to us.
>>>>>>>>   factory.popHandler();
>>>>>>>>
>>>>>>>> Nicholas
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>        
>>>>>>>>> -- Daniel --,
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>          
>>>>>>>>>> Daniel Julin wrote:
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>            
>>>>>>>>>>> I guess a two mode approach would make everyone happy. But 
>>>>>>>>>>> would
>>>>>>>>>>>                 
>>>> it
>>>>  
>>>>>>>>>>>
>>>>>>>>>>>                 
>>>>>>>>>> make
>>>>>>>>>>
>>>>>>>>>>               the API too complicated?
>>>>>>>>>>
>>>>>>>>>>            
>>>>>>>>>>>
>>>>>>>>>>>                 
>>>>>>>>>> I have some sympathy for what Steve is talking about -- maybe my
>>>>>>>>>> short-term memory is small, but when lots of single lines of 
>>>>>>>>>> code
>>>>>>>>>> inflate to 6 lines (and two indentation levels), it is 
>>>>>>>>>> definitely
>>>>>>>>>>               
>>>> harder
>>>>  
>>>>>>>>>> for me to read.  However, I wouldn't want to give up the certain
>>>>>>>>>>               
>>>> and
>>>>  
>>>>>>>>>> immediate catching of errors offered by exceptions.
>>>>>>>>>>
>>>>>>>>>> Would a mechanism like this work for the two-mode approach?
>>>>>>>>>>
>>>>>>>>>>    factory.setDataUnavailableHandler( new DataUnavailableHandler
>>>>>>>>>>               
>>>> ( ... )
>>>>  
>>>>>>>>>>
>>>>>>>>>>               
>>>>>>>>> {
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>          
>>>>>>>>>>        ...
>>>>>>>>>>    } );
>>>>>>>>>>
>>>>>>>>>> All objects created by the factory would call that object's
>>>>>>>>>> dataUnavailable() method when appropriate, passing it enough 
>>>>>>>>>> info
>>>>>>>>>>               
>>>> about
>>>>  
>>>>>>>>>> what was going on to allow the method to make interesting 
>>>>>>>>>> decisions
>>>>>>>>>> about what to do.  The default handler would always throw a
>>>>>>>>>> DataUnavailableException.
>>>>>>>>>>
>>>>>>>>>> It's hard for me to tell whether something like that would 
>>>>>>>>>> really
>>>>>>>>>> suffice in actual use.  Perhaps it would have to be 
>>>>>>>>>> finer-grained,
>>>>>>>>>>               
>>>> with
>>>>  
>>>>>>>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(),
>>>>>>>>>>               
>>>> etc.
>>>>  
>>>>>>>>>> Perhaps the defaults for those would call the more generic
>>>>>>>>>> dataUnavailable() so that you could intervene for all cases 
>>>>>>>>>> and/or
>>>>>>>>>>               
>>>> for
>>>>  
>>>>>>>>>> individual cases as desired.
>>>>>>>>>>
>>>>>>>>>> Nicholas
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>               
>>>>>>>>>             
>>>>>>       
>>>>
>>>>   
>>>

Re: Kato API javadoc - error handling

Posted by Nicholas Sterling <Ni...@Sun.COM>.

How about having visitObject return a boolean saying whether traversal 
should continue?

Nicholas


Stuart Monteith wrote:
> I think with the visitor pattern we'd have to weigh up the typical 
> usage patterns against the loss of control it implies.
> Certainly for the heap, you might typically do a linear scan as the 
> locality of objects implies nothing about their relationship to one 
> another - using a bidirectional cursor is pointless.. The loss of 
> control means that the entire heap will be scanned, regardless of what 
> occurs.
>
> I think better with examples, so say we are counting all of the 
> instances of classes, by name:
>
>
>   final Foo outside_class = ...;
>
>   HeapVisitor visitor = new HeapVisitor() {
>       HashMap<String,Long> classCount = new HashMap<String,Long>();
>       Foo inside_class = ...;
>
>       void visitObject( JavaObject obj )  {
>           // Both outside_class and inside_class are visible.
>           // Var outside_class cannot be modified, of course,
>           // but fields in the object it refers to may.
> 1         JavaClass clazz = obj.getJavaClass();
> 2         String className = clazz.getName();
>           Long count= classCount.get(className);
>                  if (count.longValue() == 0) {
>             classCount.put(className, 1);
>          } else {
>             classCount.put(className, count+1);
>          }
>       }
>
>       void handleDataUnavailable( JavaObject obj ) {
>           // Same here.
>           // If we didn't put this method here, the default
>           // would just throw a DataUnavailableException.
>       }
>            void HandleCorruptDataException(JavaObject obj) {
>       }
>   };
>
>    try{
>       JavaHeap heap = factory.getJavaHeap(...);
>    }catch(CorruptDataException e) {
>    }catch(DataUnavailableException e) {
>    }
>   heap.visit( visitor );
>
> We could get CorruptDataException at 1 and 2, one would be because of 
> the JavaObject, the other would be because of the JavaClass it 
> referred to. I would posit that the exception information should be 
> sufficient to properly report the problem in most cases as the 
> processing done in a visitor method would be to do only with the 
> object it is passed, and anything fairly close to it, such as its 
> classes and fields.
>
> Of course, how well would this work for smaller items, such as fields 
> in classes, classes in classloaders, etc.
> With fields, I tend to want to address them by name or get all of them 
> from a class.
>
>
>
> Nicholas Sterling wrote:
>> That last example, the JDBC sanitizer, is much more conventional -- 
>> there's no handler stack.  It is essentially a combination of the 
>> Template and Visitor design patterns.  The Template pattern is often 
>> applied to Java exceptions, so I don't think this would be thought of 
>> as unusual.
>>
>> Instance variables in the anonymous class would be accessible to both 
>> the method doing the work and the method handling the exceptions.  
>> And the class could access final variables outside it:
>>
>>    final Foo outside_class = ...;
>>
>>    HeapVisitor visitor = new HeapVisitor() {
>>
>>        Foo inside_class = ...;
>>
>>        void visitObject( JavaObject obj ) {
>>            // Both outside_class and inside_class are visible.
>>            // Var outside_class cannot be modified, of course,
>>            // but fields in the object it refers to may.
>>        }
>>
>>        void handleDataUnavailable( JavaObject obj ) {
>>            // Same here.
>>            // If we didn't put this method here, the default
>>            // would just throw a DataUnavailableException.
>>        }
>>    };
>>
>>    JavaHeap heap = factory.getJavaHeap(...);
>>    heap.visit( visitor );
>>
>> Does something like that seem reasonable?
>>
>> Nicholas
>>
>>
>>
>> Daniel Julin wrote:
>>> It seems to me that with all this discussion of polymorphic and 
>>> stackable
>>> error handlers, we're rapidly re-inventing much of the Java exception
>>> facility, and probably rediscovering a lot of the same design
>>> considerations that the original designers of that Java exception 
>>> facility
>>> faced...
>>>
>>> As far as I can tell, the one major difference is that, with Java
>>> exceptions, once an exception is thrown, the flow of control is 
>>> irrevocably
>>> interrupted and can only resume after the exception handler, not 
>>> back at
>>> the point where the exception was thrown. This means that if you do 
>>> want
>>> fine control over your errors but don't want to interrupt a whole 
>>> sequence
>>> of operations, you're forced to put an explicit try/catch block at 
>>> every
>>> line of the program. Whereas with these proposed handlers, a single
>>> top-level handler could presumably take care of all the errors in a
>>> sequence of operations without interrupting that sequence.
>>>
>>> Is that a correct interpretation? And is there no practical way to 
>>> achieve
>>> the same effect with actual Java exceptions? Some sort of "continue"
>>> statement inside a catch block, maybe?
>>>
>>>
>>> On the other hand, one thing that Java try/catch blocks offer is 
>>> controlled
>>> access to the local variables of the method in which the try/catch 
>>> block
>>> resides, and to the private instance members of the object. The 
>>> proposed
>>> handlers, since they are executing in a separate object and a separate
>>> method, would not enjoy a similar access. Whether this limitation would
>>> prove bothersome in practice, will depend on the actual usage scenarios
>>> that we face...
>>>
>>>
>>> -- Daniel --
>>>
>>>
>>>
>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-14 05:39:40 PM:
>>>  
>>>> If we were to end up doing something like this, would we use 
>>>> checked or
>>>> unchecked exceptions?  If we use checked exceptions, the client will
>>>> still have to catch the exception or say that the method throws it.
>>>> Presumably that would defeat the purpose...
>>>>
>>>> Good idea on the comparison code.  I'm a little concerned that people
>>>> may think we are overengineering the whole exception thing; once we 
>>>> have
>>>> the comparison code, we can run it by some folks and see whether their
>>>> brains short-circuit.
>>>>
>>>> It might be helpful as a reference point to consider an example with
>>>> another API.  I was sufficiently frustrated by the unreadability of my
>>>> JDBC clients that I wrote a pair of classes, Query and Querier, that
>>>> hide gory details, and I think it makes a big difference.  Among the
>>>> hidden are the binding of variables and iterating through result sets,
>>>> but probably the biggest benefit is from hiding the exception-handling
>>>> logic (it closes the ResultSet for you on an exception). This is 
>>>> what it
>>>> looks like to use it:
>>>>
>>>>     // Create a query to get recent bugs.
>>>>     static final Query recent_bugs_query = new Query(
>>>>         "bugs submitted against a PRODUCT in the last NUM DAYS",
>>>>         "select id, synopsis from bugs " +
>>>>        " where product = ? and date_submitted > sysdate - ?"
>>>>     );
>>>>     ...
>>>>     // Given a Connection conn and values for PRODUCT and NUM DAYS,
>>>>     // query the DB for recent bugs and display the resulting rows.
>>>>     new Querier( recent_bugs_query, conn, product, num_days ) {
>>>>         public void doRow() throws SQLException {
>>>>             System.out.println( rs.getString(1) + " " + rs.getString
>>>>     
>>> (2) );
>>>  
>>>>         }
>>>>     }
>>>>
>>>> A major benefit was getting rid of that awful doubly-nested catch 
>>>> block
>>>> (closing the ResultSet in the catch block may throw an exception, 
>>>> so it
>>>> requires its own try-catch -- gaah!).
>>>>
>>>> The default Querier throws an exception, but you can extend Querier 
>>>> and
>>>> override the handleException() method to do whatever is appropriate 
>>>> for
>>>> your app, and they use your custom Querier throughout your program, 
>>>> e.g.
>>>>
>>>>     class MyQuerier extends Querier {
>>>>         void handleException( Exception ex ) {
>>>>             ....
>>>>         }
>>>>     }
>>>>
>>>> Perhaps we could use a similar approach, for example providing a
>>>> HeapQuerier class from which clients create anonymous classes to do 
>>>> what
>>>> they want.
>>>>
>>>> Nicholas
>>>>
>>>>
>>>>
>>>> Steve Poole wrote:
>>>>   
>>>>> On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
>>>>> Nicholas.Sterling@sun.com> wrote:
>>>>>
>>>>>
>>>>>     
>>>>>> And a Handler (whatever it should really be called) would have 
>>>>>> access
>>>>>>         
>>> to
>>>  
>>>>>> the previous Handler on the stack, so it could do
>>>>>>
>>>>>>   void handleJavaObjectUnavailable(...) {
>>>>>>       // do some stuff, then defer to the guy beneath us on the 
>>>>>> stack:
>>>>>>       prevHandler().handleJavaObjectUnavailable(...);
>>>>>>   }
>>>>>> Nicholas
>>>>>>
>>>>>> This is cool -  The callback approach is sort of a half way
>>>>>>         
>>> housebetween a
>>>  
>>>>> DOM and SAX model.  It could allow us to have a default "no nulls"
>>>>>       
>>> approch
>>>  
>>>>> for an implementation but still allows for users of the API to do
>>>>>       
>>> something
>>>  
>>>>> different.
>>>>>
>>>>> I think we should create some comparison code segments to see what it
>>>>>       
>>> could
>>>  
>>>>> look like.
>>>>>
>>>>>
>>>>>     
>>>>>> Nicholas Sterling wrote:
>>>>>>
>>>>>>
>>>>>>       
>>>>>>> Daniel Julin wrote:
>>>>>>>
>>>>>>>
>>>>>>>         
>>>>>>>> I like that approach a lot, because it may also address the other
>>>>>>>>             
>>> concern
>>>  
>>>>>>>> that a proposed "default reasonable behavior" may not be 
>>>>>>>> appropriate
>>>>>>>>             
>>> for
>>>  
>>>>>>>> all usage scenarios. We could probably come-up with a variety of
>>>>>>>>             
>>> handlers
>>>  
>>>>>>>> for various common behaviors, like printing a simple error 
>>>>>>>> message,
>>>>>>>> completely ignoring the error, and lots of other creative 
>>>>>>>> responses.
>>>>>>>>
>>>>>>>> Incidentally, nothing in this discussion is particularly 
>>>>>>>> specific to
>>>>>>>>             
>>> the
>>>  
>>>>>>>> Kato API, is it? Are we saying that, in general, we don't like
>>>>>>>>             
>>> exceptions
>>>  
>>>>>>>> as the standard mechanism to report errors in Java, and that we're
>>>>>>>> inventing new patterns?  If so, have any useful patterns been
>>>>>>>>             
>>> proposed
>>>  
>>>>>>>> and
>>>>>>>> documented previously in the literature?
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>             
>>>>>>> I just looked around a little, and am only seeing suggestions 
>>>>>>> for how
>>>>>>>           
>>> the
>>>  
>>>>>>> *client* can abstract out the exception-handling logic using the
>>>>>>>           
>>> Template
>>>  
>>>>>>> design pattern.  So far I haven't seen any advice for API 
>>>>>>> designers.
>>>>>>>
>>>>>>> By the way, it occurred to me that the setter can have a generic 
>>>>>>> name
>>>>>>> because overloading will allow us to have a method for each
>>>>>>>           
>>> condition:
>>>  
>>>>>>>   factory.setHandler( new DataUnavailableHandler( ... ) {
>>>>>>>       ...
>>>>>>>   } );
>>>>>>>
>>>>>>> Also, it might make sense to push the handler on a stack rather
>>>>>>>           
>>> replace
>>>  
>>>>>>> what is there.  That will allow independent modules to modify just
>>>>>>>           
>>> that
>>>  
>>>>>>> behavior they need to and then remove those modifications when they
>>>>>>>           
>>> are no
>>>  
>>>>>>> longer needed.  It also means that we can have just one Handler
>>>>>>>           
>>>> () class for
>>>>   
>>>>>>> all the handlers, e.g.
>>>>>>>
>>>>>>>   // Temporarily override the handling of DataUnavailable errors.
>>>>>>>   factory.pushHandler( new Handler( ... ) {
>>>>>>>       void handleJavaObjectUnavailable(...) {
>>>>>>>           // handling specific for JavaObjects
>>>>>>>       }
>>>>>>>       void handleDataUnavailable(...) {
>>>>>>>           // handling for all other DataUnavailable conditions
>>>>>>>       }
>>>>>>>       // All handler methods not overridden will simply call the 
>>>>>>> same
>>>>>>> method
>>>>>>>       // for the object beneath us on the stack.  If we get to the
>>>>>>>           
>>> bottom,
>>>  
>>>>>>> the
>>>>>>>       // handler there will throw an exception.
>>>>>>>   } );
>>>>>>>   // Do some work that might cause an exception.  This might 
>>>>>>> include
>>>>>>> calling
>>>>>>>   // an independently written module that also wants to temporarily
>>>>>>> override
>>>>>>>   // some handler, but they will pop that before returning to us.
>>>>>>>   factory.popHandler();
>>>>>>>
>>>>>>> Nicholas
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>         
>>>>>>>> -- Daniel --,
>>>>>>>>
>>>>>>>>
>>>>>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>           
>>>>>>>>> Daniel Julin wrote:
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>             
>>>>>>>>>> I guess a two mode approach would make everyone happy. But would
>>>>>>>>>>                 
>>> it
>>>  
>>>>>>>>>>
>>>>>>>>>>                 
>>>>>>>>> make
>>>>>>>>>
>>>>>>>>>               the API too complicated?
>>>>>>>>>
>>>>>>>>>             
>>>>>>>>>>
>>>>>>>>>>                 
>>>>>>>>> I have some sympathy for what Steve is talking about -- maybe my
>>>>>>>>> short-term memory is small, but when lots of single lines of code
>>>>>>>>> inflate to 6 lines (and two indentation levels), it is definitely
>>>>>>>>>               
>>> harder
>>>  
>>>>>>>>> for me to read.  However, I wouldn't want to give up the certain
>>>>>>>>>               
>>> and
>>>  
>>>>>>>>> immediate catching of errors offered by exceptions.
>>>>>>>>>
>>>>>>>>> Would a mechanism like this work for the two-mode approach?
>>>>>>>>>
>>>>>>>>>    factory.setDataUnavailableHandler( new DataUnavailableHandler
>>>>>>>>>               
>>> ( ... )
>>>  
>>>>>>>>>
>>>>>>>>>               
>>>>>>>> {
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>           
>>>>>>>>>        ...
>>>>>>>>>    } );
>>>>>>>>>
>>>>>>>>> All objects created by the factory would call that object's
>>>>>>>>> dataUnavailable() method when appropriate, passing it enough info
>>>>>>>>>               
>>> about
>>>  
>>>>>>>>> what was going on to allow the method to make interesting 
>>>>>>>>> decisions
>>>>>>>>> about what to do.  The default handler would always throw a
>>>>>>>>> DataUnavailableException.
>>>>>>>>>
>>>>>>>>> It's hard for me to tell whether something like that would really
>>>>>>>>> suffice in actual use.  Perhaps it would have to be 
>>>>>>>>> finer-grained,
>>>>>>>>>               
>>> with
>>>  
>>>>>>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(),
>>>>>>>>>               
>>> etc.
>>>  
>>>>>>>>> Perhaps the defaults for those would call the more generic
>>>>>>>>> dataUnavailable() so that you could intervene for all cases 
>>>>>>>>> and/or
>>>>>>>>>               
>>> for
>>>  
>>>>>>>>> individual cases as desired.
>>>>>>>>>
>>>>>>>>> Nicholas
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>               
>>>>>>>>             
>>>>>       
>>>
>>>   
>>

Re: Kato API javadoc - error handling

Posted by Stuart Monteith <st...@stoo.me.uk>.

With the aim of getting to a conclusion, shall we consider the use  
cases in this discussion?

For example, with a batch job, the visitor pattern (or something like  
it) might make perfect sense.
However, if we consider the Runtime Explorer, where we have an  
interactive list of objects, the visitor pattern would not make sense.

Also, does the current API provide all of the necessary information to  
satisfy these use cases?

Can I open the discussion to the following items not in the API (some  
may be already there but implicit, others irretrievable)?:

	Generics
	Inner classes
	Thread Groups
	Annotations
	Enums
	Shared classes
	JavaStackFrame/ImageStackFrame interleaving
	local variable information
	traversal over JavaObjects that are Collections, etc.
	
Are these items absences a hindrance to the use cases?
	

Regards,
	Stuart


For instance,

On 15 Apr 2009, at 20:21, Nicholas Sterling wrote:

> I'm finding this a very useful exercise.
>
> May I suggest a couple of minor tweaks:
>
>   ObjectVisitor objVisitor = new OurObjectVisitor() {
>       boolean visitField( JavaClass clazz, JavaField field, Object
>   value ) {
>           System.out.println(
>                         obj.getID()
>               + ": "  + clazz.getName()
>               + "."   + field.getSignature()
>               + " "   + field.getName()
>               + " = " + value
>           );
>           return true;
>       }
>   };
>   HeapVisitor visitor = new OurHeapVisitor() {
>       boolean visitObject( JavaObject obj )  {
>           obj.visit(objVisitor);
>           return true;
>       }
>   };
>
> That is, a single ObjectVisitor, created beforehand, can be used  
> with each object.  Also, you probably want the object visitor to  
> extend a customized OurObjectVisitor that handles exceptions.
>
> Presumably we would want the visitors to return true, to keep  
> going.  Alternatively we could supply a stopVisiting() method which  
> the visitor could call, and not return the boolean.
>
> Nicholas
>
>
> Stuart Monteith wrote:
>> I think 1. would be rejected on the basis that errors are common.
>> However, 3. would be accepted because errors are common i.e. most  
>> of the time they are logged and ignored.
>>
>> One thing I like about the Visitor pattern is that it is never left  
>> to the caller of the API to decide under what circumstances it  
>> should stop retreiving objects, the expectation is entirely on the  
>> API implementer to be able to complete. It's not the case that the  
>> API implementer might mistakenly place the responsibility for  
>> halting onto the API caller.
>>
>> The next level to examine the Visitor pattern would be to look at  
>> JavaClass and JavaField. The example I posted was of printing out  
>> all of the fields of all of the objects on the heap. The gnarly  
>> thing about this is you have to go through getting the Object, then  
>> the class, then the field, then applying them to the object.
>>
>> Would this be sensible?:
>>
>> interface ObjectVisitor {
>>   public void visitField(JavaClass clazz, JavaField field, Object  
>> value);
>> }
>>
>>      HeapVisitor visitor = new _OurHeapVisitor_() {
>>          boolean visitObject( JavaObject obj )   
>> {                        ObjectVisitor objVisitor = new  
>> ObjectVisitor() {
>>                  public void visitField(JavaClass clazz, JavaField  
>> field, Object value) {
>>                     System.out.println(obj.getID()+":  
>> "+clazz.getName()+"."+field.getSignature()+" "+field.getName()+" =  
>> "+value);
>>                  }
>>              };
>>              obj.visit(objVisitor);
>>          }
>>      };
>>
>>
>>
>> Nicholas Sterling wrote:
>>>>>>>>

Re: Kato API javadoc - error handling

Posted by Nicholas Sterling <Ni...@Sun.COM>.

I'm finding this a very useful exercise.

May I suggest a couple of minor tweaks:

    ObjectVisitor objVisitor = new OurObjectVisitor() {
        boolean visitField( JavaClass clazz, JavaField field, Object
    value ) {
            System.out.println(
                          obj.getID()
                + ": "  + clazz.getName()
                + "."   + field.getSignature()
                + " "   + field.getName()
                + " = " + value
            );
            return true;
        }
    };
    HeapVisitor visitor = new OurHeapVisitor() {
        boolean visitObject( JavaObject obj )  {
            obj.visit(objVisitor);
            return true;
        }
    };

That is, a single ObjectVisitor, created beforehand, can be used with 
each object.  Also, you probably want the object visitor to extend a 
customized OurObjectVisitor that handles exceptions.

Presumably we would want the visitors to return true, to keep going.  
Alternatively we could supply a stopVisiting() method which the visitor 
could call, and not return the boolean.

Nicholas


Stuart Monteith wrote:
> I think 1. would be rejected on the basis that errors are common.
> However, 3. would be accepted because errors are common i.e. most of 
> the time they are logged and ignored.
>
> One thing I like about the Visitor pattern is that it is never left to 
> the caller of the API to decide under what circumstances it should 
> stop retreiving objects, the expectation is entirely on the API 
> implementer to be able to complete. It's not the case that the API 
> implementer might mistakenly place the responsibility for halting onto 
> the API caller.
>
> The next level to examine the Visitor pattern would be to look at 
> JavaClass and JavaField. The example I posted was of printing out all 
> of the fields of all of the objects on the heap. The gnarly thing 
> about this is you have to go through getting the Object, then the 
> class, then the field, then applying them to the object.
>
> Would this be sensible?:
>
> interface ObjectVisitor {
>    public void visitField(JavaClass clazz, JavaField field, Object 
> value);
> }
>
>       HeapVisitor visitor = new _OurHeapVisitor_() {
>           boolean visitObject( JavaObject obj )  {           
>              ObjectVisitor objVisitor = new ObjectVisitor() {
>                   public void visitField(JavaClass clazz, JavaField 
> field, Object value) {
>                      System.out.println(obj.getID()+": 
> "+clazz.getName()+"."+field.getSignature()+" "+field.getName()+" = 
> "+value);
>                   }
>               };
>               obj.visit(objVisitor);
>           }
>       };
>
>
>
> Nicholas Sterling wrote:
>> I was just looking closer at the example code, and wondering about 
>> the location of the try-catch.  Just to make sure we're on the same 
>> page, I'd like to throw out some different possibilities for the way 
>> you would actually handle exceptions using the visitor approach.
>>
>> 1. Here we (probably unwisely) use the traditional approach, and 
>> abort heap traversal if there is an error of any kind:
>>
>>    void doObjects() {
>>
>>        HeapVisitor visitor = new HeapVisitor() {
>>            boolean visitObject( JavaObject obj )  {
>>                // do something; return true to keep going
>>            }
>>        };
>>
>>        try{
>>            JavaHeap heap = factory.getJavaHeap(...);
>>            heap.visit( visitor );
>>        } catch ( CorruptDataException e ) {
>>            ...
>>        } catch ( DataUnavailableException e ) {
>>            ...
>>        }
>>    }
>>
>> 2. Here we handle the error inside the visitor and keep going:
>>
>>    void doObjects() _throws KatoException_ {
>>
>>        HeapVisitor visitor = new HeapVisitor() {
>>            boolean visitObject( JavaObject obj )  {
>>                // do something; return true to keep going
>>            }
>>            void handleDataUnavailable( JavaObject obj ) {
>>                ...
>>            }
>>            void HandleCorruptDataException(JavaObject obj) {
>>                ...
>>            }
>>        };
>>
>>        JavaHeap heap = factory.getJavaHeap(...);
>>        heap.visit( visitor );
>>    }
>>
>> 3. Here we abstract out that error-handling into a subclass of 
>> HeapVisitor:
>>
>>    class OurHeapVisitor extends HeapVisitor {
>>            void handleDataUnavailable( JavaObject obj ) {
>>                ...
>>            }
>>            void HandleCorruptDataException(JavaObject obj) {
>>                ...
>>            }
>>    }
>>    ------------------------------------------------------------
>>    void doObjects() _throws KatoException_ {
>>
>>        HeapVisitor visitor = new _OurHeapVisitor_() {
>>            boolean visitObject( JavaObject obj )  {
>>                // do something; return true to keep going
>>            }
>>        };
>>
>>        JavaHeap heap = factory.getJavaHeap(...);
>>        heap.visit( visitor );
>>    }
>>
>> This third one, in particular, is highly readable.
>>
>> Nicholas
>>
>>
>> Stuart Monteith wrote:
>>> I think with the visitor pattern we'd have to weigh up the typical 
>>> usage patterns against the loss of control it implies.
>>> Certainly for the heap, you might typically do a linear scan as the 
>>> locality of objects implies nothing about their relationship to one 
>>> another - using a bidirectional cursor is pointless.. The loss of 
>>> control means that the entire heap will be scanned, regardless of 
>>> what occurs.
>>>
>>> I think better with examples, so say we are counting all of the 
>>> instances of classes, by name:
>>>
>>>
>>>   final Foo outside_class = ...;
>>>
>>>   HeapVisitor visitor = new HeapVisitor() {
>>>       HashMap<String,Long> classCount = new HashMap<String,Long>();
>>>       Foo inside_class = ...;
>>>
>>>       void visitObject( JavaObject obj )  {
>>>           // Both outside_class and inside_class are visible.
>>>           // Var outside_class cannot be modified, of course,
>>>           // but fields in the object it refers to may.
>>> 1         JavaClass clazz = obj.getJavaClass();
>>> 2         String className = clazz.getName();
>>>           Long count= classCount.get(className);
>>>                  if (count.longValue() == 0) {
>>>             classCount.put(className, 1);
>>>          } else {
>>>             classCount.put(className, count+1);
>>>          }
>>>       }
>>>
>>>       void handleDataUnavailable( JavaObject obj ) {
>>>           // Same here.
>>>           // If we didn't put this method here, the default
>>>           // would just throw a DataUnavailableException.
>>>       }
>>>            void HandleCorruptDataException(JavaObject obj) {
>>>       }
>>>   };
>>>
>>>    try{
>>>       JavaHeap heap = factory.getJavaHeap(...);
>>>    }catch(CorruptDataException e) {
>>>    }catch(DataUnavailableException e) {
>>>    }
>>>   heap.visit( visitor );
>>>
>>> We could get CorruptDataException at 1 and 2, one would be because 
>>> of the JavaObject, the other would be because of the JavaClass it 
>>> referred to. I would posit that the exception information should be 
>>> sufficient to properly report the problem in most cases as the 
>>> processing done in a visitor method would be to do only with the 
>>> object it is passed, and anything fairly close to it, such as its 
>>> classes and fields.
>>>
>>> Of course, how well would this work for smaller items, such as 
>>> fields in classes, classes in classloaders, etc.
>>> With fields, I tend to want to address them by name or get all of 
>>> them from a class.
>>>
>>>
>>>
>>> Nicholas Sterling wrote:
>>>> That last example, the JDBC sanitizer, is much more conventional -- 
>>>> there's no handler stack.  It is essentially a combination of the 
>>>> Template and Visitor design patterns.  The Template pattern is 
>>>> often applied to Java exceptions, so I don't think this would be 
>>>> thought of as unusual.
>>>>
>>>> Instance variables in the anonymous class would be accessible to 
>>>> both the method doing the work and the method handling the 
>>>> exceptions.  And the class could access final variables outside it:
>>>>
>>>>    final Foo outside_class = ...;
>>>>
>>>>    HeapVisitor visitor = new HeapVisitor() {
>>>>
>>>>        Foo inside_class = ...;
>>>>
>>>>        void visitObject( JavaObject obj ) {
>>>>            // Both outside_class and inside_class are visible.
>>>>            // Var outside_class cannot be modified, of course,
>>>>            // but fields in the object it refers to may.
>>>>        }
>>>>
>>>>        void handleDataUnavailable( JavaObject obj ) {
>>>>            // Same here.
>>>>            // If we didn't put this method here, the default
>>>>            // would just throw a DataUnavailableException.
>>>>        }
>>>>    };
>>>>
>>>>    JavaHeap heap = factory.getJavaHeap(...);
>>>>    heap.visit( visitor );
>>>>
>>>> Does something like that seem reasonable?
>>>>
>>>> Nicholas
>>>>
>>>>
>>>>
>>>> Daniel Julin wrote:
>>>>> It seems to me that with all this discussion of polymorphic and 
>>>>> stackable
>>>>> error handlers, we're rapidly re-inventing much of the Java exception
>>>>> facility, and probably rediscovering a lot of the same design
>>>>> considerations that the original designers of that Java exception 
>>>>> facility
>>>>> faced...
>>>>>
>>>>> As far as I can tell, the one major difference is that, with Java
>>>>> exceptions, once an exception is thrown, the flow of control is 
>>>>> irrevocably
>>>>> interrupted and can only resume after the exception handler, not 
>>>>> back at
>>>>> the point where the exception was thrown. This means that if you 
>>>>> do want
>>>>> fine control over your errors but don't want to interrupt a whole 
>>>>> sequence
>>>>> of operations, you're forced to put an explicit try/catch block at 
>>>>> every
>>>>> line of the program. Whereas with these proposed handlers, a single
>>>>> top-level handler could presumably take care of all the errors in a
>>>>> sequence of operations without interrupting that sequence.
>>>>>
>>>>> Is that a correct interpretation? And is there no practical way to 
>>>>> achieve
>>>>> the same effect with actual Java exceptions? Some sort of "continue"
>>>>> statement inside a catch block, maybe?
>>>>>
>>>>>
>>>>> On the other hand, one thing that Java try/catch blocks offer is 
>>>>> controlled
>>>>> access to the local variables of the method in which the try/catch 
>>>>> block
>>>>> resides, and to the private instance members of the object. The 
>>>>> proposed
>>>>> handlers, since they are executing in a separate object and a 
>>>>> separate
>>>>> method, would not enjoy a similar access. Whether this limitation 
>>>>> would
>>>>> prove bothersome in practice, will depend on the actual usage 
>>>>> scenarios
>>>>> that we face...
>>>>>
>>>>>
>>>>> -- Daniel --
>>>>>
>>>>>
>>>>>
>>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-14 05:39:40 PM:
>>>>>  
>>>>>> If we were to end up doing something like this, would we use 
>>>>>> checked or
>>>>>> unchecked exceptions?  If we use checked exceptions, the client will
>>>>>> still have to catch the exception or say that the method throws it.
>>>>>> Presumably that would defeat the purpose...
>>>>>>
>>>>>> Good idea on the comparison code.  I'm a little concerned that 
>>>>>> people
>>>>>> may think we are overengineering the whole exception thing; once 
>>>>>> we have
>>>>>> the comparison code, we can run it by some folks and see whether 
>>>>>> their
>>>>>> brains short-circuit.
>>>>>>
>>>>>> It might be helpful as a reference point to consider an example with
>>>>>> another API.  I was sufficiently frustrated by the unreadability 
>>>>>> of my
>>>>>> JDBC clients that I wrote a pair of classes, Query and Querier, that
>>>>>> hide gory details, and I think it makes a big difference.  Among the
>>>>>> hidden are the binding of variables and iterating through result 
>>>>>> sets,
>>>>>> but probably the biggest benefit is from hiding the 
>>>>>> exception-handling
>>>>>> logic (it closes the ResultSet for you on an exception). This is 
>>>>>> what it
>>>>>> looks like to use it:
>>>>>>
>>>>>>     // Create a query to get recent bugs.
>>>>>>     static final Query recent_bugs_query = new Query(
>>>>>>         "bugs submitted against a PRODUCT in the last NUM DAYS",
>>>>>>         "select id, synopsis from bugs " +
>>>>>>        " where product = ? and date_submitted > sysdate - ?"
>>>>>>     );
>>>>>>     ...
>>>>>>     // Given a Connection conn and values for PRODUCT and NUM DAYS,
>>>>>>     // query the DB for recent bugs and display the resulting rows.
>>>>>>     new Querier( recent_bugs_query, conn, product, num_days ) {
>>>>>>         public void doRow() throws SQLException {
>>>>>>             System.out.println( rs.getString(1) + " " + rs.getString
>>>>>>     
>>>>> (2) );
>>>>>  
>>>>>>         }
>>>>>>     }
>>>>>>
>>>>>> A major benefit was getting rid of that awful doubly-nested catch 
>>>>>> block
>>>>>> (closing the ResultSet in the catch block may throw an exception, 
>>>>>> so it
>>>>>> requires its own try-catch -- gaah!).
>>>>>>
>>>>>> The default Querier throws an exception, but you can extend 
>>>>>> Querier and
>>>>>> override the handleException() method to do whatever is 
>>>>>> appropriate for
>>>>>> your app, and they use your custom Querier throughout your 
>>>>>> program, e.g.
>>>>>>
>>>>>>     class MyQuerier extends Querier {
>>>>>>         void handleException( Exception ex ) {
>>>>>>             ....
>>>>>>         }
>>>>>>     }
>>>>>>
>>>>>> Perhaps we could use a similar approach, for example providing a
>>>>>> HeapQuerier class from which clients create anonymous classes to 
>>>>>> do what
>>>>>> they want.
>>>>>>
>>>>>> Nicholas
>>>>>>
>>>>>>
>>>>>>
>>>>>> Steve Poole wrote:
>>>>>>  
>>>>>>> On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
>>>>>>> Nicholas.Sterling@sun.com> wrote:
>>>>>>>
>>>>>>>
>>>>>>>   
>>>>>>>> And a Handler (whatever it should really be called) would have 
>>>>>>>> access
>>>>>>>>         
>>>>> to
>>>>>  
>>>>>>>> the previous Handler on the stack, so it could do
>>>>>>>>
>>>>>>>>   void handleJavaObjectUnavailable(...) {
>>>>>>>>       // do some stuff, then defer to the guy beneath us on the 
>>>>>>>> stack:
>>>>>>>>       prevHandler().handleJavaObjectUnavailable(...);
>>>>>>>>   }
>>>>>>>> Nicholas
>>>>>>>>
>>>>>>>> This is cool -  The callback approach is sort of a half way
>>>>>>>>         
>>>>> housebetween a
>>>>>  
>>>>>>> DOM and SAX model.  It could allow us to have a default "no nulls"
>>>>>>>       
>>>>> approch
>>>>>  
>>>>>>> for an implementation but still allows for users of the API to do
>>>>>>>       
>>>>> something
>>>>>  
>>>>>>> different.
>>>>>>>
>>>>>>> I think we should create some comparison code segments to see 
>>>>>>> what it
>>>>>>>       
>>>>> could
>>>>>  
>>>>>>> look like.
>>>>>>>
>>>>>>>
>>>>>>>   
>>>>>>>> Nicholas Sterling wrote:
>>>>>>>>
>>>>>>>>
>>>>>>>>     
>>>>>>>>> Daniel Julin wrote:
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>       
>>>>>>>>>> I like that approach a lot, because it may also address the 
>>>>>>>>>> other
>>>>>>>>>>             
>>>>> concern
>>>>>  
>>>>>>>>>> that a proposed "default reasonable behavior" may not be 
>>>>>>>>>> appropriate
>>>>>>>>>>             
>>>>> for
>>>>>  
>>>>>>>>>> all usage scenarios. We could probably come-up with a variety of
>>>>>>>>>>             
>>>>> handlers
>>>>>  
>>>>>>>>>> for various common behaviors, like printing a simple error 
>>>>>>>>>> message,
>>>>>>>>>> completely ignoring the error, and lots of other creative 
>>>>>>>>>> responses.
>>>>>>>>>>
>>>>>>>>>> Incidentally, nothing in this discussion is particularly 
>>>>>>>>>> specific to
>>>>>>>>>>             
>>>>> the
>>>>>  
>>>>>>>>>> Kato API, is it? Are we saying that, in general, we don't like
>>>>>>>>>>             
>>>>> exceptions
>>>>>  
>>>>>>>>>> as the standard mechanism to report errors in Java, and that 
>>>>>>>>>> we're
>>>>>>>>>> inventing new patterns?  If so, have any useful patterns been
>>>>>>>>>>             
>>>>> proposed
>>>>>  
>>>>>>>>>> and
>>>>>>>>>> documented previously in the literature?
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>             
>>>>>>>>> I just looked around a little, and am only seeing suggestions 
>>>>>>>>> for how
>>>>>>>>>           
>>>>> the
>>>>>  
>>>>>>>>> *client* can abstract out the exception-handling logic using the
>>>>>>>>>           
>>>>> Template
>>>>>  
>>>>>>>>> design pattern.  So far I haven't seen any advice for API 
>>>>>>>>> designers.
>>>>>>>>>
>>>>>>>>> By the way, it occurred to me that the setter can have a 
>>>>>>>>> generic name
>>>>>>>>> because overloading will allow us to have a method for each
>>>>>>>>>           
>>>>> condition:
>>>>>  
>>>>>>>>>   factory.setHandler( new DataUnavailableHandler( ... ) {
>>>>>>>>>       ...
>>>>>>>>>   } );
>>>>>>>>>
>>>>>>>>> Also, it might make sense to push the handler on a stack rather
>>>>>>>>>           
>>>>> replace
>>>>>  
>>>>>>>>> what is there.  That will allow independent modules to modify 
>>>>>>>>> just
>>>>>>>>>           
>>>>> that
>>>>>  
>>>>>>>>> behavior they need to and then remove those modifications when 
>>>>>>>>> they
>>>>>>>>>           
>>>>> are no
>>>>>  
>>>>>>>>> longer needed.  It also means that we can have just one Handler
>>>>>>>>>           
>>>>>> () class for
>>>>>>  
>>>>>>>>> all the handlers, e.g.
>>>>>>>>>
>>>>>>>>>   // Temporarily override the handling of DataUnavailable errors.
>>>>>>>>>   factory.pushHandler( new Handler( ... ) {
>>>>>>>>>       void handleJavaObjectUnavailable(...) {
>>>>>>>>>           // handling specific for JavaObjects
>>>>>>>>>       }
>>>>>>>>>       void handleDataUnavailable(...) {
>>>>>>>>>           // handling for all other DataUnavailable conditions
>>>>>>>>>       }
>>>>>>>>>       // All handler methods not overridden will simply call 
>>>>>>>>> the same
>>>>>>>>> method
>>>>>>>>>       // for the object beneath us on the stack.  If we get to 
>>>>>>>>> the
>>>>>>>>>           
>>>>> bottom,
>>>>>  
>>>>>>>>> the
>>>>>>>>>       // handler there will throw an exception.
>>>>>>>>>   } );
>>>>>>>>>   // Do some work that might cause an exception.  This might 
>>>>>>>>> include
>>>>>>>>> calling
>>>>>>>>>   // an independently written module that also wants to 
>>>>>>>>> temporarily
>>>>>>>>> override
>>>>>>>>>   // some handler, but they will pop that before returning to us.
>>>>>>>>>   factory.popHandler();
>>>>>>>>>
>>>>>>>>> Nicholas
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>       
>>>>>>>>>> -- Daniel --,
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>         
>>>>>>>>>>> Daniel Julin wrote:
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>           
>>>>>>>>>>>> I guess a two mode approach would make everyone happy. But 
>>>>>>>>>>>> would
>>>>>>>>>>>>                 
>>>>> it
>>>>>  
>>>>>>>>>>>>
>>>>>>>>>>>>                 
>>>>>>>>>>> make
>>>>>>>>>>>
>>>>>>>>>>>               the API too complicated?
>>>>>>>>>>>
>>>>>>>>>>>           
>>>>>>>>>>>>
>>>>>>>>>>>>                 
>>>>>>>>>>> I have some sympathy for what Steve is talking about -- 
>>>>>>>>>>> maybe my
>>>>>>>>>>> short-term memory is small, but when lots of single lines of 
>>>>>>>>>>> code
>>>>>>>>>>> inflate to 6 lines (and two indentation levels), it is 
>>>>>>>>>>> definitely
>>>>>>>>>>>               
>>>>> harder
>>>>>  
>>>>>>>>>>> for me to read.  However, I wouldn't want to give up the 
>>>>>>>>>>> certain
>>>>>>>>>>>               
>>>>> and
>>>>>  
>>>>>>>>>>> immediate catching of errors offered by exceptions.
>>>>>>>>>>>
>>>>>>>>>>> Would a mechanism like this work for the two-mode approach?
>>>>>>>>>>>
>>>>>>>>>>>    factory.setDataUnavailableHandler( new 
>>>>>>>>>>> DataUnavailableHandler
>>>>>>>>>>>               
>>>>> ( ... )
>>>>>  
>>>>>>>>>>>
>>>>>>>>>>>               
>>>>>>>>>> {
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>         
>>>>>>>>>>>        ...
>>>>>>>>>>>    } );
>>>>>>>>>>>
>>>>>>>>>>> All objects created by the factory would call that object's
>>>>>>>>>>> dataUnavailable() method when appropriate, passing it enough 
>>>>>>>>>>> info
>>>>>>>>>>>               
>>>>> about
>>>>>  
>>>>>>>>>>> what was going on to allow the method to make interesting 
>>>>>>>>>>> decisions
>>>>>>>>>>> about what to do.  The default handler would always throw a
>>>>>>>>>>> DataUnavailableException.
>>>>>>>>>>>
>>>>>>>>>>> It's hard for me to tell whether something like that would 
>>>>>>>>>>> really
>>>>>>>>>>> suffice in actual use.  Perhaps it would have to be 
>>>>>>>>>>> finer-grained,
>>>>>>>>>>>               
>>>>> with
>>>>>  
>>>>>>>>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(),
>>>>>>>>>>>               
>>>>> etc.
>>>>>  
>>>>>>>>>>> Perhaps the defaults for those would call the more generic
>>>>>>>>>>> dataUnavailable() so that you could intervene for all cases 
>>>>>>>>>>> and/or
>>>>>>>>>>>               
>>>>> for
>>>>>  
>>>>>>>>>>> individual cases as desired.
>>>>>>>>>>>
>>>>>>>>>>> Nicholas
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>               
>>>>>>>>>>             
>>>>>>>       
>>>>>
>>>>>   
>>>>
>>

Re: Kato API javadoc - error handling

Posted by Stuart Monteith <st...@stoo.me.uk>.

I think 1. would be rejected on the basis that errors are common.
However, 3. would be accepted because errors are common i.e. most of the 
time they are logged and ignored.

One thing I like about the Visitor pattern is that it is never left to 
the caller of the API to decide under what circumstances it should stop 
retreiving objects, the expectation is entirely on the API implementer 
to be able to complete. It's not the case that the API implementer might 
mistakenly place the responsibility for halting onto the API caller.

The next level to examine the Visitor pattern would be to look at 
JavaClass and JavaField. The example I posted was of printing out all of 
the fields of all of the objects on the heap. The gnarly thing about 
this is you have to go through getting the Object, then the class, then 
the field, then applying them to the object.

Would this be sensible?:

interface ObjectVisitor {
    public void visitField(JavaClass clazz, JavaField field, Object value);
}

       HeapVisitor visitor = new _OurHeapVisitor_() {
           boolean visitObject( JavaObject obj )  {           
              ObjectVisitor objVisitor = new ObjectVisitor() {
                   public void visitField(JavaClass clazz, JavaField 
field, Object value) {
                      System.out.println(obj.getID()+": 
"+clazz.getName()+"."+field.getSignature()+" "+field.getName()+" = "+value);
                   }
               };
               obj.visit(objVisitor);
           }
       };



Nicholas Sterling wrote:
> I was just looking closer at the example code, and wondering about the 
> location of the try-catch.  Just to make sure we're on the same page, 
> I'd like to throw out some different possibilities for the way you 
> would actually handle exceptions using the visitor approach.
>
> 1. Here we (probably unwisely) use the traditional approach, and abort 
> heap traversal if there is an error of any kind:
>
>    void doObjects() {
>
>        HeapVisitor visitor = new HeapVisitor() {
>            boolean visitObject( JavaObject obj )  {
>                // do something; return true to keep going
>            }
>        };
>
>        try{
>            JavaHeap heap = factory.getJavaHeap(...);
>            heap.visit( visitor );
>        } catch ( CorruptDataException e ) {
>            ...
>        } catch ( DataUnavailableException e ) {
>            ...
>        }
>    }
>
> 2. Here we handle the error inside the visitor and keep going:
>
>    void doObjects() _throws KatoException_ {
>
>        HeapVisitor visitor = new HeapVisitor() {
>            boolean visitObject( JavaObject obj )  {
>                // do something; return true to keep going
>            }
>            void handleDataUnavailable( JavaObject obj ) {
>                ...
>            }
>            void HandleCorruptDataException(JavaObject obj) {
>                ...
>            }
>        };
>
>        JavaHeap heap = factory.getJavaHeap(...);
>        heap.visit( visitor );
>    }
>
> 3. Here we abstract out that error-handling into a subclass of 
> HeapVisitor:
>
>    class OurHeapVisitor extends HeapVisitor {
>            void handleDataUnavailable( JavaObject obj ) {
>                ...
>            }
>            void HandleCorruptDataException(JavaObject obj) {
>                ...
>            }
>    }
>    ------------------------------------------------------------
>    void doObjects() _throws KatoException_ {
>
>        HeapVisitor visitor = new _OurHeapVisitor_() {
>            boolean visitObject( JavaObject obj )  {
>                // do something; return true to keep going
>            }
>        };
>
>        JavaHeap heap = factory.getJavaHeap(...);
>        heap.visit( visitor );
>    }
>
> This third one, in particular, is highly readable.
>
> Nicholas
>
>
> Stuart Monteith wrote:
>> I think with the visitor pattern we'd have to weigh up the typical 
>> usage patterns against the loss of control it implies.
>> Certainly for the heap, you might typically do a linear scan as the 
>> locality of objects implies nothing about their relationship to one 
>> another - using a bidirectional cursor is pointless.. The loss of 
>> control means that the entire heap will be scanned, regardless of 
>> what occurs.
>>
>> I think better with examples, so say we are counting all of the 
>> instances of classes, by name:
>>
>>
>>   final Foo outside_class = ...;
>>
>>   HeapVisitor visitor = new HeapVisitor() {
>>       HashMap<String,Long> classCount = new HashMap<String,Long>();
>>       Foo inside_class = ...;
>>
>>       void visitObject( JavaObject obj )  {
>>           // Both outside_class and inside_class are visible.
>>           // Var outside_class cannot be modified, of course,
>>           // but fields in the object it refers to may.
>> 1         JavaClass clazz = obj.getJavaClass();
>> 2         String className = clazz.getName();
>>           Long count= classCount.get(className);
>>                  if (count.longValue() == 0) {
>>             classCount.put(className, 1);
>>          } else {
>>             classCount.put(className, count+1);
>>          }
>>       }
>>
>>       void handleDataUnavailable( JavaObject obj ) {
>>           // Same here.
>>           // If we didn't put this method here, the default
>>           // would just throw a DataUnavailableException.
>>       }
>>            void HandleCorruptDataException(JavaObject obj) {
>>       }
>>   };
>>
>>    try{
>>       JavaHeap heap = factory.getJavaHeap(...);
>>    }catch(CorruptDataException e) {
>>    }catch(DataUnavailableException e) {
>>    }
>>   heap.visit( visitor );
>>
>> We could get CorruptDataException at 1 and 2, one would be because of 
>> the JavaObject, the other would be because of the JavaClass it 
>> referred to. I would posit that the exception information should be 
>> sufficient to properly report the problem in most cases as the 
>> processing done in a visitor method would be to do only with the 
>> object it is passed, and anything fairly close to it, such as its 
>> classes and fields.
>>
>> Of course, how well would this work for smaller items, such as fields 
>> in classes, classes in classloaders, etc.
>> With fields, I tend to want to address them by name or get all of 
>> them from a class.
>>
>>
>>
>> Nicholas Sterling wrote:
>>> That last example, the JDBC sanitizer, is much more conventional -- 
>>> there's no handler stack.  It is essentially a combination of the 
>>> Template and Visitor design patterns.  The Template pattern is often 
>>> applied to Java exceptions, so I don't think this would be thought 
>>> of as unusual.
>>>
>>> Instance variables in the anonymous class would be accessible to 
>>> both the method doing the work and the method handling the 
>>> exceptions.  And the class could access final variables outside it:
>>>
>>>    final Foo outside_class = ...;
>>>
>>>    HeapVisitor visitor = new HeapVisitor() {
>>>
>>>        Foo inside_class = ...;
>>>
>>>        void visitObject( JavaObject obj ) {
>>>            // Both outside_class and inside_class are visible.
>>>            // Var outside_class cannot be modified, of course,
>>>            // but fields in the object it refers to may.
>>>        }
>>>
>>>        void handleDataUnavailable( JavaObject obj ) {
>>>            // Same here.
>>>            // If we didn't put this method here, the default
>>>            // would just throw a DataUnavailableException.
>>>        }
>>>    };
>>>
>>>    JavaHeap heap = factory.getJavaHeap(...);
>>>    heap.visit( visitor );
>>>
>>> Does something like that seem reasonable?
>>>
>>> Nicholas
>>>
>>>
>>>
>>> Daniel Julin wrote:
>>>> It seems to me that with all this discussion of polymorphic and 
>>>> stackable
>>>> error handlers, we're rapidly re-inventing much of the Java exception
>>>> facility, and probably rediscovering a lot of the same design
>>>> considerations that the original designers of that Java exception 
>>>> facility
>>>> faced...
>>>>
>>>> As far as I can tell, the one major difference is that, with Java
>>>> exceptions, once an exception is thrown, the flow of control is 
>>>> irrevocably
>>>> interrupted and can only resume after the exception handler, not 
>>>> back at
>>>> the point where the exception was thrown. This means that if you do 
>>>> want
>>>> fine control over your errors but don't want to interrupt a whole 
>>>> sequence
>>>> of operations, you're forced to put an explicit try/catch block at 
>>>> every
>>>> line of the program. Whereas with these proposed handlers, a single
>>>> top-level handler could presumably take care of all the errors in a
>>>> sequence of operations without interrupting that sequence.
>>>>
>>>> Is that a correct interpretation? And is there no practical way to 
>>>> achieve
>>>> the same effect with actual Java exceptions? Some sort of "continue"
>>>> statement inside a catch block, maybe?
>>>>
>>>>
>>>> On the other hand, one thing that Java try/catch blocks offer is 
>>>> controlled
>>>> access to the local variables of the method in which the try/catch 
>>>> block
>>>> resides, and to the private instance members of the object. The 
>>>> proposed
>>>> handlers, since they are executing in a separate object and a separate
>>>> method, would not enjoy a similar access. Whether this limitation 
>>>> would
>>>> prove bothersome in practice, will depend on the actual usage 
>>>> scenarios
>>>> that we face...
>>>>
>>>>
>>>> -- Daniel --
>>>>
>>>>
>>>>
>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-14 05:39:40 PM:
>>>>  
>>>>> If we were to end up doing something like this, would we use 
>>>>> checked or
>>>>> unchecked exceptions?  If we use checked exceptions, the client will
>>>>> still have to catch the exception or say that the method throws it.
>>>>> Presumably that would defeat the purpose...
>>>>>
>>>>> Good idea on the comparison code.  I'm a little concerned that people
>>>>> may think we are overengineering the whole exception thing; once 
>>>>> we have
>>>>> the comparison code, we can run it by some folks and see whether 
>>>>> their
>>>>> brains short-circuit.
>>>>>
>>>>> It might be helpful as a reference point to consider an example with
>>>>> another API.  I was sufficiently frustrated by the unreadability 
>>>>> of my
>>>>> JDBC clients that I wrote a pair of classes, Query and Querier, that
>>>>> hide gory details, and I think it makes a big difference.  Among the
>>>>> hidden are the binding of variables and iterating through result 
>>>>> sets,
>>>>> but probably the biggest benefit is from hiding the 
>>>>> exception-handling
>>>>> logic (it closes the ResultSet for you on an exception). This is 
>>>>> what it
>>>>> looks like to use it:
>>>>>
>>>>>     // Create a query to get recent bugs.
>>>>>     static final Query recent_bugs_query = new Query(
>>>>>         "bugs submitted against a PRODUCT in the last NUM DAYS",
>>>>>         "select id, synopsis from bugs " +
>>>>>        " where product = ? and date_submitted > sysdate - ?"
>>>>>     );
>>>>>     ...
>>>>>     // Given a Connection conn and values for PRODUCT and NUM DAYS,
>>>>>     // query the DB for recent bugs and display the resulting rows.
>>>>>     new Querier( recent_bugs_query, conn, product, num_days ) {
>>>>>         public void doRow() throws SQLException {
>>>>>             System.out.println( rs.getString(1) + " " + rs.getString
>>>>>     
>>>> (2) );
>>>>  
>>>>>         }
>>>>>     }
>>>>>
>>>>> A major benefit was getting rid of that awful doubly-nested catch 
>>>>> block
>>>>> (closing the ResultSet in the catch block may throw an exception, 
>>>>> so it
>>>>> requires its own try-catch -- gaah!).
>>>>>
>>>>> The default Querier throws an exception, but you can extend 
>>>>> Querier and
>>>>> override the handleException() method to do whatever is 
>>>>> appropriate for
>>>>> your app, and they use your custom Querier throughout your 
>>>>> program, e.g.
>>>>>
>>>>>     class MyQuerier extends Querier {
>>>>>         void handleException( Exception ex ) {
>>>>>             ....
>>>>>         }
>>>>>     }
>>>>>
>>>>> Perhaps we could use a similar approach, for example providing a
>>>>> HeapQuerier class from which clients create anonymous classes to 
>>>>> do what
>>>>> they want.
>>>>>
>>>>> Nicholas
>>>>>
>>>>>
>>>>>
>>>>> Steve Poole wrote:
>>>>>  
>>>>>> On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
>>>>>> Nicholas.Sterling@sun.com> wrote:
>>>>>>
>>>>>>
>>>>>>    
>>>>>>> And a Handler (whatever it should really be called) would have 
>>>>>>> access
>>>>>>>         
>>>> to
>>>>  
>>>>>>> the previous Handler on the stack, so it could do
>>>>>>>
>>>>>>>   void handleJavaObjectUnavailable(...) {
>>>>>>>       // do some stuff, then defer to the guy beneath us on the 
>>>>>>> stack:
>>>>>>>       prevHandler().handleJavaObjectUnavailable(...);
>>>>>>>   }
>>>>>>> Nicholas
>>>>>>>
>>>>>>> This is cool -  The callback approach is sort of a half way
>>>>>>>         
>>>> housebetween a
>>>>  
>>>>>> DOM and SAX model.  It could allow us to have a default "no nulls"
>>>>>>       
>>>> approch
>>>>  
>>>>>> for an implementation but still allows for users of the API to do
>>>>>>       
>>>> something
>>>>  
>>>>>> different.
>>>>>>
>>>>>> I think we should create some comparison code segments to see 
>>>>>> what it
>>>>>>       
>>>> could
>>>>  
>>>>>> look like.
>>>>>>
>>>>>>
>>>>>>    
>>>>>>> Nicholas Sterling wrote:
>>>>>>>
>>>>>>>
>>>>>>>      
>>>>>>>> Daniel Julin wrote:
>>>>>>>>
>>>>>>>>
>>>>>>>>        
>>>>>>>>> I like that approach a lot, because it may also address the other
>>>>>>>>>             
>>>> concern
>>>>  
>>>>>>>>> that a proposed "default reasonable behavior" may not be 
>>>>>>>>> appropriate
>>>>>>>>>             
>>>> for
>>>>  
>>>>>>>>> all usage scenarios. We could probably come-up with a variety of
>>>>>>>>>             
>>>> handlers
>>>>  
>>>>>>>>> for various common behaviors, like printing a simple error 
>>>>>>>>> message,
>>>>>>>>> completely ignoring the error, and lots of other creative 
>>>>>>>>> responses.
>>>>>>>>>
>>>>>>>>> Incidentally, nothing in this discussion is particularly 
>>>>>>>>> specific to
>>>>>>>>>             
>>>> the
>>>>  
>>>>>>>>> Kato API, is it? Are we saying that, in general, we don't like
>>>>>>>>>             
>>>> exceptions
>>>>  
>>>>>>>>> as the standard mechanism to report errors in Java, and that 
>>>>>>>>> we're
>>>>>>>>> inventing new patterns?  If so, have any useful patterns been
>>>>>>>>>             
>>>> proposed
>>>>  
>>>>>>>>> and
>>>>>>>>> documented previously in the literature?
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>             
>>>>>>>> I just looked around a little, and am only seeing suggestions 
>>>>>>>> for how
>>>>>>>>           
>>>> the
>>>>  
>>>>>>>> *client* can abstract out the exception-handling logic using the
>>>>>>>>           
>>>> Template
>>>>  
>>>>>>>> design pattern.  So far I haven't seen any advice for API 
>>>>>>>> designers.
>>>>>>>>
>>>>>>>> By the way, it occurred to me that the setter can have a 
>>>>>>>> generic name
>>>>>>>> because overloading will allow us to have a method for each
>>>>>>>>           
>>>> condition:
>>>>  
>>>>>>>>   factory.setHandler( new DataUnavailableHandler( ... ) {
>>>>>>>>       ...
>>>>>>>>   } );
>>>>>>>>
>>>>>>>> Also, it might make sense to push the handler on a stack rather
>>>>>>>>           
>>>> replace
>>>>  
>>>>>>>> what is there.  That will allow independent modules to modify just
>>>>>>>>           
>>>> that
>>>>  
>>>>>>>> behavior they need to and then remove those modifications when 
>>>>>>>> they
>>>>>>>>           
>>>> are no
>>>>  
>>>>>>>> longer needed.  It also means that we can have just one Handler
>>>>>>>>           
>>>>> () class for
>>>>>  
>>>>>>>> all the handlers, e.g.
>>>>>>>>
>>>>>>>>   // Temporarily override the handling of DataUnavailable errors.
>>>>>>>>   factory.pushHandler( new Handler( ... ) {
>>>>>>>>       void handleJavaObjectUnavailable(...) {
>>>>>>>>           // handling specific for JavaObjects
>>>>>>>>       }
>>>>>>>>       void handleDataUnavailable(...) {
>>>>>>>>           // handling for all other DataUnavailable conditions
>>>>>>>>       }
>>>>>>>>       // All handler methods not overridden will simply call 
>>>>>>>> the same
>>>>>>>> method
>>>>>>>>       // for the object beneath us on the stack.  If we get to the
>>>>>>>>           
>>>> bottom,
>>>>  
>>>>>>>> the
>>>>>>>>       // handler there will throw an exception.
>>>>>>>>   } );
>>>>>>>>   // Do some work that might cause an exception.  This might 
>>>>>>>> include
>>>>>>>> calling
>>>>>>>>   // an independently written module that also wants to 
>>>>>>>> temporarily
>>>>>>>> override
>>>>>>>>   // some handler, but they will pop that before returning to us.
>>>>>>>>   factory.popHandler();
>>>>>>>>
>>>>>>>> Nicholas
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>        
>>>>>>>>> -- Daniel --,
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>          
>>>>>>>>>> Daniel Julin wrote:
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>            
>>>>>>>>>>> I guess a two mode approach would make everyone happy. But 
>>>>>>>>>>> would
>>>>>>>>>>>                 
>>>> it
>>>>  
>>>>>>>>>>>
>>>>>>>>>>>                 
>>>>>>>>>> make
>>>>>>>>>>
>>>>>>>>>>               the API too complicated?
>>>>>>>>>>
>>>>>>>>>>            
>>>>>>>>>>>
>>>>>>>>>>>                 
>>>>>>>>>> I have some sympathy for what Steve is talking about -- maybe my
>>>>>>>>>> short-term memory is small, but when lots of single lines of 
>>>>>>>>>> code
>>>>>>>>>> inflate to 6 lines (and two indentation levels), it is 
>>>>>>>>>> definitely
>>>>>>>>>>               
>>>> harder
>>>>  
>>>>>>>>>> for me to read.  However, I wouldn't want to give up the certain
>>>>>>>>>>               
>>>> and
>>>>  
>>>>>>>>>> immediate catching of errors offered by exceptions.
>>>>>>>>>>
>>>>>>>>>> Would a mechanism like this work for the two-mode approach?
>>>>>>>>>>
>>>>>>>>>>    factory.setDataUnavailableHandler( new DataUnavailableHandler
>>>>>>>>>>               
>>>> ( ... )
>>>>  
>>>>>>>>>>
>>>>>>>>>>               
>>>>>>>>> {
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>          
>>>>>>>>>>        ...
>>>>>>>>>>    } );
>>>>>>>>>>
>>>>>>>>>> All objects created by the factory would call that object's
>>>>>>>>>> dataUnavailable() method when appropriate, passing it enough 
>>>>>>>>>> info
>>>>>>>>>>               
>>>> about
>>>>  
>>>>>>>>>> what was going on to allow the method to make interesting 
>>>>>>>>>> decisions
>>>>>>>>>> about what to do.  The default handler would always throw a
>>>>>>>>>> DataUnavailableException.
>>>>>>>>>>
>>>>>>>>>> It's hard for me to tell whether something like that would 
>>>>>>>>>> really
>>>>>>>>>> suffice in actual use.  Perhaps it would have to be 
>>>>>>>>>> finer-grained,
>>>>>>>>>>               
>>>> with
>>>>  
>>>>>>>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(),
>>>>>>>>>>               
>>>> etc.
>>>>  
>>>>>>>>>> Perhaps the defaults for those would call the more generic
>>>>>>>>>> dataUnavailable() so that you could intervene for all cases 
>>>>>>>>>> and/or
>>>>>>>>>>               
>>>> for
>>>>  
>>>>>>>>>> individual cases as desired.
>>>>>>>>>>
>>>>>>>>>> Nicholas
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>               
>>>>>>>>>             
>>>>>>       
>>>>
>>>>   
>>>
>

Re: Kato API javadoc - error handling

Posted by Nicholas Sterling <Ni...@Sun.COM>.

I was just looking closer at the example code, and wondering about the 
location of the try-catch.  Just to make sure we're on the same page, 
I'd like to throw out some different possibilities for the way you would 
actually handle exceptions using the visitor approach.

1. Here we (probably unwisely) use the traditional approach, and abort 
heap traversal if there is an error of any kind:

    void doObjects() {

        HeapVisitor visitor = new HeapVisitor() {
            boolean visitObject( JavaObject obj )  {
                // do something; return true to keep going
            }
        };

        try{
            JavaHeap heap = factory.getJavaHeap(...);
            heap.visit( visitor );
        } catch ( CorruptDataException e ) {
            ...
        } catch ( DataUnavailableException e ) {
            ...
        }
    }

2. Here we handle the error inside the visitor and keep going:

    void doObjects() _throws KatoException_ {

        HeapVisitor visitor = new HeapVisitor() {
            boolean visitObject( JavaObject obj )  {
                // do something; return true to keep going
            }
            void handleDataUnavailable( JavaObject obj ) {
                ...
            }
            void HandleCorruptDataException(JavaObject obj) {
                ...
            }
        };

        JavaHeap heap = factory.getJavaHeap(...);
        heap.visit( visitor );
    }

3. Here we abstract out that error-handling into a subclass of HeapVisitor:

    class OurHeapVisitor extends HeapVisitor {
            void handleDataUnavailable( JavaObject obj ) {
                ...
            }
            void HandleCorruptDataException(JavaObject obj) {
                ...
            }
    }
    ------------------------------------------------------------
    void doObjects() _throws KatoException_ {

        HeapVisitor visitor = new _OurHeapVisitor_() {
            boolean visitObject( JavaObject obj )  {
                // do something; return true to keep going
            }
        };

        JavaHeap heap = factory.getJavaHeap(...);
        heap.visit( visitor );
    }

This third one, in particular, is highly readable.

Nicholas


Stuart Monteith wrote:
> I think with the visitor pattern we'd have to weigh up the typical 
> usage patterns against the loss of control it implies.
> Certainly for the heap, you might typically do a linear scan as the 
> locality of objects implies nothing about their relationship to one 
> another - using a bidirectional cursor is pointless.. The loss of 
> control means that the entire heap will be scanned, regardless of what 
> occurs.
>
> I think better with examples, so say we are counting all of the 
> instances of classes, by name:
>
>
>   final Foo outside_class = ...;
>
>   HeapVisitor visitor = new HeapVisitor() {
>       HashMap<String,Long> classCount = new HashMap<String,Long>();
>       Foo inside_class = ...;
>
>       void visitObject( JavaObject obj )  {
>           // Both outside_class and inside_class are visible.
>           // Var outside_class cannot be modified, of course,
>           // but fields in the object it refers to may.
> 1         JavaClass clazz = obj.getJavaClass();
> 2         String className = clazz.getName();
>           Long count= classCount.get(className);
>                  if (count.longValue() == 0) {
>             classCount.put(className, 1);
>          } else {
>             classCount.put(className, count+1);
>          }
>       }
>
>       void handleDataUnavailable( JavaObject obj ) {
>           // Same here.
>           // If we didn't put this method here, the default
>           // would just throw a DataUnavailableException.
>       }
>            void HandleCorruptDataException(JavaObject obj) {
>       }
>   };
>
>    try{
>       JavaHeap heap = factory.getJavaHeap(...);
>    }catch(CorruptDataException e) {
>    }catch(DataUnavailableException e) {
>    }
>   heap.visit( visitor );
>
> We could get CorruptDataException at 1 and 2, one would be because of 
> the JavaObject, the other would be because of the JavaClass it 
> referred to. I would posit that the exception information should be 
> sufficient to properly report the problem in most cases as the 
> processing done in a visitor method would be to do only with the 
> object it is passed, and anything fairly close to it, such as its 
> classes and fields.
>
> Of course, how well would this work for smaller items, such as fields 
> in classes, classes in classloaders, etc.
> With fields, I tend to want to address them by name or get all of them 
> from a class.
>
>
>
> Nicholas Sterling wrote:
>> That last example, the JDBC sanitizer, is much more conventional -- 
>> there's no handler stack.  It is essentially a combination of the 
>> Template and Visitor design patterns.  The Template pattern is often 
>> applied to Java exceptions, so I don't think this would be thought of 
>> as unusual.
>>
>> Instance variables in the anonymous class would be accessible to both 
>> the method doing the work and the method handling the exceptions.  
>> And the class could access final variables outside it:
>>
>>    final Foo outside_class = ...;
>>
>>    HeapVisitor visitor = new HeapVisitor() {
>>
>>        Foo inside_class = ...;
>>
>>        void visitObject( JavaObject obj ) {
>>            // Both outside_class and inside_class are visible.
>>            // Var outside_class cannot be modified, of course,
>>            // but fields in the object it refers to may.
>>        }
>>
>>        void handleDataUnavailable( JavaObject obj ) {
>>            // Same here.
>>            // If we didn't put this method here, the default
>>            // would just throw a DataUnavailableException.
>>        }
>>    };
>>
>>    JavaHeap heap = factory.getJavaHeap(...);
>>    heap.visit( visitor );
>>
>> Does something like that seem reasonable?
>>
>> Nicholas
>>
>>
>>
>> Daniel Julin wrote:
>>> It seems to me that with all this discussion of polymorphic and 
>>> stackable
>>> error handlers, we're rapidly re-inventing much of the Java exception
>>> facility, and probably rediscovering a lot of the same design
>>> considerations that the original designers of that Java exception 
>>> facility
>>> faced...
>>>
>>> As far as I can tell, the one major difference is that, with Java
>>> exceptions, once an exception is thrown, the flow of control is 
>>> irrevocably
>>> interrupted and can only resume after the exception handler, not 
>>> back at
>>> the point where the exception was thrown. This means that if you do 
>>> want
>>> fine control over your errors but don't want to interrupt a whole 
>>> sequence
>>> of operations, you're forced to put an explicit try/catch block at 
>>> every
>>> line of the program. Whereas with these proposed handlers, a single
>>> top-level handler could presumably take care of all the errors in a
>>> sequence of operations without interrupting that sequence.
>>>
>>> Is that a correct interpretation? And is there no practical way to 
>>> achieve
>>> the same effect with actual Java exceptions? Some sort of "continue"
>>> statement inside a catch block, maybe?
>>>
>>>
>>> On the other hand, one thing that Java try/catch blocks offer is 
>>> controlled
>>> access to the local variables of the method in which the try/catch 
>>> block
>>> resides, and to the private instance members of the object. The 
>>> proposed
>>> handlers, since they are executing in a separate object and a separate
>>> method, would not enjoy a similar access. Whether this limitation would
>>> prove bothersome in practice, will depend on the actual usage scenarios
>>> that we face...
>>>
>>>
>>> -- Daniel --
>>>
>>>
>>>
>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-14 05:39:40 PM:
>>>  
>>>> If we were to end up doing something like this, would we use 
>>>> checked or
>>>> unchecked exceptions?  If we use checked exceptions, the client will
>>>> still have to catch the exception or say that the method throws it.
>>>> Presumably that would defeat the purpose...
>>>>
>>>> Good idea on the comparison code.  I'm a little concerned that people
>>>> may think we are overengineering the whole exception thing; once we 
>>>> have
>>>> the comparison code, we can run it by some folks and see whether their
>>>> brains short-circuit.
>>>>
>>>> It might be helpful as a reference point to consider an example with
>>>> another API.  I was sufficiently frustrated by the unreadability of my
>>>> JDBC clients that I wrote a pair of classes, Query and Querier, that
>>>> hide gory details, and I think it makes a big difference.  Among the
>>>> hidden are the binding of variables and iterating through result sets,
>>>> but probably the biggest benefit is from hiding the exception-handling
>>>> logic (it closes the ResultSet for you on an exception). This is 
>>>> what it
>>>> looks like to use it:
>>>>
>>>>     // Create a query to get recent bugs.
>>>>     static final Query recent_bugs_query = new Query(
>>>>         "bugs submitted against a PRODUCT in the last NUM DAYS",
>>>>         "select id, synopsis from bugs " +
>>>>        " where product = ? and date_submitted > sysdate - ?"
>>>>     );
>>>>     ...
>>>>     // Given a Connection conn and values for PRODUCT and NUM DAYS,
>>>>     // query the DB for recent bugs and display the resulting rows.
>>>>     new Querier( recent_bugs_query, conn, product, num_days ) {
>>>>         public void doRow() throws SQLException {
>>>>             System.out.println( rs.getString(1) + " " + rs.getString
>>>>     
>>> (2) );
>>>  
>>>>         }
>>>>     }
>>>>
>>>> A major benefit was getting rid of that awful doubly-nested catch 
>>>> block
>>>> (closing the ResultSet in the catch block may throw an exception, 
>>>> so it
>>>> requires its own try-catch -- gaah!).
>>>>
>>>> The default Querier throws an exception, but you can extend Querier 
>>>> and
>>>> override the handleException() method to do whatever is appropriate 
>>>> for
>>>> your app, and they use your custom Querier throughout your program, 
>>>> e.g.
>>>>
>>>>     class MyQuerier extends Querier {
>>>>         void handleException( Exception ex ) {
>>>>             ....
>>>>         }
>>>>     }
>>>>
>>>> Perhaps we could use a similar approach, for example providing a
>>>> HeapQuerier class from which clients create anonymous classes to do 
>>>> what
>>>> they want.
>>>>
>>>> Nicholas
>>>>
>>>>
>>>>
>>>> Steve Poole wrote:
>>>>   
>>>>> On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
>>>>> Nicholas.Sterling@sun.com> wrote:
>>>>>
>>>>>
>>>>>     
>>>>>> And a Handler (whatever it should really be called) would have 
>>>>>> access
>>>>>>         
>>> to
>>>  
>>>>>> the previous Handler on the stack, so it could do
>>>>>>
>>>>>>   void handleJavaObjectUnavailable(...) {
>>>>>>       // do some stuff, then defer to the guy beneath us on the 
>>>>>> stack:
>>>>>>       prevHandler().handleJavaObjectUnavailable(...);
>>>>>>   }
>>>>>> Nicholas
>>>>>>
>>>>>> This is cool -  The callback approach is sort of a half way
>>>>>>         
>>> housebetween a
>>>  
>>>>> DOM and SAX model.  It could allow us to have a default "no nulls"
>>>>>       
>>> approch
>>>  
>>>>> for an implementation but still allows for users of the API to do
>>>>>       
>>> something
>>>  
>>>>> different.
>>>>>
>>>>> I think we should create some comparison code segments to see what it
>>>>>       
>>> could
>>>  
>>>>> look like.
>>>>>
>>>>>
>>>>>     
>>>>>> Nicholas Sterling wrote:
>>>>>>
>>>>>>
>>>>>>       
>>>>>>> Daniel Julin wrote:
>>>>>>>
>>>>>>>
>>>>>>>         
>>>>>>>> I like that approach a lot, because it may also address the other
>>>>>>>>             
>>> concern
>>>  
>>>>>>>> that a proposed "default reasonable behavior" may not be 
>>>>>>>> appropriate
>>>>>>>>             
>>> for
>>>  
>>>>>>>> all usage scenarios. We could probably come-up with a variety of
>>>>>>>>             
>>> handlers
>>>  
>>>>>>>> for various common behaviors, like printing a simple error 
>>>>>>>> message,
>>>>>>>> completely ignoring the error, and lots of other creative 
>>>>>>>> responses.
>>>>>>>>
>>>>>>>> Incidentally, nothing in this discussion is particularly 
>>>>>>>> specific to
>>>>>>>>             
>>> the
>>>  
>>>>>>>> Kato API, is it? Are we saying that, in general, we don't like
>>>>>>>>             
>>> exceptions
>>>  
>>>>>>>> as the standard mechanism to report errors in Java, and that we're
>>>>>>>> inventing new patterns?  If so, have any useful patterns been
>>>>>>>>             
>>> proposed
>>>  
>>>>>>>> and
>>>>>>>> documented previously in the literature?
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>             
>>>>>>> I just looked around a little, and am only seeing suggestions 
>>>>>>> for how
>>>>>>>           
>>> the
>>>  
>>>>>>> *client* can abstract out the exception-handling logic using the
>>>>>>>           
>>> Template
>>>  
>>>>>>> design pattern.  So far I haven't seen any advice for API 
>>>>>>> designers.
>>>>>>>
>>>>>>> By the way, it occurred to me that the setter can have a generic 
>>>>>>> name
>>>>>>> because overloading will allow us to have a method for each
>>>>>>>           
>>> condition:
>>>  
>>>>>>>   factory.setHandler( new DataUnavailableHandler( ... ) {
>>>>>>>       ...
>>>>>>>   } );
>>>>>>>
>>>>>>> Also, it might make sense to push the handler on a stack rather
>>>>>>>           
>>> replace
>>>  
>>>>>>> what is there.  That will allow independent modules to modify just
>>>>>>>           
>>> that
>>>  
>>>>>>> behavior they need to and then remove those modifications when they
>>>>>>>           
>>> are no
>>>  
>>>>>>> longer needed.  It also means that we can have just one Handler
>>>>>>>           
>>>> () class for
>>>>   
>>>>>>> all the handlers, e.g.
>>>>>>>
>>>>>>>   // Temporarily override the handling of DataUnavailable errors.
>>>>>>>   factory.pushHandler( new Handler( ... ) {
>>>>>>>       void handleJavaObjectUnavailable(...) {
>>>>>>>           // handling specific for JavaObjects
>>>>>>>       }
>>>>>>>       void handleDataUnavailable(...) {
>>>>>>>           // handling for all other DataUnavailable conditions
>>>>>>>       }
>>>>>>>       // All handler methods not overridden will simply call the 
>>>>>>> same
>>>>>>> method
>>>>>>>       // for the object beneath us on the stack.  If we get to the
>>>>>>>           
>>> bottom,
>>>  
>>>>>>> the
>>>>>>>       // handler there will throw an exception.
>>>>>>>   } );
>>>>>>>   // Do some work that might cause an exception.  This might 
>>>>>>> include
>>>>>>> calling
>>>>>>>   // an independently written module that also wants to temporarily
>>>>>>> override
>>>>>>>   // some handler, but they will pop that before returning to us.
>>>>>>>   factory.popHandler();
>>>>>>>
>>>>>>> Nicholas
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>         
>>>>>>>> -- Daniel --,
>>>>>>>>
>>>>>>>>
>>>>>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>           
>>>>>>>>> Daniel Julin wrote:
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>             
>>>>>>>>>> I guess a two mode approach would make everyone happy. But would
>>>>>>>>>>                 
>>> it
>>>  
>>>>>>>>>>
>>>>>>>>>>                 
>>>>>>>>> make
>>>>>>>>>
>>>>>>>>>               the API too complicated?
>>>>>>>>>
>>>>>>>>>             
>>>>>>>>>>
>>>>>>>>>>                 
>>>>>>>>> I have some sympathy for what Steve is talking about -- maybe my
>>>>>>>>> short-term memory is small, but when lots of single lines of code
>>>>>>>>> inflate to 6 lines (and two indentation levels), it is definitely
>>>>>>>>>               
>>> harder
>>>  
>>>>>>>>> for me to read.  However, I wouldn't want to give up the certain
>>>>>>>>>               
>>> and
>>>  
>>>>>>>>> immediate catching of errors offered by exceptions.
>>>>>>>>>
>>>>>>>>> Would a mechanism like this work for the two-mode approach?
>>>>>>>>>
>>>>>>>>>    factory.setDataUnavailableHandler( new DataUnavailableHandler
>>>>>>>>>               
>>> ( ... )
>>>  
>>>>>>>>>
>>>>>>>>>               
>>>>>>>> {
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>           
>>>>>>>>>        ...
>>>>>>>>>    } );
>>>>>>>>>
>>>>>>>>> All objects created by the factory would call that object's
>>>>>>>>> dataUnavailable() method when appropriate, passing it enough info
>>>>>>>>>               
>>> about
>>>  
>>>>>>>>> what was going on to allow the method to make interesting 
>>>>>>>>> decisions
>>>>>>>>> about what to do.  The default handler would always throw a
>>>>>>>>> DataUnavailableException.
>>>>>>>>>
>>>>>>>>> It's hard for me to tell whether something like that would really
>>>>>>>>> suffice in actual use.  Perhaps it would have to be 
>>>>>>>>> finer-grained,
>>>>>>>>>               
>>> with
>>>  
>>>>>>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(),
>>>>>>>>>               
>>> etc.
>>>  
>>>>>>>>> Perhaps the defaults for those would call the more generic
>>>>>>>>> dataUnavailable() so that you could intervene for all cases 
>>>>>>>>> and/or
>>>>>>>>>               
>>> for
>>>  
>>>>>>>>> individual cases as desired.
>>>>>>>>>
>>>>>>>>> Nicholas
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>               
>>>>>>>>             
>>>>>       
>>>
>>>   
>>

Re: Kato API javadoc - error handling

Posted by Stuart Monteith <st...@stoo.me.uk>.

I think with the visitor pattern we'd have to weigh up the typical usage 
patterns against the loss of control it implies.
Certainly for the heap, you might typically do a linear scan as the 
locality of objects implies nothing about their relationship to one 
another - using a bidirectional cursor is pointless.. The loss of 
control means that the entire heap will be scanned, regardless of what 
occurs.

I think better with examples, so say we are counting all of the 
instances of classes, by name:


   final Foo outside_class = ...;

   HeapVisitor visitor = new HeapVisitor() {
       HashMap<String,Long> classCount = new HashMap<String,Long>();
       Foo inside_class = ...;

       void visitObject( JavaObject obj )  {
           // Both outside_class and inside_class are visible.
           // Var outside_class cannot be modified, of course,
           // but fields in the object it refers to may.
1         JavaClass clazz = obj.getJavaClass();
2         String className = clazz.getName();
           Long count= classCount.get(className);
         
          if (count.longValue() == 0) {
             classCount.put(className, 1);
          } else {
             classCount.put(className, count+1);
          }
       }

       void handleDataUnavailable( JavaObject obj ) {
           // Same here.
           // If we didn't put this method here, the default
           // would just throw a DataUnavailableException.
       }
      
       void HandleCorruptDataException(JavaObject obj) {
       }
   };

    try{
       JavaHeap heap = factory.getJavaHeap(...);
    }catch(CorruptDataException e) {
    }catch(DataUnavailableException e) {
    }
   heap.visit( visitor );

We could get CorruptDataException at 1 and 2, one would be because of 
the JavaObject, the other would be because of the JavaClass it referred 
to. I would posit that the exception information should be sufficient to 
properly report the problem in most cases as the processing done in a 
visitor method would be to do only with the object it is passed, and 
anything fairly close to it, such as its classes and fields.

Of course, how well would this work for smaller items, such as fields in 
classes, classes in classloaders, etc.
With fields, I tend to want to address them by name or get all of them 
from a class.



Nicholas Sterling wrote:
> That last example, the JDBC sanitizer, is much more conventional -- 
> there's no handler stack.  It is essentially a combination of the 
> Template and Visitor design patterns.  The Template pattern is often 
> applied to Java exceptions, so I don't think this would be thought of 
> as unusual.
>
> Instance variables in the anonymous class would be accessible to both 
> the method doing the work and the method handling the exceptions.  And 
> the class could access final variables outside it:
>
>    final Foo outside_class = ...;
>
>    HeapVisitor visitor = new HeapVisitor() {
>
>        Foo inside_class = ...;
>
>        void visitObject( JavaObject obj ) {
>            // Both outside_class and inside_class are visible.
>            // Var outside_class cannot be modified, of course,
>            // but fields in the object it refers to may.
>        }
>
>        void handleDataUnavailable( JavaObject obj ) {
>            // Same here.
>            // If we didn't put this method here, the default
>            // would just throw a DataUnavailableException.
>        }
>    };
>
>    JavaHeap heap = factory.getJavaHeap(...);
>    heap.visit( visitor );
>
> Does something like that seem reasonable?
>
> Nicholas
>
>
>
> Daniel Julin wrote:
>> It seems to me that with all this discussion of polymorphic and 
>> stackable
>> error handlers, we're rapidly re-inventing much of the Java exception
>> facility, and probably rediscovering a lot of the same design
>> considerations that the original designers of that Java exception 
>> facility
>> faced...
>>
>> As far as I can tell, the one major difference is that, with Java
>> exceptions, once an exception is thrown, the flow of control is 
>> irrevocably
>> interrupted and can only resume after the exception handler, not back at
>> the point where the exception was thrown. This means that if you do want
>> fine control over your errors but don't want to interrupt a whole 
>> sequence
>> of operations, you're forced to put an explicit try/catch block at every
>> line of the program. Whereas with these proposed handlers, a single
>> top-level handler could presumably take care of all the errors in a
>> sequence of operations without interrupting that sequence.
>>
>> Is that a correct interpretation? And is there no practical way to 
>> achieve
>> the same effect with actual Java exceptions? Some sort of "continue"
>> statement inside a catch block, maybe?
>>
>>
>> On the other hand, one thing that Java try/catch blocks offer is 
>> controlled
>> access to the local variables of the method in which the try/catch block
>> resides, and to the private instance members of the object. The proposed
>> handlers, since they are executing in a separate object and a separate
>> method, would not enjoy a similar access. Whether this limitation would
>> prove bothersome in practice, will depend on the actual usage scenarios
>> that we face...
>>
>>
>> -- Daniel --
>>
>>
>>
>> Nicholas.Sterling@Sun.COM wrote on 2009-04-14 05:39:40 PM:
>>  
>>> If we were to end up doing something like this, would we use checked or
>>> unchecked exceptions?  If we use checked exceptions, the client will
>>> still have to catch the exception or say that the method throws it.
>>> Presumably that would defeat the purpose...
>>>
>>> Good idea on the comparison code.  I'm a little concerned that people
>>> may think we are overengineering the whole exception thing; once we 
>>> have
>>> the comparison code, we can run it by some folks and see whether their
>>> brains short-circuit.
>>>
>>> It might be helpful as a reference point to consider an example with
>>> another API.  I was sufficiently frustrated by the unreadability of my
>>> JDBC clients that I wrote a pair of classes, Query and Querier, that
>>> hide gory details, and I think it makes a big difference.  Among the
>>> hidden are the binding of variables and iterating through result sets,
>>> but probably the biggest benefit is from hiding the exception-handling
>>> logic (it closes the ResultSet for you on an exception). This is 
>>> what it
>>> looks like to use it:
>>>
>>>     // Create a query to get recent bugs.
>>>     static final Query recent_bugs_query = new Query(
>>>         "bugs submitted against a PRODUCT in the last NUM DAYS",
>>>         "select id, synopsis from bugs " +
>>>        " where product = ? and date_submitted > sysdate - ?"
>>>     );
>>>     ...
>>>     // Given a Connection conn and values for PRODUCT and NUM DAYS,
>>>     // query the DB for recent bugs and display the resulting rows.
>>>     new Querier( recent_bugs_query, conn, product, num_days ) {
>>>         public void doRow() throws SQLException {
>>>             System.out.println( rs.getString(1) + " " + rs.getString
>>>     
>> (2) );
>>  
>>>         }
>>>     }
>>>
>>> A major benefit was getting rid of that awful doubly-nested catch block
>>> (closing the ResultSet in the catch block may throw an exception, so it
>>> requires its own try-catch -- gaah!).
>>>
>>> The default Querier throws an exception, but you can extend Querier and
>>> override the handleException() method to do whatever is appropriate for
>>> your app, and they use your custom Querier throughout your program, 
>>> e.g.
>>>
>>>     class MyQuerier extends Querier {
>>>         void handleException( Exception ex ) {
>>>             ....
>>>         }
>>>     }
>>>
>>> Perhaps we could use a similar approach, for example providing a
>>> HeapQuerier class from which clients create anonymous classes to do 
>>> what
>>> they want.
>>>
>>> Nicholas
>>>
>>>
>>>
>>> Steve Poole wrote:
>>>    
>>>> On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
>>>> Nicholas.Sterling@sun.com> wrote:
>>>>
>>>>
>>>>      
>>>>> And a Handler (whatever it should really be called) would have access
>>>>>         
>> to
>>  
>>>>> the previous Handler on the stack, so it could do
>>>>>
>>>>>   void handleJavaObjectUnavailable(...) {
>>>>>       // do some stuff, then defer to the guy beneath us on the 
>>>>> stack:
>>>>>       prevHandler().handleJavaObjectUnavailable(...);
>>>>>   }
>>>>> Nicholas
>>>>>
>>>>> This is cool -  The callback approach is sort of a half way
>>>>>         
>> housebetween a
>>  
>>>> DOM and SAX model.  It could allow us to have a default "no nulls"
>>>>       
>> approch
>>  
>>>> for an implementation but still allows for users of the API to do
>>>>       
>> something
>>  
>>>> different.
>>>>
>>>> I think we should create some comparison code segments to see what it
>>>>       
>> could
>>  
>>>> look like.
>>>>
>>>>
>>>>      
>>>>> Nicholas Sterling wrote:
>>>>>
>>>>>
>>>>>        
>>>>>> Daniel Julin wrote:
>>>>>>
>>>>>>
>>>>>>          
>>>>>>> I like that approach a lot, because it may also address the other
>>>>>>>             
>> concern
>>  
>>>>>>> that a proposed "default reasonable behavior" may not be 
>>>>>>> appropriate
>>>>>>>             
>> for
>>  
>>>>>>> all usage scenarios. We could probably come-up with a variety of
>>>>>>>             
>> handlers
>>  
>>>>>>> for various common behaviors, like printing a simple error message,
>>>>>>> completely ignoring the error, and lots of other creative 
>>>>>>> responses.
>>>>>>>
>>>>>>> Incidentally, nothing in this discussion is particularly 
>>>>>>> specific to
>>>>>>>             
>> the
>>  
>>>>>>> Kato API, is it? Are we saying that, in general, we don't like
>>>>>>>             
>> exceptions
>>  
>>>>>>> as the standard mechanism to report errors in Java, and that we're
>>>>>>> inventing new patterns?  If so, have any useful patterns been
>>>>>>>             
>> proposed
>>  
>>>>>>> and
>>>>>>> documented previously in the literature?
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>             
>>>>>> I just looked around a little, and am only seeing suggestions for 
>>>>>> how
>>>>>>           
>> the
>>  
>>>>>> *client* can abstract out the exception-handling logic using the
>>>>>>           
>> Template
>>  
>>>>>> design pattern.  So far I haven't seen any advice for API designers.
>>>>>>
>>>>>> By the way, it occurred to me that the setter can have a generic 
>>>>>> name
>>>>>> because overloading will allow us to have a method for each
>>>>>>           
>> condition:
>>  
>>>>>>   factory.setHandler( new DataUnavailableHandler( ... ) {
>>>>>>       ...
>>>>>>   } );
>>>>>>
>>>>>> Also, it might make sense to push the handler on a stack rather
>>>>>>           
>> replace
>>  
>>>>>> what is there.  That will allow independent modules to modify just
>>>>>>           
>> that
>>  
>>>>>> behavior they need to and then remove those modifications when they
>>>>>>           
>> are no
>>  
>>>>>> longer needed.  It also means that we can have just one Handler
>>>>>>           
>>> () class for
>>>    
>>>>>> all the handlers, e.g.
>>>>>>
>>>>>>   // Temporarily override the handling of DataUnavailable errors.
>>>>>>   factory.pushHandler( new Handler( ... ) {
>>>>>>       void handleJavaObjectUnavailable(...) {
>>>>>>           // handling specific for JavaObjects
>>>>>>       }
>>>>>>       void handleDataUnavailable(...) {
>>>>>>           // handling for all other DataUnavailable conditions
>>>>>>       }
>>>>>>       // All handler methods not overridden will simply call the 
>>>>>> same
>>>>>> method
>>>>>>       // for the object beneath us on the stack.  If we get to the
>>>>>>           
>> bottom,
>>  
>>>>>> the
>>>>>>       // handler there will throw an exception.
>>>>>>   } );
>>>>>>   // Do some work that might cause an exception.  This might include
>>>>>> calling
>>>>>>   // an independently written module that also wants to temporarily
>>>>>> override
>>>>>>   // some handler, but they will pop that before returning to us.
>>>>>>   factory.popHandler();
>>>>>>
>>>>>> Nicholas
>>>>>>
>>>>>>
>>>>>>
>>>>>>          
>>>>>>> -- Daniel --,
>>>>>>>
>>>>>>>
>>>>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>            
>>>>>>>> Daniel Julin wrote:
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>              
>>>>>>>>> I guess a two mode approach would make everyone happy. But would
>>>>>>>>>                 
>> it
>>  
>>>>>>>>>
>>>>>>>>>                 
>>>>>>>> make
>>>>>>>>
>>>>>>>>               the API too complicated?
>>>>>>>>
>>>>>>>>              
>>>>>>>>>
>>>>>>>>>                 
>>>>>>>> I have some sympathy for what Steve is talking about -- maybe my
>>>>>>>> short-term memory is small, but when lots of single lines of code
>>>>>>>> inflate to 6 lines (and two indentation levels), it is definitely
>>>>>>>>               
>> harder
>>  
>>>>>>>> for me to read.  However, I wouldn't want to give up the certain
>>>>>>>>               
>> and
>>  
>>>>>>>> immediate catching of errors offered by exceptions.
>>>>>>>>
>>>>>>>> Would a mechanism like this work for the two-mode approach?
>>>>>>>>
>>>>>>>>    factory.setDataUnavailableHandler( new DataUnavailableHandler
>>>>>>>>               
>> ( ... )
>>  
>>>>>>>>
>>>>>>>>               
>>>>>>> {
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>            
>>>>>>>>        ...
>>>>>>>>    } );
>>>>>>>>
>>>>>>>> All objects created by the factory would call that object's
>>>>>>>> dataUnavailable() method when appropriate, passing it enough info
>>>>>>>>               
>> about
>>  
>>>>>>>> what was going on to allow the method to make interesting 
>>>>>>>> decisions
>>>>>>>> about what to do.  The default handler would always throw a
>>>>>>>> DataUnavailableException.
>>>>>>>>
>>>>>>>> It's hard for me to tell whether something like that would really
>>>>>>>> suffice in actual use.  Perhaps it would have to be finer-grained,
>>>>>>>>               
>> with
>>  
>>>>>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(),
>>>>>>>>               
>> etc.
>>  
>>>>>>>> Perhaps the defaults for those would call the more generic
>>>>>>>> dataUnavailable() so that you could intervene for all cases and/or
>>>>>>>>               
>> for
>>  
>>>>>>>> individual cases as desired.
>>>>>>>>
>>>>>>>> Nicholas
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>               
>>>>>>>             
>>>>       
>>
>>   
>

Re: Kato API javadoc - error handling

Posted by Nicholas Sterling <Ni...@Sun.COM>.

That last example, the JDBC sanitizer, is much more conventional -- 
there's no handler stack.  It is essentially a combination of the 
Template and Visitor design patterns.  The Template pattern is often 
applied to Java exceptions, so I don't think this would be thought of as 
unusual.

Instance variables in the anonymous class would be accessible to both 
the method doing the work and the method handling the exceptions.  And 
the class could access final variables outside it:

    final Foo outside_class = ...;

    HeapVisitor visitor = new HeapVisitor() {

        Foo inside_class = ...;

        void visitObject( JavaObject obj ) {
            // Both outside_class and inside_class are visible.
            // Var outside_class cannot be modified, of course,
            // but fields in the object it refers to may.
        }

        void handleDataUnavailable( JavaObject obj ) {
            // Same here.
            // If we didn't put this method here, the default
            // would just throw a DataUnavailableException.
        }
    };

    JavaHeap heap = factory.getJavaHeap(...);
    heap.visit( visitor );

Does something like that seem reasonable?

Nicholas



Daniel Julin wrote:
> It seems to me that with all this discussion of polymorphic and stackable
> error handlers, we're rapidly re-inventing much of the Java exception
> facility, and probably rediscovering a lot of the same design
> considerations that the original designers of that Java exception facility
> faced...
>
> As far as I can tell, the one major difference is that, with Java
> exceptions, once an exception is thrown, the flow of control is irrevocably
> interrupted and can only resume after the exception handler, not back at
> the point where the exception was thrown. This means that if you do want
> fine control over your errors but don't want to interrupt a whole sequence
> of operations, you're forced to put an explicit try/catch block at every
> line of the program. Whereas with these proposed handlers, a single
> top-level handler could presumably take care of all the errors in a
> sequence of operations without interrupting that sequence.
>
> Is that a correct interpretation? And is there no practical way to achieve
> the same effect with actual Java exceptions? Some sort of "continue"
> statement inside a catch block, maybe?
>
>
> On the other hand, one thing that Java try/catch blocks offer is controlled
> access to the local variables of the method in which the try/catch block
> resides, and to the private instance members of the object. The proposed
> handlers, since they are executing in a separate object and a separate
> method, would not enjoy a similar access. Whether this limitation would
> prove bothersome in practice, will depend on the actual usage scenarios
> that we face...
>
>
> -- Daniel --
>
>
>
> Nicholas.Sterling@Sun.COM wrote on 2009-04-14 05:39:40 PM:
>   
>> If we were to end up doing something like this, would we use checked or
>> unchecked exceptions?  If we use checked exceptions, the client will
>> still have to catch the exception or say that the method throws it.
>> Presumably that would defeat the purpose...
>>
>> Good idea on the comparison code.  I'm a little concerned that people
>> may think we are overengineering the whole exception thing; once we have
>> the comparison code, we can run it by some folks and see whether their
>> brains short-circuit.
>>
>> It might be helpful as a reference point to consider an example with
>> another API.  I was sufficiently frustrated by the unreadability of my
>> JDBC clients that I wrote a pair of classes, Query and Querier, that
>> hide gory details, and I think it makes a big difference.  Among the
>> hidden are the binding of variables and iterating through result sets,
>> but probably the biggest benefit is from hiding the exception-handling
>> logic (it closes the ResultSet for you on an exception). This is what it
>> looks like to use it:
>>
>>     // Create a query to get recent bugs.
>>     static final Query recent_bugs_query = new Query(
>>         "bugs submitted against a PRODUCT in the last NUM DAYS",
>>         "select id, synopsis from bugs " +
>>        " where product = ? and date_submitted > sysdate - ?"
>>     );
>>     ...
>>     // Given a Connection conn and values for PRODUCT and NUM DAYS,
>>     // query the DB for recent bugs and display the resulting rows.
>>     new Querier( recent_bugs_query, conn, product, num_days ) {
>>         public void doRow() throws SQLException {
>>             System.out.println( rs.getString(1) + " " + rs.getString
>>     
> (2) );
>   
>>         }
>>     }
>>
>> A major benefit was getting rid of that awful doubly-nested catch block
>> (closing the ResultSet in the catch block may throw an exception, so it
>> requires its own try-catch -- gaah!).
>>
>> The default Querier throws an exception, but you can extend Querier and
>> override the handleException() method to do whatever is appropriate for
>> your app, and they use your custom Querier throughout your program, e.g.
>>
>>     class MyQuerier extends Querier {
>>         void handleException( Exception ex ) {
>>             ....
>>         }
>>     }
>>
>> Perhaps we could use a similar approach, for example providing a
>> HeapQuerier class from which clients create anonymous classes to do what
>> they want.
>>
>> Nicholas
>>
>>
>>
>> Steve Poole wrote:
>>     
>>> On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
>>> Nicholas.Sterling@sun.com> wrote:
>>>
>>>
>>>       
>>>> And a Handler (whatever it should really be called) would have access
>>>>         
> to
>   
>>>> the previous Handler on the stack, so it could do
>>>>
>>>>   void handleJavaObjectUnavailable(...) {
>>>>       // do some stuff, then defer to the guy beneath us on the stack:
>>>>       prevHandler().handleJavaObjectUnavailable(...);
>>>>   }
>>>> Nicholas
>>>>
>>>> This is cool -  The callback approach is sort of a half way
>>>>         
> housebetween a
>   
>>> DOM and SAX model.  It could allow us to have a default "no nulls"
>>>       
> approch
>   
>>> for an implementation but still allows for users of the API to do
>>>       
> something
>   
>>> different.
>>>
>>> I think we should create some comparison code segments to see what it
>>>       
> could
>   
>>> look like.
>>>
>>>
>>>       
>>>> Nicholas Sterling wrote:
>>>>
>>>>
>>>>         
>>>>> Daniel Julin wrote:
>>>>>
>>>>>
>>>>>           
>>>>>> I like that approach a lot, because it may also address the other
>>>>>>             
> concern
>   
>>>>>> that a proposed "default reasonable behavior" may not be appropriate
>>>>>>             
> for
>   
>>>>>> all usage scenarios. We could probably come-up with a variety of
>>>>>>             
> handlers
>   
>>>>>> for various common behaviors, like printing a simple error message,
>>>>>> completely ignoring the error, and lots of other creative responses.
>>>>>>
>>>>>> Incidentally, nothing in this discussion is particularly specific to
>>>>>>             
> the
>   
>>>>>> Kato API, is it? Are we saying that, in general, we don't like
>>>>>>             
> exceptions
>   
>>>>>> as the standard mechanism to report errors in Java, and that we're
>>>>>> inventing new patterns?  If so, have any useful patterns been
>>>>>>             
> proposed
>   
>>>>>> and
>>>>>> documented previously in the literature?
>>>>>>
>>>>>>
>>>>>>
>>>>>>             
>>>>> I just looked around a little, and am only seeing suggestions for how
>>>>>           
> the
>   
>>>>> *client* can abstract out the exception-handling logic using the
>>>>>           
> Template
>   
>>>>> design pattern.  So far I haven't seen any advice for API designers.
>>>>>
>>>>> By the way, it occurred to me that the setter can have a generic name
>>>>> because overloading will allow us to have a method for each
>>>>>           
> condition:
>   
>>>>>   factory.setHandler( new DataUnavailableHandler( ... ) {
>>>>>       ...
>>>>>   } );
>>>>>
>>>>> Also, it might make sense to push the handler on a stack rather
>>>>>           
> replace
>   
>>>>> what is there.  That will allow independent modules to modify just
>>>>>           
> that
>   
>>>>> behavior they need to and then remove those modifications when they
>>>>>           
> are no
>   
>>>>> longer needed.  It also means that we can have just one Handler
>>>>>           
>> () class for
>>     
>>>>> all the handlers, e.g.
>>>>>
>>>>>   // Temporarily override the handling of DataUnavailable errors.
>>>>>   factory.pushHandler( new Handler( ... ) {
>>>>>       void handleJavaObjectUnavailable(...) {
>>>>>           // handling specific for JavaObjects
>>>>>       }
>>>>>       void handleDataUnavailable(...) {
>>>>>           // handling for all other DataUnavailable conditions
>>>>>       }
>>>>>       // All handler methods not overridden will simply call the same
>>>>> method
>>>>>       // for the object beneath us on the stack.  If we get to the
>>>>>           
> bottom,
>   
>>>>> the
>>>>>       // handler there will throw an exception.
>>>>>   } );
>>>>>   // Do some work that might cause an exception.  This might include
>>>>> calling
>>>>>   // an independently written module that also wants to temporarily
>>>>> override
>>>>>   // some handler, but they will pop that before returning to us.
>>>>>   factory.popHandler();
>>>>>
>>>>> Nicholas
>>>>>
>>>>>
>>>>>
>>>>>           
>>>>>> -- Daniel --,
>>>>>>
>>>>>>
>>>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>>>>>
>>>>>>
>>>>>>
>>>>>>             
>>>>>>> Daniel Julin wrote:
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>               
>>>>>>>> I guess a two mode approach would make everyone happy. But would
>>>>>>>>                 
> it
>   
>>>>>>>>
>>>>>>>>                 
>>>>>>> make
>>>>>>>
>>>>>>>               
>>>>>>> the API too complicated?
>>>>>>>
>>>>>>>               
>>>>>>>>
>>>>>>>>                 
>>>>>>> I have some sympathy for what Steve is talking about -- maybe my
>>>>>>> short-term memory is small, but when lots of single lines of code
>>>>>>> inflate to 6 lines (and two indentation levels), it is definitely
>>>>>>>               
> harder
>   
>>>>>>> for me to read.  However, I wouldn't want to give up the certain
>>>>>>>               
> and
>   
>>>>>>> immediate catching of errors offered by exceptions.
>>>>>>>
>>>>>>> Would a mechanism like this work for the two-mode approach?
>>>>>>>
>>>>>>>    factory.setDataUnavailableHandler( new DataUnavailableHandler
>>>>>>>               
> ( ... )
>   
>>>>>>>
>>>>>>>               
>>>>>> {
>>>>>>
>>>>>>
>>>>>>
>>>>>>             
>>>>>>>        ...
>>>>>>>    } );
>>>>>>>
>>>>>>> All objects created by the factory would call that object's
>>>>>>> dataUnavailable() method when appropriate, passing it enough info
>>>>>>>               
> about
>   
>>>>>>> what was going on to allow the method to make interesting decisions
>>>>>>> about what to do.  The default handler would always throw a
>>>>>>> DataUnavailableException.
>>>>>>>
>>>>>>> It's hard for me to tell whether something like that would really
>>>>>>> suffice in actual use.  Perhaps it would have to be finer-grained,
>>>>>>>               
> with
>   
>>>>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(),
>>>>>>>               
> etc.
>   
>>>>>>> Perhaps the defaults for those would call the more generic
>>>>>>> dataUnavailable() so that you could intervene for all cases and/or
>>>>>>>               
> for
>   
>>>>>>> individual cases as desired.
>>>>>>>
>>>>>>> Nicholas
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>               
>>>>>>             
>>>       
>
>

Re: Kato API javadoc - error handling

Posted by Daniel Julin <dp...@us.ibm.com>.

It seems to me that with all this discussion of polymorphic and stackable
error handlers, we're rapidly re-inventing much of the Java exception
facility, and probably rediscovering a lot of the same design
considerations that the original designers of that Java exception facility
faced...

As far as I can tell, the one major difference is that, with Java
exceptions, once an exception is thrown, the flow of control is irrevocably
interrupted and can only resume after the exception handler, not back at
the point where the exception was thrown. This means that if you do want
fine control over your errors but don't want to interrupt a whole sequence
of operations, you're forced to put an explicit try/catch block at every
line of the program. Whereas with these proposed handlers, a single
top-level handler could presumably take care of all the errors in a
sequence of operations without interrupting that sequence.

Is that a correct interpretation? And is there no practical way to achieve
the same effect with actual Java exceptions? Some sort of "continue"
statement inside a catch block, maybe?


On the other hand, one thing that Java try/catch blocks offer is controlled
access to the local variables of the method in which the try/catch block
resides, and to the private instance members of the object. The proposed
handlers, since they are executing in a separate object and a separate
method, would not enjoy a similar access. Whether this limitation would
prove bothersome in practice, will depend on the actual usage scenarios
that we face...


-- Daniel --



Nicholas.Sterling@Sun.COM wrote on 2009-04-14 05:39:40 PM:
> If we were to end up doing something like this, would we use checked or
> unchecked exceptions?  If we use checked exceptions, the client will
> still have to catch the exception or say that the method throws it.
> Presumably that would defeat the purpose...
>
> Good idea on the comparison code.  I'm a little concerned that people
> may think we are overengineering the whole exception thing; once we have
> the comparison code, we can run it by some folks and see whether their
> brains short-circuit.
>
> It might be helpful as a reference point to consider an example with
> another API.  I was sufficiently frustrated by the unreadability of my
> JDBC clients that I wrote a pair of classes, Query and Querier, that
> hide gory details, and I think it makes a big difference.  Among the
> hidden are the binding of variables and iterating through result sets,
> but probably the biggest benefit is from hiding the exception-handling
> logic (it closes the ResultSet for you on an exception). This is what it
> looks like to use it:
>
>     // Create a query to get recent bugs.
>     static final Query recent_bugs_query = new Query(
>         "bugs submitted against a PRODUCT in the last NUM DAYS",
>         "select id, synopsis from bugs " +
>        " where product = ? and date_submitted > sysdate - ?"
>     );
>     ...
>     // Given a Connection conn and values for PRODUCT and NUM DAYS,
>     // query the DB for recent bugs and display the resulting rows.
>     new Querier( recent_bugs_query, conn, product, num_days ) {
>         public void doRow() throws SQLException {
>             System.out.println( rs.getString(1) + " " + rs.getString
(2) );
>         }
>     }
>
> A major benefit was getting rid of that awful doubly-nested catch block
> (closing the ResultSet in the catch block may throw an exception, so it
> requires its own try-catch -- gaah!).
>
> The default Querier throws an exception, but you can extend Querier and
> override the handleException() method to do whatever is appropriate for
> your app, and they use your custom Querier throughout your program, e.g.
>
>     class MyQuerier extends Querier {
>         void handleException( Exception ex ) {
>             ....
>         }
>     }
>
> Perhaps we could use a similar approach, for example providing a
> HeapQuerier class from which clients create anonymous classes to do what
> they want.
>
> Nicholas
>
>
>
> Steve Poole wrote:
> > On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
> > Nicholas.Sterling@sun.com> wrote:
> >
> >
> >> And a Handler (whatever it should really be called) would have access
to
> >> the previous Handler on the stack, so it could do
> >>
> >>   void handleJavaObjectUnavailable(...) {
> >>       // do some stuff, then defer to the guy beneath us on the stack:
> >>       prevHandler().handleJavaObjectUnavailable(...);
> >>   }
> >> Nicholas
> >>
> >> This is cool -  The callback approach is sort of a half way
housebetween a
> >>
> > DOM and SAX model.  It could allow us to have a default "no nulls"
approch
> > for an implementation but still allows for users of the API to do
something
> > different.
> >
> > I think we should create some comparison code segments to see what it
could
> > look like.
> >
> >
> >> Nicholas Sterling wrote:
> >>
> >>
> >>> Daniel Julin wrote:
> >>>
> >>>
> >>>> I like that approach a lot, because it may also address the other
concern
> >>>> that a proposed "default reasonable behavior" may not be appropriate
for
> >>>> all usage scenarios. We could probably come-up with a variety of
handlers
> >>>> for various common behaviors, like printing a simple error message,
> >>>> completely ignoring the error, and lots of other creative responses.
> >>>>
> >>>> Incidentally, nothing in this discussion is particularly specific to
the
> >>>> Kato API, is it? Are we saying that, in general, we don't like
exceptions
> >>>> as the standard mechanism to report errors in Java, and that we're
> >>>> inventing new patterns?  If so, have any useful patterns been
proposed
> >>>> and
> >>>> documented previously in the literature?
> >>>>
> >>>>
> >>>>
> >>> I just looked around a little, and am only seeing suggestions for how
the
> >>> *client* can abstract out the exception-handling logic using the
Template
> >>> design pattern.  So far I haven't seen any advice for API designers.
> >>>
> >>> By the way, it occurred to me that the setter can have a generic name
> >>> because overloading will allow us to have a method for each
condition:
> >>>
> >>>   factory.setHandler( new DataUnavailableHandler( ... ) {
> >>>       ...
> >>>   } );
> >>>
> >>> Also, it might make sense to push the handler on a stack rather
replace
> >>> what is there.  That will allow independent modules to modify just
that
> >>> behavior they need to and then remove those modifications when they
are no
> >>> longer needed.  It also means that we can have just one Handler
> () class for
> >>> all the handlers, e.g.
> >>>
> >>>   // Temporarily override the handling of DataUnavailable errors.
> >>>   factory.pushHandler( new Handler( ... ) {
> >>>       void handleJavaObjectUnavailable(...) {
> >>>           // handling specific for JavaObjects
> >>>       }
> >>>       void handleDataUnavailable(...) {
> >>>           // handling for all other DataUnavailable conditions
> >>>       }
> >>>       // All handler methods not overridden will simply call the same
> >>> method
> >>>       // for the object beneath us on the stack.  If we get to the
bottom,
> >>> the
> >>>       // handler there will throw an exception.
> >>>   } );
> >>>   // Do some work that might cause an exception.  This might include
> >>> calling
> >>>   // an independently written module that also wants to temporarily
> >>> override
> >>>   // some handler, but they will pop that before returning to us.
> >>>   factory.popHandler();
> >>>
> >>> Nicholas
> >>>
> >>>
> >>>
> >>>> -- Daniel --,
> >>>>
> >>>>
> >>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
> >>>>
> >>>>
> >>>>
> >>>>> Daniel Julin wrote:
> >>>>>
> >>>>>
> >>>>>
> >>>>>> I guess a two mode approach would make everyone happy. But would
it
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>> make
> >>>>>
> >>>>
> >>>>> the API too complicated?
> >>>>>
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>> I have some sympathy for what Steve is talking about -- maybe my
> >>>>> short-term memory is small, but when lots of single lines of code
> >>>>> inflate to 6 lines (and two indentation levels), it is definitely
harder
> >>>>> for me to read.  However, I wouldn't want to give up the certain
and
> >>>>> immediate catching of errors offered by exceptions.
> >>>>>
> >>>>> Would a mechanism like this work for the two-mode approach?
> >>>>>
> >>>>>    factory.setDataUnavailableHandler( new DataUnavailableHandler
( ... )
> >>>>>
> >>>>>
> >>>>>
> >>>> {
> >>>>
> >>>>
> >>>>
> >>>>>        ...
> >>>>>    } );
> >>>>>
> >>>>> All objects created by the factory would call that object's
> >>>>> dataUnavailable() method when appropriate, passing it enough info
about
> >>>>> what was going on to allow the method to make interesting decisions
> >>>>> about what to do.  The default handler would always throw a
> >>>>> DataUnavailableException.
> >>>>>
> >>>>> It's hard for me to tell whether something like that would really
> >>>>> suffice in actual use.  Perhaps it would have to be finer-grained,
with
> >>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(),
etc.
> >>>>> Perhaps the defaults for those would call the more generic
> >>>>> dataUnavailable() so that you could intervene for all cases and/or
for
> >>>>> individual cases as desired.
> >>>>>
> >>>>> Nicholas
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>
> >>>>
> >>>
> >
> >

Re: Kato API javadoc - error handling

Posted by Nicholas Sterling <Ni...@Sun.COM>.

If we were to end up doing something like this, would we use checked or 
unchecked exceptions?  If we use checked exceptions, the client will 
still have to catch the exception or say that the method throws it.  
Presumably that would defeat the purpose...

Good idea on the comparison code.  I'm a little concerned that people 
may think we are overengineering the whole exception thing; once we have 
the comparison code, we can run it by some folks and see whether their 
brains short-circuit.

It might be helpful as a reference point to consider an example with 
another API.  I was sufficiently frustrated by the unreadability of my 
JDBC clients that I wrote a pair of classes, Query and Querier, that 
hide gory details, and I think it makes a big difference.  Among the 
hidden are the binding of variables and iterating through result sets, 
but probably the biggest benefit is from hiding the exception-handling 
logic (it closes the ResultSet for you on an exception). This is what it 
looks like to use it:

    // Create a query to get recent bugs.
    static final Query recent_bugs_query = new Query(
        "bugs submitted against a PRODUCT in the last NUM DAYS",
        "select id, synopsis from bugs " +
       " where product = ? and date_submitted > sysdate - ?"
    );
    ...
    // Given a Connection conn and values for PRODUCT and NUM DAYS,
    // query the DB for recent bugs and display the resulting rows.
    new Querier( recent_bugs_query, conn, product, num_days ) {
        public void doRow() throws SQLException {
            System.out.println( rs.getString(1) + " " + rs.getString(2) );
        }
    }

A major benefit was getting rid of that awful doubly-nested catch block 
(closing the ResultSet in the catch block may throw an exception, so it 
requires its own try-catch -- gaah!).

The default Querier throws an exception, but you can extend Querier and 
override the handleException() method to do whatever is appropriate for 
your app, and they use your custom Querier throughout your program, e.g.

    class MyQuerier extends Querier {
        void handleException( Exception ex ) {
            ....
        }
    }

Perhaps we could use a similar approach, for example providing a 
HeapQuerier class from which clients create anonymous classes to do what 
they want.

Nicholas



Steve Poole wrote:
> On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
> Nicholas.Sterling@sun.com> wrote:
>
>   
>> And a Handler (whatever it should really be called) would have access to
>> the previous Handler on the stack, so it could do
>>
>>   void handleJavaObjectUnavailable(...) {
>>       // do some stuff, then defer to the guy beneath us on the stack:
>>       prevHandler().handleJavaObjectUnavailable(...);
>>   }
>> Nicholas
>>
>> This is cool -  The callback approach is sort of a half way house between a
>>     
> DOM and SAX model.  It could allow us to have a default "no nulls" approch
> for an implementation but still allows for users of the API to do something
> different.
>
> I think we should create some comparison code segments to see what it could
> look like.
>
>   
>> Nicholas Sterling wrote:
>>
>>     
>>> Daniel Julin wrote:
>>>
>>>       
>>>> I like that approach a lot, because it may also address the other concern
>>>> that a proposed "default reasonable behavior" may not be appropriate for
>>>> all usage scenarios. We could probably come-up with a variety of handlers
>>>> for various common behaviors, like printing a simple error message,
>>>> completely ignoring the error, and lots of other creative responses.
>>>>
>>>> Incidentally, nothing in this discussion is particularly specific to the
>>>> Kato API, is it? Are we saying that, in general, we don't like exceptions
>>>> as the standard mechanism to report errors in Java, and that we're
>>>> inventing new patterns?  If so, have any useful patterns been proposed
>>>> and
>>>> documented previously in the literature?
>>>>
>>>>
>>>>         
>>> I just looked around a little, and am only seeing suggestions for how the
>>> *client* can abstract out the exception-handling logic using the Template
>>> design pattern.  So far I haven't seen any advice for API designers.
>>>
>>> By the way, it occurred to me that the setter can have a generic name
>>> because overloading will allow us to have a method for each condition:
>>>
>>>   factory.setHandler( new DataUnavailableHandler( ... ) {
>>>       ...
>>>   } );
>>>
>>> Also, it might make sense to push the handler on a stack rather replace
>>> what is there.  That will allow independent modules to modify just that
>>> behavior they need to and then remove those modifications when they are no
>>> longer needed.  It also means that we can have just one Handler() class for
>>> all the handlers, e.g.
>>>
>>>   // Temporarily override the handling of DataUnavailable errors.
>>>   factory.pushHandler( new Handler( ... ) {
>>>       void handleJavaObjectUnavailable(...) {
>>>           // handling specific for JavaObjects
>>>       }
>>>       void handleDataUnavailable(...) {
>>>           // handling for all other DataUnavailable conditions
>>>       }
>>>       // All handler methods not overridden will simply call the same
>>> method
>>>       // for the object beneath us on the stack.  If we get to the bottom,
>>> the
>>>       // handler there will throw an exception.
>>>   } );
>>>   // Do some work that might cause an exception.  This might include
>>> calling
>>>   // an independently written module that also wants to temporarily
>>> override
>>>   // some handler, but they will pop that before returning to us.
>>>   factory.popHandler();
>>>
>>> Nicholas
>>>
>>>
>>>       
>>>> -- Daniel --,
>>>>
>>>>
>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>>>
>>>>
>>>>         
>>>>> Daniel Julin wrote:
>>>>>
>>>>>
>>>>>           
>>>>>> I guess a two mode approach would make everyone happy. But would it
>>>>>>
>>>>>>
>>>>>>             
>>>>> make
>>>>>           
>>>>         
>>>>> the API too complicated?
>>>>>           
>>>>>>
>>>>>>
>>>>>>             
>>>>> I have some sympathy for what Steve is talking about -- maybe my
>>>>> short-term memory is small, but when lots of single lines of code
>>>>> inflate to 6 lines (and two indentation levels), it is definitely harder
>>>>> for me to read.  However, I wouldn't want to give up the certain and
>>>>> immediate catching of errors offered by exceptions.
>>>>>
>>>>> Would a mechanism like this work for the two-mode approach?
>>>>>
>>>>>    factory.setDataUnavailableHandler( new DataUnavailableHandler( ... )
>>>>>
>>>>>
>>>>>           
>>>> {
>>>>
>>>>
>>>>         
>>>>>        ...
>>>>>    } );
>>>>>
>>>>> All objects created by the factory would call that object's
>>>>> dataUnavailable() method when appropriate, passing it enough info about
>>>>> what was going on to allow the method to make interesting decisions
>>>>> about what to do.  The default handler would always throw a
>>>>> DataUnavailableException.
>>>>>
>>>>> It's hard for me to tell whether something like that would really
>>>>> suffice in actual use.  Perhaps it would have to be finer-grained, with
>>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(), etc.
>>>>> Perhaps the defaults for those would call the more generic
>>>>> dataUnavailable() so that you could intervene for all cases and/or for
>>>>> individual cases as desired.
>>>>>
>>>>> Nicholas
>>>>>
>>>>>
>>>>>
>>>>>           
>>>>
>>>>         
>>>       
>
>

Re: Kato API javadoc - error handling

Posted by Steve Poole <sp...@googlemail.com>.

On Mon, Apr 13, 2009 at 4:34 AM, Nicholas Sterling <
Nicholas.Sterling@sun.com> wrote:

> And a Handler (whatever it should really be called) would have access to
> the previous Handler on the stack, so it could do
>
>   void handleJavaObjectUnavailable(...) {
>       // do some stuff, then defer to the guy beneath us on the stack:
>       prevHandler().handleJavaObjectUnavailable(...);
>   }
> Nicholas
>
> This is cool -  The callback approach is sort of a half way house between a
DOM and SAX model.  It could allow us to have a default "no nulls" approch
for an implementation but still allows for users of the API to do something
different.

I think we should create some comparison code segments to see what it could
look like.

>
>
> Nicholas Sterling wrote:
>
>>
>>
>> Daniel Julin wrote:
>>
>>> I like that approach a lot, because it may also address the other concern
>>> that a proposed "default reasonable behavior" may not be appropriate for
>>> all usage scenarios. We could probably come-up with a variety of handlers
>>> for various common behaviors, like printing a simple error message,
>>> completely ignoring the error, and lots of other creative responses.
>>>
>>> Incidentally, nothing in this discussion is particularly specific to the
>>> Kato API, is it? Are we saying that, in general, we don't like exceptions
>>> as the standard mechanism to report errors in Java, and that we're
>>> inventing new patterns?  If so, have any useful patterns been proposed
>>> and
>>> documented previously in the literature?
>>>
>>>
>> I just looked around a little, and am only seeing suggestions for how the
>> *client* can abstract out the exception-handling logic using the Template
>> design pattern.  So far I haven't seen any advice for API designers.
>>
>> By the way, it occurred to me that the setter can have a generic name
>> because overloading will allow us to have a method for each condition:
>>
>>   factory.setHandler( new DataUnavailableHandler( ... ) {
>>       ...
>>   } );
>>
>> Also, it might make sense to push the handler on a stack rather replace
>> what is there.  That will allow independent modules to modify just that
>> behavior they need to and then remove those modifications when they are no
>> longer needed.  It also means that we can have just one Handler() class for
>> all the handlers, e.g.
>>
>>   // Temporarily override the handling of DataUnavailable errors.
>>   factory.pushHandler( new Handler( ... ) {
>>       void handleJavaObjectUnavailable(...) {
>>           // handling specific for JavaObjects
>>       }
>>       void handleDataUnavailable(...) {
>>           // handling for all other DataUnavailable conditions
>>       }
>>       // All handler methods not overridden will simply call the same
>> method
>>       // for the object beneath us on the stack.  If we get to the bottom,
>> the
>>       // handler there will throw an exception.
>>   } );
>>   // Do some work that might cause an exception.  This might include
>> calling
>>   // an independently written module that also wants to temporarily
>> override
>>   // some handler, but they will pop that before returning to us.
>>   factory.popHandler();
>>
>> Nicholas
>>
>>
>>> -- Daniel --,
>>>
>>>
>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>>
>>>
>>>> Daniel Julin wrote:
>>>>
>>>>
>>>>> I guess a two mode approach would make everyone happy. But would it
>>>>>
>>>>>
>>>> make
>>>
>>>
>>>> the API too complicated?
>>>>>
>>>>>
>>>>>
>>>>>
>>>> I have some sympathy for what Steve is talking about -- maybe my
>>>> short-term memory is small, but when lots of single lines of code
>>>> inflate to 6 lines (and two indentation levels), it is definitely harder
>>>> for me to read.  However, I wouldn't want to give up the certain and
>>>> immediate catching of errors offered by exceptions.
>>>>
>>>> Would a mechanism like this work for the two-mode approach?
>>>>
>>>>    factory.setDataUnavailableHandler( new DataUnavailableHandler( ... )
>>>>
>>>>
>>> {
>>>
>>>
>>>>        ...
>>>>    } );
>>>>
>>>> All objects created by the factory would call that object's
>>>> dataUnavailable() method when appropriate, passing it enough info about
>>>> what was going on to allow the method to make interesting decisions
>>>> about what to do.  The default handler would always throw a
>>>> DataUnavailableException.
>>>>
>>>> It's hard for me to tell whether something like that would really
>>>> suffice in actual use.  Perhaps it would have to be finer-grained, with
>>>> methods for javaObjectUnavailable(), imageSectionUnavailable(), etc.
>>>> Perhaps the defaults for those would call the more generic
>>>> dataUnavailable() so that you could intervene for all cases and/or for
>>>> individual cases as desired.
>>>>
>>>> Nicholas
>>>>
>>>>
>>>>
>>>
>>>
>>>
>>
>>

Re: Kato API javadoc - error handling

Posted by Nicholas Sterling <Ni...@Sun.COM>.

And a Handler (whatever it should really be called) would have access to 
the previous Handler on the stack, so it could do

    void handleJavaObjectUnavailable(...) {
        // do some stuff, then defer to the guy beneath us on the stack:
        prevHandler().handleJavaObjectUnavailable(...);
    } 

Nicholas


Nicholas Sterling wrote:
>
>
> Daniel Julin wrote:
>> I like that approach a lot, because it may also address the other 
>> concern
>> that a proposed "default reasonable behavior" may not be appropriate for
>> all usage scenarios. We could probably come-up with a variety of 
>> handlers
>> for various common behaviors, like printing a simple error message,
>> completely ignoring the error, and lots of other creative responses.
>>
>> Incidentally, nothing in this discussion is particularly specific to the
>> Kato API, is it? Are we saying that, in general, we don't like 
>> exceptions
>> as the standard mechanism to report errors in Java, and that we're
>> inventing new patterns?  If so, have any useful patterns been 
>> proposed and
>> documented previously in the literature?
>>   
> I just looked around a little, and am only seeing suggestions for how 
> the *client* can abstract out the exception-handling logic using the 
> Template design pattern.  So far I haven't seen any advice for API 
> designers.
>
> By the way, it occurred to me that the setter can have a generic name 
> because overloading will allow us to have a method for each condition:
>
>    factory.setHandler( new DataUnavailableHandler( ... ) {
>        ...
>    } );
>
> Also, it might make sense to push the handler on a stack rather 
> replace what is there.  That will allow independent modules to modify 
> just that behavior they need to and then remove those modifications 
> when they are no longer needed.  It also means that we can have just 
> one Handler() class for all the handlers, e.g.
>
>    // Temporarily override the handling of DataUnavailable errors.
>    factory.pushHandler( new Handler( ... ) {
>        void handleJavaObjectUnavailable(...) {
>            // handling specific for JavaObjects
>        }
>        void handleDataUnavailable(...) {
>            // handling for all other DataUnavailable conditions
>        }
>        // All handler methods not overridden will simply call the same 
> method
>        // for the object beneath us on the stack.  If we get to the 
> bottom, the
>        // handler there will throw an exception.
>    } );
>    // Do some work that might cause an exception.  This might include 
> calling
>    // an independently written module that also wants to temporarily 
> override
>    // some handler, but they will pop that before returning to us.
>    factory.popHandler();
>
> Nicholas
>
>>
>> -- Daniel --,
>>
>>
>> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>>  
>>> Daniel Julin wrote:
>>>    
>>>> I guess a two mode approach would make everyone happy. But would it
>>>>       
>> make
>>  
>>>> the API too complicated?
>>>>
>>>>
>>>>       
>>> I have some sympathy for what Steve is talking about -- maybe my
>>> short-term memory is small, but when lots of single lines of code
>>> inflate to 6 lines (and two indentation levels), it is definitely 
>>> harder
>>> for me to read.  However, I wouldn't want to give up the certain and
>>> immediate catching of errors offered by exceptions.
>>>
>>> Would a mechanism like this work for the two-mode approach?
>>>
>>>     factory.setDataUnavailableHandler( new DataUnavailableHandler( 
>>> ... )
>>>     
>> {
>>  
>>>         ...
>>>     } );
>>>
>>> All objects created by the factory would call that object's
>>> dataUnavailable() method when appropriate, passing it enough info about
>>> what was going on to allow the method to make interesting decisions
>>> about what to do.  The default handler would always throw a
>>> DataUnavailableException.
>>>
>>> It's hard for me to tell whether something like that would really
>>> suffice in actual use.  Perhaps it would have to be finer-grained, with
>>> methods for javaObjectUnavailable(), imageSectionUnavailable(), etc.
>>> Perhaps the defaults for those would call the more generic
>>> dataUnavailable() so that you could intervene for all cases and/or for
>>> individual cases as desired.
>>>
>>> Nicholas
>>>
>>>     
>>
>>   
>

Re: Kato API javadoc - error handling

Posted by Nicholas Sterling <Ni...@Sun.COM>.


Daniel Julin wrote:
> I like that approach a lot, because it may also address the other concern
> that a proposed "default reasonable behavior" may not be appropriate for
> all usage scenarios. We could probably come-up with a variety of handlers
> for various common behaviors, like printing a simple error message,
> completely ignoring the error, and lots of other creative responses.
>
> Incidentally, nothing in this discussion is particularly specific to the
> Kato API, is it? Are we saying that, in general, we don't like exceptions
> as the standard mechanism to report errors in Java, and that we're
> inventing new patterns?  If so, have any useful patterns been proposed and
> documented previously in the literature?
>   
I just looked around a little, and am only seeing suggestions for how 
the *client* can abstract out the exception-handling logic using the 
Template design pattern.  So far I haven't seen any advice for API 
designers.

By the way, it occurred to me that the setter can have a generic name 
because overloading will allow us to have a method for each condition:

    factory.setHandler( new DataUnavailableHandler( ... ) {
        ...
    } );

Also, it might make sense to push the handler on a stack rather replace 
what is there.  That will allow independent modules to modify just that 
behavior they need to and then remove those modifications when they are 
no longer needed.  It also means that we can have just one Handler() 
class for all the handlers, e.g.

    // Temporarily override the handling of DataUnavailable errors.
    factory.pushHandler( new Handler( ... ) {
        void handleJavaObjectUnavailable(...) {
            // handling specific for JavaObjects
        }
        void handleDataUnavailable(...) {
            // handling for all other DataUnavailable conditions
        }
        // All handler methods not overridden will simply call the same method
        // for the object beneath us on the stack.  If we get to the bottom, the
        // handler there will throw an exception.
    } );
    // Do some work that might cause an exception.  This might include calling
    // an independently written module that also wants to temporarily override
    // some handler, but they will pop that before returning to us.
    factory.popHandler();

Nicholas

>
> -- Daniel --,
>
>
> Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
>   
>> Daniel Julin wrote:
>>     
>>> I guess a two mode approach would make everyone happy. But would it
>>>       
> make
>   
>>> the API too complicated?
>>>
>>>
>>>       
>> I have some sympathy for what Steve is talking about -- maybe my
>> short-term memory is small, but when lots of single lines of code
>> inflate to 6 lines (and two indentation levels), it is definitely harder
>> for me to read.  However, I wouldn't want to give up the certain and
>> immediate catching of errors offered by exceptions.
>>
>> Would a mechanism like this work for the two-mode approach?
>>
>>     factory.setDataUnavailableHandler( new DataUnavailableHandler( ... )
>>     
> {
>   
>>         ...
>>     } );
>>
>> All objects created by the factory would call that object's
>> dataUnavailable() method when appropriate, passing it enough info about
>> what was going on to allow the method to make interesting decisions
>> about what to do.  The default handler would always throw a
>> DataUnavailableException.
>>
>> It's hard for me to tell whether something like that would really
>> suffice in actual use.  Perhaps it would have to be finer-grained, with
>> methods for javaObjectUnavailable(), imageSectionUnavailable(), etc.
>> Perhaps the defaults for those would call the more generic
>> dataUnavailable() so that you could intervene for all cases and/or for
>> individual cases as desired.
>>
>> Nicholas
>>
>>     
>
>

Re: Kato API javadoc - error handling

Posted by Daniel Julin <dp...@us.ibm.com>.

I like that approach a lot, because it may also address the other concern
that a proposed "default reasonable behavior" may not be appropriate for
all usage scenarios. We could probably come-up with a variety of handlers
for various common behaviors, like printing a simple error message,
completely ignoring the error, and lots of other creative responses.

Incidentally, nothing in this discussion is particularly specific to the
Kato API, is it? Are we saying that, in general, we don't like exceptions
as the standard mechanism to report errors in Java, and that we're
inventing new patterns?  If so, have any useful patterns been proposed and
documented previously in the literature?

-- Daniel --,

Nicholas.Sterling@Sun.COM wrote on 2009-04-11 01:48:53 AM:
> Daniel Julin wrote:
> > I guess a two mode approach would make everyone happy. But would it
make
> > the API too complicated?
> >
> >
> I have some sympathy for what Steve is talking about -- maybe my
> short-term memory is small, but when lots of single lines of code
> inflate to 6 lines (and two indentation levels), it is definitely harder
> for me to read.  However, I wouldn't want to give up the certain and
> immediate catching of errors offered by exceptions.
>
> Would a mechanism like this work for the two-mode approach?
>
>     factory.setDataUnavailableHandler( new DataUnavailableHandler( ... )
{
>         ...
>     } );
>
> All objects created by the factory would call that object's
> dataUnavailable() method when appropriate, passing it enough info about
> what was going on to allow the method to make interesting decisions
> about what to do.  The default handler would always throw a
> DataUnavailableException.
>
> It's hard for me to tell whether something like that would really
> suffice in actual use.  Perhaps it would have to be finer-grained, with
> methods for javaObjectUnavailable(), imageSectionUnavailable(), etc.
> Perhaps the defaults for those would call the more generic
> dataUnavailable() so that you could intervene for all cases and/or for
> individual cases as desired.
>
> Nicholas
>

Re: Kato API javadoc - error handling

Posted by Nicholas Sterling <Ni...@Sun.COM>.

Daniel Julin wrote:
> I guess a two mode approach would make everyone happy. But would it make
> the API too complicated?
>
>   
I have some sympathy for what Steve is talking about -- maybe my 
short-term memory is small, but when lots of single lines of code 
inflate to 6 lines (and two indentation levels), it is definitely harder 
for me to read.  However, I wouldn't want to give up the certain and 
immediate catching of errors offered by exceptions.

Would a mechanism like this work for the two-mode approach?

    factory.setDataUnavailableHandler( new DataUnavailableHandler( ... ) {
        ...
    } );

All objects created by the factory would call that object's 
dataUnavailable() method when appropriate, passing it enough info about 
what was going on to allow the method to make interesting decisions 
about what to do.  The default handler would always throw a 
DataUnavailableException.

It's hard for me to tell whether something like that would really 
suffice in actual use.  Perhaps it would have to be finer-grained, with 
methods for javaObjectUnavailable(), imageSectionUnavailable(), etc.  
Perhaps the defaults for those would call the more generic 
dataUnavailable() so that you could intervene for all cases and/or for 
individual cases as desired.

Nicholas

Re: Kato API javadoc - error handling

Posted by Daniel Julin <dp...@us.ibm.com>.

Steve Poole <sp...@googlemail.com> wrote on 2009-04-08 04:46:25 AM:
...
> I'm not happy with leaving things as they are, as currently the API is
not
> very programmer friendly.   I do understand the points made on this
subject
> so far but I still think that the  "no nulls" approach is the best
> approach.    Why?  here are my reasons
>
> 1 - Code robustness -  both API consumer and API provider have to deal
with
> missing or corrupt data - and this could happen anywhere at anytime.
> Programmers love to write  chained methods  like foo().getbar().getname()
> My real worry is that Joe RandomDeveloper will write his clever tool
using a
> favourite platform / dump  which then fails when run elsewhere because of
> unexpected missing data etc.

I think this issue of never returning nulls is distinct from the question
of how to properly report errors. Certainly we don't want to get nulls in
random places when there was some specific API error or problem, as this
may cause NullPointerExceptions that are indistinguishable from many other
kinds plain bugs that we may have in our code. In other words, non-buggy
code should never see NullPointerExceptions :-)

Having a dummy static or a well-defined and specific exceptions allows us
to carefully pinpoint what the problem is. As an added bonus, note that the
dummy value or the special exception can contain a "reason" string that
provides more detail about exactly what went wrong (many of the
DataUnavailable and CorruptDataExceptions thrown in the current
implementation do so already, and the DumpAnalyzer tool, for example,
prints these reason strings in the error log)

> 2 - Sensible default behaviour for missing or corrupt data -   Missing or
> corrupt data is an indicator that something is not right - what are you
> going to do with it?  Its either an "all bets are off" signal or you are
> just going to assume some default behavior.  We should do that for the
> programmer and make the API easier and friendlier to use.

Frankly, I'm not sure that we can define a reasonable default behavior that
is satisfactory for all possible use cases. I think we'd have to carefully
review a collection of real proposed used cases to be sure.

To use the DumpAnalyzer tool as an example, I can think of two main
behaviors that we use when encountering minor errors (there may be others
that just skip my mind at this time):

- sometime we print a detailed and very specific error indication, at a
very specific point in the output and in the right context. For example:

    Current Thread: [<unavailable>]

- sometime we set a flag to remember that one particular area of our
analysis is flawed, and use that knowledge to influence other parts of the
analysis. For example, while we're scanning all the JavaClassLoader and
JavaClasses to build a dictionary mapping class names to JavaClass
definitions. If we have an error while reading some of the JavaClass
instances but not all, or if we find multiple definitions of the same
class, we emit the dreaded message "Warning: class lookups may be
unreliable", but we continue building our classname dictionary, and use it
throughout the rest of the analysis. In practice, this particular example
happens a lot!



> 3 - Programmer friendlyness -   see above.   I absoletely hate the fact
that
> the current API design forces me to put try catch blocks around every
call.
> if I wanted to report the values on a object I have to do this sort of
> horror ...
>
> String field1=null;
> String field2=null;
>
> try {
>
>  field1=foo.getField1();
> }
> catch(DTFJException e} {
>    ;
> }
> try {
>
>  field2=foo.getField2();
> }
> catch(DTFJException e} {
>    ;
> }

I guess I don't get it. As a programmer, I'd like the compiler to tell me
about as many possible problems in my program at compile time, rather than
waiting until runtime tests to hope to catch all the things that I might
have forgotten to guard against. And I'm willing to pay a little price in
added ugliness and verbosity of my code, for that benefit.

And remember, if you don't want to handle errors at a fine granularity, you
don't have to put try/catch blocks everywhere. You can just put one single
global try/catch block around your entire program, and hope for the best...


>
> May be I'm arguing for a two mode approach  in which I can tell the API
if
> I want to receive exceptions or get default data.   I do know that I do
not
> want  perpertuate the above.

I guess a two mode approach would make everyone happy. But would it make
the API too complicated?



-- Daniel --

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

On Wed, Apr 8, 2009 at 9:06 AM, Carmine Cristallo <
carminecristallo@gmail.com> wrote:

> I agree with Julian. Both events (CorruptData and DataUnavailable) are to
> be
> seen as normal, and there's really no way to avoid writing client code that
> checks, in one way or another, for those events.Even if we implement
> Steve's
> suggestion (having a static value for each class that means "no data"), or
> if we reserve the "null" value for the same case (which is an option that
> I've been contemplating for some time in the past), that wouldn't change
> much for the client code, the only difference being that the "data
> unavailable" event would be checked with a "if... else" block rather than
> with a "try... catch". Of course, in the first case, the compiler won't
> oblige us to do the checking, but... is that really an advantage? What do
> we
> do with an empty value other than discard it?
>
> I would therefore vote for leaving things as they are.
>

I'm not happy with leaving things as they are, as currently the API is not
very programmer friendly.   I do understand the points made on this subject
so far but I still think that the  "no nulls" approach is the best
approach.    Why?  here are my reasons

1 - Code robustness -  both API consumer and API provider have to deal with
missing or corrupt data - and this could happen anywhere at anytime.
Programmers love to write  chained methods  like foo().getbar().getname()
My real worry is that Joe RandomDeveloper will write his clever tool using a
favourite platform / dump  which then fails when run elsewhere because of
unexpected missing data etc.

2 - Sensible default behaviour for missing or corrupt data -   Missing or
corrupt data is an indicator that something is not right - what are you
going to do with it?  Its either an "all bets are off" signal or you are
just going to assume some default behavior.  We should do that for the
programmer and make the API easier and friendlier to use.

3 - Programmer friendlyness -   see above.   I absoletely hate the fact that
the current API design forces me to put try catch blocks around every call.
if I wanted to report the values on a object I have to do this sort of
horror ...

String field1=null;
String field2=null;

try {

 field1=foo.getField1();
}
catch(DTFJException e} {
   ;
}
try {

 field2=foo.getField2();
}
catch(DTFJException e} {
   ;
}


May be I'm arguing for a two mode approach  in which I can tell the API  if
I want to receive exceptions or get default data.   I do know that I do not
want  perpertuate the above.





>
>     Carmine
>
> On Wed, Apr 8, 2009 at 2:17 AM, Daniel Julin <dp...@us.ibm.com> wrote:
>
> >
> >
> > I would like put in a good word in favor of checked exceptions.
> >
> > One key thing to keep mind is that minor errors are actually quite common
> > and often unavoidable when analyzing a dump. For example:
> >
> > * Some data items may appear corrupted or inconsistent because they were
> > caught "in flight" at the instant when the dump was generated
> >
> > * Some data items may not be present, depending on the circumstances, the
> > method used to obtain the dump and the implementation of a particular
> > reader. For example, in some cases dumps from Linux do not contain full
> > information about all the native threads, because the Linux kernel itself
> > does not put it in the dump.
> >
> > From our experiences with the DumpAnalyzer tool over the past couple of
> > years, it's not unusual to have dozens or even hundreds of small errors
> > like that while walking through a typical dump, and they do not generally
> > degrade the overall usefulness of the analysis. In the DTFJ API, these
> > result in a DataUnavailable or CorrupDataException. The DumpAnalyzer tool
> > catches the exception right at the point where it happens, prints a
> simple
> > "[<unavailable>]" or "[<corrupted>]" tag at the appropriate point in the
> > output, and moves on with the rest of the dump analysis.
> >
> > Having these reported through checked exceptions obviously makes it much
> > easier to write a tool that carefully checks for all such potential
> errors
> > and handles them in as narrow a scope as possible. The price is indeed
> that
> > we have to have try/catch blocks all over the place. It's annoying, but
> it
> > does not really make the code any more complicated than if we had to have
> > an explicit test for an invalid value everywhere. And, if our code
> > compiles, we can be sure that we did not forget to put a check for an
> error
> > condition somewhere. Unchecked exceptions, of course, do not give us that
> > guarantee.
> >
> > I recognize that, conversely, this makes life somewhat more complicated
> for
> > the sustaining engineer who wants to write a quick simple program for
> some
> > special analysis, and who does not want to spend a lot of time writing
> lots
> > of error handling code. But all these exceptions from the Kato API are
> > subclasses of DTFJException. So, he/she can simply declare every method
> in
> > his/her program with "throws DTFJException", and have a single global
> > try/catch block at the top level of the program to catch any
> DTFJException
> > and abort the program gracefully. Is that really too onerous?
> >
> >
> > -- Daniel --
> >
> >
> >
> > Nicholas.Sterling@Sun.COM wrote on 2009-04-06 06:11:35 PM:
> > >
> > > 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
> > >
> >
>

Re: Kato API javadoc

Posted by Carmine Cristallo <ca...@gmail.com>.

I agree with Julian. Both events (CorruptData and DataUnavailable) are to be
seen as normal, and there's really no way to avoid writing client code that
checks, in one way or another, for those events.Even if we implement Steve's
suggestion (having a static value for each class that means "no data"), or
if we reserve the "null" value for the same case (which is an option that
I've been contemplating for some time in the past), that wouldn't change
much for the client code, the only difference being that the "data
unavailable" event would be checked with a "if... else" block rather than
with a "try... catch". Of course, in the first case, the compiler won't
oblige us to do the checking, but... is that really an advantage? What do we
do with an empty value other than discard it?

I would therefore vote for leaving things as they are.


     Carmine

On Wed, Apr 8, 2009 at 2:17 AM, Daniel Julin <dp...@us.ibm.com> wrote:

>
>
> I would like put in a good word in favor of checked exceptions.
>
> One key thing to keep mind is that minor errors are actually quite common
> and often unavoidable when analyzing a dump. For example:
>
> * Some data items may appear corrupted or inconsistent because they were
> caught "in flight" at the instant when the dump was generated
>
> * Some data items may not be present, depending on the circumstances, the
> method used to obtain the dump and the implementation of a particular
> reader. For example, in some cases dumps from Linux do not contain full
> information about all the native threads, because the Linux kernel itself
> does not put it in the dump.
>
> From our experiences with the DumpAnalyzer tool over the past couple of
> years, it's not unusual to have dozens or even hundreds of small errors
> like that while walking through a typical dump, and they do not generally
> degrade the overall usefulness of the analysis. In the DTFJ API, these
> result in a DataUnavailable or CorrupDataException. The DumpAnalyzer tool
> catches the exception right at the point where it happens, prints a simple
> "[<unavailable>]" or "[<corrupted>]" tag at the appropriate point in the
> output, and moves on with the rest of the dump analysis.
>
> Having these reported through checked exceptions obviously makes it much
> easier to write a tool that carefully checks for all such potential errors
> and handles them in as narrow a scope as possible. The price is indeed that
> we have to have try/catch blocks all over the place. It's annoying, but it
> does not really make the code any more complicated than if we had to have
> an explicit test for an invalid value everywhere. And, if our code
> compiles, we can be sure that we did not forget to put a check for an error
> condition somewhere. Unchecked exceptions, of course, do not give us that
> guarantee.
>
> I recognize that, conversely, this makes life somewhat more complicated for
> the sustaining engineer who wants to write a quick simple program for some
> special analysis, and who does not want to spend a lot of time writing lots
> of error handling code. But all these exceptions from the Kato API are
> subclasses of DTFJException. So, he/she can simply declare every method in
> his/her program with "throws DTFJException", and have a single global
> try/catch block at the top level of the program to catch any DTFJException
> and abort the program gracefully. Is that really too onerous?
>
>
> -- Daniel --
>
>
>
> Nicholas.Sterling@Sun.COM wrote on 2009-04-06 06:11:35 PM:
> >
> > 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
> >
>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.

Hmmm.  I had it all wrong, then, thinking that 99% of the time our 
assumptions would be valid and we would skate through without an 
exception.  It sounds like in practice there is very little chance that 
a program that assumes the best would not die somewhere along the way, 
at least if it rummages around in the heap.  Thanks for straightening me 
out, Daniel.

Nicholas



Daniel Julin wrote:
> I would like put in a good word in favor of checked exceptions.
>
> One key thing to keep mind is that minor errors are actually quite common
> and often unavoidable when analyzing a dump. For example:
>
> * Some data items may appear corrupted or inconsistent because they were
> caught "in flight" at the instant when the dump was generated
>
> * Some data items may not be present, depending on the circumstances, the
> method used to obtain the dump and the implementation of a particular
> reader. For example, in some cases dumps from Linux do not contain full
> information about all the native threads, because the Linux kernel itself
> does not put it in the dump.
>
> From our experiences with the DumpAnalyzer tool over the past couple of
> years, it's not unusual to have dozens or even hundreds of small errors
> like that while walking through a typical dump, and they do not generally
> degrade the overall usefulness of the analysis. In the DTFJ API, these
> result in a DataUnavailable or CorrupDataException. The DumpAnalyzer tool
> catches the exception right at the point where it happens, prints a simple
> "[<unavailable>]" or "[<corrupted>]" tag at the appropriate point in the
> output, and moves on with the rest of the dump analysis.
>
> Having these reported through checked exceptions obviously makes it much
> easier to write a tool that carefully checks for all such potential errors
> and handles them in as narrow a scope as possible. The price is indeed that
> we have to have try/catch blocks all over the place. It's annoying, but it
> does not really make the code any more complicated than if we had to have
> an explicit test for an invalid value everywhere. And, if our code
> compiles, we can be sure that we did not forget to put a check for an error
> condition somewhere. Unchecked exceptions, of course, do not give us that
> guarantee.
>
> I recognize that, conversely, this makes life somewhat more complicated for
> the sustaining engineer who wants to write a quick simple program for some
> special analysis, and who does not want to spend a lot of time writing lots
> of error handling code. But all these exceptions from the Kato API are
> subclasses of DTFJException. So, he/she can simply declare every method in
> his/her program with "throws DTFJException", and have a single global
> try/catch block at the top level of the program to catch any DTFJException
> and abort the program gracefully. Is that really too onerous?
>
>
> -- Daniel --
>
>
>
> Nicholas.Sterling@Sun.COM wrote on 2009-04-06 06:11:35 PM:
>   
>> 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
>>
>>     
>
>

Re: Kato API javadoc

Posted by Daniel Julin <dp...@us.ibm.com>.


I would like put in a good word in favor of checked exceptions.

One key thing to keep mind is that minor errors are actually quite common
and often unavoidable when analyzing a dump. For example:

* Some data items may appear corrupted or inconsistent because they were
caught "in flight" at the instant when the dump was generated

* Some data items may not be present, depending on the circumstances, the
method used to obtain the dump and the implementation of a particular
reader. For example, in some cases dumps from Linux do not contain full
information about all the native threads, because the Linux kernel itself
does not put it in the dump.

From our experiences with the DumpAnalyzer tool over the past couple of
years, it's not unusual to have dozens or even hundreds of small errors
like that while walking through a typical dump, and they do not generally
degrade the overall usefulness of the analysis. In the DTFJ API, these
result in a DataUnavailable or CorrupDataException. The DumpAnalyzer tool
catches the exception right at the point where it happens, prints a simple
"[<unavailable>]" or "[<corrupted>]" tag at the appropriate point in the
output, and moves on with the rest of the dump analysis.

Having these reported through checked exceptions obviously makes it much
easier to write a tool that carefully checks for all such potential errors
and handles them in as narrow a scope as possible. The price is indeed that
we have to have try/catch blocks all over the place. It's annoying, but it
does not really make the code any more complicated than if we had to have
an explicit test for an invalid value everywhere. And, if our code
compiles, we can be sure that we did not forget to put a check for an error
condition somewhere. Unchecked exceptions, of course, do not give us that
guarantee.

I recognize that, conversely, this makes life somewhat more complicated for
the sustaining engineer who wants to write a quick simple program for some
special analysis, and who does not want to spend a lot of time writing lots
of error handling code. But all these exceptions from the Kato API are
subclasses of DTFJException. So, he/she can simply declare every method in
his/her program with "throws DTFJException", and have a single global
try/catch block at the top level of the program to catch any DTFJException
and abort the program gracefully. Is that really too onerous?


-- Daniel --



Nicholas.Sterling@Sun.COM wrote on 2009-04-06 06:11:35 PM:
>
> 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
>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.

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
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>             
>>>>         
>>>       
>
>

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

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
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>>
>>
>>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.

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.)

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
>>>>
>>>>
>>>>
>>>>       
>>
>>   
>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.


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
>>>
>>>
>>>
>>>       
>
>

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

On Wed, Apr 8, 2009 at 11:09 AM, Carmine Cristallo <
carminecristallo@gmail.com> wrote:

> What scares me is having to re-read whole threads of conversations of
> dozens
> of emails just to find out what subjects have been touched that require a
> decision.What I was thinking is that we could maybe create some form of
> work
> item about each of these subjects and move the discussion there, or to keep
> track of the items in some other structured way ... What do you think?
>

Ah - now I understand.  yes I agree it would be good to have a definitive
list of items for discussion - using jira to track an discussion item from
inception to final resolution would be great.  We should still keep the
topic discussion here though but in a separate thread.

>
>     Carmine
>
> On Mon, Apr 6, 2009 at 10:06 PM, Steve Poole <spoole167@googlemail.com
> >wrote:
>
> > On Mon, Apr 6, 2009 at 9:31 PM, Carmine Cristallo <
> > carminecristallo@gmail.com> wrote:
> >
> > > Hi all!A number of potential work items are starting to emerge from
> this
> > > thread. I'll try to enumerate them:
> > >
> > > 1. refactor the API to use generics. Basically, every method that now
> > > returns an Iterator should have its signature modified. And while we're
> > at
> > > it... is Iterator<...> the right "thing" to return? Wouldn't a
> collection
> > > (List<...>?) suit better?
> > > 2. give a better implementation - as the one suggested by Nicholas - to
> > > ImageThread#getRegister(). How about renaming it to "getRegisterMap()",
> > > returning a RegisterMap interface?
> > > 3. refactor the TCK to decouple the setup classes from the test
> classes,
> > as
> > > suggested by Stuart.
> > >
> > > Steve... should we start to open Jira work items for the above
> > activities?
> > >
> > > How about we just start some discussion threads on this list first -
> and
> > then create jira items to cover agreed changes to the API?
> >
> > >
> > >     Carmine
> > >
> > > On Mon, Apr 6, 2009 at 8:24 PM, Nicholas Sterling <
> > > Nicholas.Sterling@sun.com
> > > > wrote:
> > >
> > > > It's very nice being able to look at this javadoc -- thanks!
> > > >
> > > > It might help to have a little introductory text in some of the key
> > > classes
> > > > giving some context, something along the lines of the DTFJ example on
> > > your
> > > > web site that opens a core dump and iterates through the threads.
> > > >
> > > > I wonder if ImageThread should return interface RegisterSet, of which
> > > there
> > > > would be various implementations for various CPU types, each
> containing
> > a
> > > > map from a Register enum to a RegisterValue.
> > > >
> > > > I hadn't realized until I started looking through this javadoc how
> much
> > > > easier the use of generics makes it to understand an API.  For
> example,
> > > > under JavaClassLoader I see methods getCachedClasses() and
> > > > getDefinedClasses(), but I can't tell from their signatures whether
> > they
> > > > return the same type or not.  That info is in the method
> descriptions,
> > > but
> > > > it's a lot more work to flip back and forth between the Summary and
> the
> > > > Detail.
> > > >
> > > > Nicholas
> > > >
> > > >
> > > >
> > > > Steve Poole wrote:
> > > >
> > > >> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <
> > > >> Nicholas.Sterling@sun.com
> > > >>
> > > >>
> > > >>> wrote:
> > > >>>
> > > >>>
> > > >>
> > > >>
> > > >>
> > > >>> Great!  I've passed this on to the HotSpot folks for comment.
> > > >>>
> > > >>> I think I remember us talking about there being some provision for
> > > >>> accessing the vendor-specific VM constructs that implement the
> heap,
> > > >>> etc.,
> > > >>> in addition to the Java objects in it.  Will that be done by, for
> > > >>> example,
> > > >>> casting a JavaVM to a HotSpotVM and using the latter's extra
> methods?
> > > >>>
> > > >>>
> > > >>>
> > > >>
> > > >> That's the most obvious solution I think.
> > > >>
> > > >>
> > > >>
> > > >>> 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?
> > > >>
> > > >>
> > > >>
> > > >>> 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
> > > >>>>
> > > >>>>
> > > >>>>
> > > >>>>
> > > >>>>
> > > >>>
> > > >>
> > > >>
> > > >
> > >
> >
>

Re: Kato API javadoc

Posted by Carmine Cristallo <ca...@gmail.com>.

What scares me is having to re-read whole threads of conversations of dozens
of emails just to find out what subjects have been touched that require a
decision.What I was thinking is that we could maybe create some form of work
item about each of these subjects and move the discussion there, or to keep
track of the items in some other structured way ... What do you think?

     Carmine

On Mon, Apr 6, 2009 at 10:06 PM, Steve Poole <sp...@googlemail.com>wrote:

> On Mon, Apr 6, 2009 at 9:31 PM, Carmine Cristallo <
> carminecristallo@gmail.com> wrote:
>
> > Hi all!A number of potential work items are starting to emerge from this
> > thread. I'll try to enumerate them:
> >
> > 1. refactor the API to use generics. Basically, every method that now
> > returns an Iterator should have its signature modified. And while we're
> at
> > it... is Iterator<...> the right "thing" to return? Wouldn't a collection
> > (List<...>?) suit better?
> > 2. give a better implementation - as the one suggested by Nicholas - to
> > ImageThread#getRegister(). How about renaming it to "getRegisterMap()",
> > returning a RegisterMap interface?
> > 3. refactor the TCK to decouple the setup classes from the test classes,
> as
> > suggested by Stuart.
> >
> > Steve... should we start to open Jira work items for the above
> activities?
> >
> > How about we just start some discussion threads on this list first - and
> then create jira items to cover agreed changes to the API?
>
> >
> >     Carmine
> >
> > On Mon, Apr 6, 2009 at 8:24 PM, Nicholas Sterling <
> > Nicholas.Sterling@sun.com
> > > wrote:
> >
> > > It's very nice being able to look at this javadoc -- thanks!
> > >
> > > It might help to have a little introductory text in some of the key
> > classes
> > > giving some context, something along the lines of the DTFJ example on
> > your
> > > web site that opens a core dump and iterates through the threads.
> > >
> > > I wonder if ImageThread should return interface RegisterSet, of which
> > there
> > > would be various implementations for various CPU types, each containing
> a
> > > map from a Register enum to a RegisterValue.
> > >
> > > I hadn't realized until I started looking through this javadoc how much
> > > easier the use of generics makes it to understand an API.  For example,
> > > under JavaClassLoader I see methods getCachedClasses() and
> > > getDefinedClasses(), but I can't tell from their signatures whether
> they
> > > return the same type or not.  That info is in the method descriptions,
> > but
> > > it's a lot more work to flip back and forth between the Summary and the
> > > Detail.
> > >
> > > Nicholas
> > >
> > >
> > >
> > > Steve Poole wrote:
> > >
> > >> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <
> > >> Nicholas.Sterling@sun.com
> > >>
> > >>
> > >>> wrote:
> > >>>
> > >>>
> > >>
> > >>
> > >>
> > >>> Great!  I've passed this on to the HotSpot folks for comment.
> > >>>
> > >>> I think I remember us talking about there being some provision for
> > >>> accessing the vendor-specific VM constructs that implement the heap,
> > >>> etc.,
> > >>> in addition to the Java objects in it.  Will that be done by, for
> > >>> example,
> > >>> casting a JavaVM to a HotSpotVM and using the latter's extra methods?
> > >>>
> > >>>
> > >>>
> > >>
> > >> That's the most obvious solution I think.
> > >>
> > >>
> > >>
> > >>> 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?
> > >>
> > >>
> > >>
> > >>> 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
> > >>>>
> > >>>>
> > >>>>
> > >>>>
> > >>>>
> > >>>
> > >>
> > >>
> > >
> >
>

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

On Mon, Apr 6, 2009 at 9:31 PM, Carmine Cristallo <
carminecristallo@gmail.com> wrote:

> Hi all!A number of potential work items are starting to emerge from this
> thread. I'll try to enumerate them:
>
> 1. refactor the API to use generics. Basically, every method that now
> returns an Iterator should have its signature modified. And while we're at
> it... is Iterator<...> the right "thing" to return? Wouldn't a collection
> (List<...>?) suit better?
> 2. give a better implementation - as the one suggested by Nicholas - to
> ImageThread#getRegister(). How about renaming it to "getRegisterMap()",
> returning a RegisterMap interface?
> 3. refactor the TCK to decouple the setup classes from the test classes, as
> suggested by Stuart.
>
> Steve... should we start to open Jira work items for the above activities?
>
> How about we just start some discussion threads on this list first - and
then create jira items to cover agreed changes to the API?

>
>     Carmine
>
> On Mon, Apr 6, 2009 at 8:24 PM, Nicholas Sterling <
> Nicholas.Sterling@sun.com
> > wrote:
>
> > It's very nice being able to look at this javadoc -- thanks!
> >
> > It might help to have a little introductory text in some of the key
> classes
> > giving some context, something along the lines of the DTFJ example on
> your
> > web site that opens a core dump and iterates through the threads.
> >
> > I wonder if ImageThread should return interface RegisterSet, of which
> there
> > would be various implementations for various CPU types, each containing a
> > map from a Register enum to a RegisterValue.
> >
> > I hadn't realized until I started looking through this javadoc how much
> > easier the use of generics makes it to understand an API.  For example,
> > under JavaClassLoader I see methods getCachedClasses() and
> > getDefinedClasses(), but I can't tell from their signatures whether they
> > return the same type or not.  That info is in the method descriptions,
> but
> > it's a lot more work to flip back and forth between the Summary and the
> > Detail.
> >
> > Nicholas
> >
> >
> >
> > Steve Poole wrote:
> >
> >> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <
> >> Nicholas.Sterling@sun.com
> >>
> >>
> >>> wrote:
> >>>
> >>>
> >>
> >>
> >>
> >>> Great!  I've passed this on to the HotSpot folks for comment.
> >>>
> >>> I think I remember us talking about there being some provision for
> >>> accessing the vendor-specific VM constructs that implement the heap,
> >>> etc.,
> >>> in addition to the Java objects in it.  Will that be done by, for
> >>> example,
> >>> casting a JavaVM to a HotSpotVM and using the latter's extra methods?
> >>>
> >>>
> >>>
> >>
> >> That's the most obvious solution I think.
> >>
> >>
> >>
> >>> 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?
> >>
> >>
> >>
> >>> 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
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>
> >>>
> >>
> >>
> >
>

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

On Mon, Apr 6, 2009 at 10:25 PM, Nicholas Sterling <
Nicholas.Sterling@sun.com> wrote:

>
> It might be useful to tell the javadoc generator to create links out of
> java.* class names to the appropriate pages on another site.
>

Done!

>
> Nicholas
>
>
>
>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.

It might be useful to tell the javadoc generator to create links out of 
java.* class names to the appropriate pages on another site.

Nicholas

Re: Kato API javadoc - the order in which entries are returned from iterators

Posted by Stuart Monteith <st...@stoo.me.uk>.

I am curious as to what ordering would make sense - I think Dan would 
have elaborate on what ordering he does just now.
What do you mean by "fully connected"? At its extreme, as well as going 
from every JavaObject to their JavaClasses, you could go from a 
JavaClass to all of the JavaObjects that are instances of it.

Oh dear, I fear Dan is going to ask for that now :-)

Stuart

Steve Poole wrote:
> I assume that the ordering required is related to the type of analysis/query
> being run. If a fully connected graph was available between the various
> elements would that remove the need for ordering?
>
> On Wed, Apr 15, 2009 at 3:08 PM, Stuart Monteith <st...@stoo.me.uk> wrote:
>
>   
>> A colleague of mine has pointed out how the JavaClass.getObject() method is
>> optional - it might return null - the JavaDoc repeats this.
>> Still, if there are classes on the heap, it would be useful to be able to
>> understand what they are. It does raise the question of why we have
>> JavaClass.getObject() at all.
>>
>>
>> Stuart Monteith wrote:
>>
>>     
>>> Hi,
>>>   The link from JavaClass to it's JavaObject java/lang/Class instance but
>>> not vice-versa is a common problem, and I believe there should be a return
>>> path, simply because it is a typical thing to do.
>>>
>>> The situation with the ordering is even worse, things aren't returned in
>>> any defined order, with some exceptions (such as stack frames).
>>> However, which ordering would be correct? While there is certainly a case
>>> for evaluating the relationships between the JavaClasses, JavaClassLoader,
>>> JavaObjects,  JavaMonitor (There is "JavaObject JavaMonitor.getObject()" but
>>> no "JavaMonitor JavaObject.getMonitor()") etc., we can enumerate all of
>>> them, but the ordering of results is a more general question. Are we
>>> discussing SQL/OQL as a solution to that?
>>>
>>> How would the ordering be specified?
>>>
>>> A simple, but fixed way would be to offer precanned ordering:
>>>
>>> public class JavaClassLoader {
>>>   public enum Order { BYNAME, BYID, BYSUPERCLASSNAME, NONE};
>>>
>>>   public Iterator<JavaClass> getDefinedClasses(Order order);
>>>   public Iterator<JavaClass> getCachedClasses(Order order);
>>> }
>>>
>>> Would this be sufficient, or would we like to do more? Very often there
>>> isn't a lot to be said about a particular object without reference to
>>> others.
>>>
>>> Stuart
>>>
>>>
>>> Daniel Julin wrote:
>>>
>>>       
>>>> I like the idea of __asking__ the API if it could please give us the
>>>> entries in a particular order, but accepting the fact that maybe it can't
>>>> and dealing with that case explicitly when needed.
>>>>
>>>> What drives me crazy right now is having to expensively sort lots of
>>>> entries in my analyzer modules, and thinking that maybe the underlying
>>>> core
>>>> reader library could have given me these entries in the right order much
>>>> more cheaply, if only I could ask.
>>>>
>>>> Note that this principle of taking advantage of shortcuts that may
>>>> optionally be available in the core reader library implementation, may
>>>> not
>>>> be limited to the order of entries in iterators. For example, in the
>>>> current API, if you're looking at an instance of JavaObject that happens
>>>> to
>>>> be of type java/lang/Class, there is no direct way to get the JavaClass
>>>> corresponding to the class for which this object is the class object. You
>>>> have to go all the way around, enumerate all the JavaClassLoaders and all
>>>> their defined JavaClasses, until you find one whose JavaClass.getObject()
>>>> is equal to your original JavaObject. I believe this is because in some
>>>> implementations of the core readers, providing this direct link would be
>>>> just as expensive as the roundabout way that I just described. But I have
>>>> to believe that in some other core reader implementations, this link
>>>> could
>>>> be provided much more cheaply. So could we take advantage of it when
>>>> possible?
>>>>
>>>>
>>>> -- Daniel --
>>>>
>>>>
>>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-08 02:37:06 AM:
>>>>
>>>>
>>>>
>>>>         
>>>>> Daniel Julin wrote:
>>>>>
>>>>>
>>>>>           
>>>>>> Some thoughts about these iterators, also based on earlier experiences
>>>>>>
>>>>>>
>>>>>>             
>>>>> with
>>>>>           
>>>>         
>>>>> the DumpAnalyzer tool:
>>>>>           
>>>>>>
>>>>>>             
>>>>> ...
>>>>>           
>>>>         
>>>>> (2) The API does not actually define any specific order in which the
>>>>>           
>>>>>> entries are returned by the various iterators, and I wish it would. For
>>>>>> example:
>>>>>>
>>>>>> * When walking through all the objects on a heap, some heap analysis
>>>>>> functions (and some file formats like PHD) require that the objects be
>>>>>> returned in the order corresponding to the increasing addresses where
>>>>>>
>>>>>>
>>>>>>             
>>>>> they
>>>>>           
>>>>         
>>>>> are located on that heap.  It turns out that, in all the
>>>>>           
>>>>>>             
>>>>> implementations
>>>>>           
>>>>         
>>>>> that I've seen so far, JavaHeap.getObjects() does provide that order,
>>>>>           
>>>>>>             
>>>>> but
>>>>>           
>>>>         
>>>>> nowhere does it say that I can count on it in every future
>>>>>           
>>>>>>             
>>>>> implementation.
>>>>>           
>>>>         
>>>>> Of course, for some future collector it might be difficult to produce
>>>>> the objects in that order.  What if there were a way of setting the
>>>>> order you want, and if the provider can't do it, then it could throw an
>>>>> exception saying that that's unimplemented.
>>>>>
>>>>>
>>>>>           
>
>

Re: Kato API javadoc - the order in which entries are returned from iterators

Posted by Steve Poole <sp...@googlemail.com>.

I assume that the ordering required is related to the type of analysis/query
being run. If a fully connected graph was available between the various
elements would that remove the need for ordering?

On Wed, Apr 15, 2009 at 3:08 PM, Stuart Monteith <st...@stoo.me.uk> wrote:

> A colleague of mine has pointed out how the JavaClass.getObject() method is
> optional - it might return null - the JavaDoc repeats this.
> Still, if there are classes on the heap, it would be useful to be able to
> understand what they are. It does raise the question of why we have
> JavaClass.getObject() at all.
>
>
> Stuart Monteith wrote:
>
>> Hi,
>>   The link from JavaClass to it's JavaObject java/lang/Class instance but
>> not vice-versa is a common problem, and I believe there should be a return
>> path, simply because it is a typical thing to do.
>>
>> The situation with the ordering is even worse, things aren't returned in
>> any defined order, with some exceptions (such as stack frames).
>> However, which ordering would be correct? While there is certainly a case
>> for evaluating the relationships between the JavaClasses, JavaClassLoader,
>> JavaObjects,  JavaMonitor (There is "JavaObject JavaMonitor.getObject()" but
>> no "JavaMonitor JavaObject.getMonitor()") etc., we can enumerate all of
>> them, but the ordering of results is a more general question. Are we
>> discussing SQL/OQL as a solution to that?
>>
>> How would the ordering be specified?
>>
>> A simple, but fixed way would be to offer precanned ordering:
>>
>> public class JavaClassLoader {
>>   public enum Order { BYNAME, BYID, BYSUPERCLASSNAME, NONE};
>>
>>   public Iterator<JavaClass> getDefinedClasses(Order order);
>>   public Iterator<JavaClass> getCachedClasses(Order order);
>> }
>>
>> Would this be sufficient, or would we like to do more? Very often there
>> isn't a lot to be said about a particular object without reference to
>> others.
>>
>> Stuart
>>
>>
>> Daniel Julin wrote:
>>
>>> I like the idea of __asking__ the API if it could please give us the
>>> entries in a particular order, but accepting the fact that maybe it can't
>>> and dealing with that case explicitly when needed.
>>>
>>> What drives me crazy right now is having to expensively sort lots of
>>> entries in my analyzer modules, and thinking that maybe the underlying
>>> core
>>> reader library could have given me these entries in the right order much
>>> more cheaply, if only I could ask.
>>>
>>> Note that this principle of taking advantage of shortcuts that may
>>> optionally be available in the core reader library implementation, may
>>> not
>>> be limited to the order of entries in iterators. For example, in the
>>> current API, if you're looking at an instance of JavaObject that happens
>>> to
>>> be of type java/lang/Class, there is no direct way to get the JavaClass
>>> corresponding to the class for which this object is the class object. You
>>> have to go all the way around, enumerate all the JavaClassLoaders and all
>>> their defined JavaClasses, until you find one whose JavaClass.getObject()
>>> is equal to your original JavaObject. I believe this is because in some
>>> implementations of the core readers, providing this direct link would be
>>> just as expensive as the roundabout way that I just described. But I have
>>> to believe that in some other core reader implementations, this link
>>> could
>>> be provided much more cheaply. So could we take advantage of it when
>>> possible?
>>>
>>>
>>> -- Daniel --
>>>
>>>
>>> Nicholas.Sterling@Sun.COM wrote on 2009-04-08 02:37:06 AM:
>>>
>>>
>>>
>>>> Daniel Julin wrote:
>>>>
>>>>
>>>>> Some thoughts about these iterators, also based on earlier experiences
>>>>>
>>>>>
>>>> with
>>>
>>>
>>>> the DumpAnalyzer tool:
>>>>>
>>>>>
>>>>>
>>>> ...
>>>
>>>
>>>> (2) The API does not actually define any specific order in which the
>>>>> entries are returned by the various iterators, and I wish it would. For
>>>>> example:
>>>>>
>>>>> * When walking through all the objects on a heap, some heap analysis
>>>>> functions (and some file formats like PHD) require that the objects be
>>>>> returned in the order corresponding to the increasing addresses where
>>>>>
>>>>>
>>>> they
>>>
>>>
>>>> are located on that heap.  It turns out that, in all the
>>>>>
>>>>>
>>>> implementations
>>>
>>>
>>>> that I've seen so far, JavaHeap.getObjects() does provide that order,
>>>>>
>>>>>
>>>> but
>>>
>>>
>>>> nowhere does it say that I can count on it in every future
>>>>>
>>>>>
>>>> implementation.
>>>
>>>
>>>> Of course, for some future collector it might be difficult to produce
>>>> the objects in that order.  What if there were a way of setting the
>>>> order you want, and if the provider can't do it, then it could throw an
>>>> exception saying that that's unimplemented.
>>>>
>>>>
>>>

Re: Kato API javadoc - the order in which entries are returned from iterators

Posted by Stuart Monteith <st...@stoo.me.uk>.

A colleague of mine has pointed out how the JavaClass.getObject() method 
is optional - it might return null - the JavaDoc repeats this.
Still, if there are classes on the heap, it would be useful to be able 
to understand what they are. It does raise the question of why we have 
JavaClass.getObject() at all.

Stuart Monteith wrote:
> Hi,
>    The link from JavaClass to it's JavaObject java/lang/Class instance 
> but not vice-versa is a common problem, and I believe there should be 
> a return path, simply because it is a typical thing to do.
>
> The situation with the ordering is even worse, things aren't returned 
> in any defined order, with some exceptions (such as stack frames).
> However, which ordering would be correct? While there is certainly a 
> case for evaluating the relationships between the JavaClasses, 
> JavaClassLoader, JavaObjects,  JavaMonitor (There is "JavaObject 
> JavaMonitor.getObject()" but no "JavaMonitor JavaObject.getMonitor()") 
> etc., we can enumerate all of them, but the ordering of results is a 
> more general question. Are we discussing SQL/OQL as a solution to that?
>
> How would the ordering be specified?
>
> A simple, but fixed way would be to offer precanned ordering:
>
> public class JavaClassLoader {
>    public enum Order { BYNAME, BYID, BYSUPERCLASSNAME, NONE};
>
>    public Iterator<JavaClass> getDefinedClasses(Order order);
>    public Iterator<JavaClass> getCachedClasses(Order order);
> }
>
> Would this be sufficient, or would we like to do more? Very often 
> there isn't a lot to be said about a particular object without 
> reference to others.
>
> Stuart
>
>
> Daniel Julin wrote:
>> I like the idea of __asking__ the API if it could please give us the
>> entries in a particular order, but accepting the fact that maybe it 
>> can't
>> and dealing with that case explicitly when needed.
>>
>> What drives me crazy right now is having to expensively sort lots of
>> entries in my analyzer modules, and thinking that maybe the 
>> underlying core
>> reader library could have given me these entries in the right order much
>> more cheaply, if only I could ask.
>>
>> Note that this principle of taking advantage of shortcuts that may
>> optionally be available in the core reader library implementation, 
>> may not
>> be limited to the order of entries in iterators. For example, in the
>> current API, if you're looking at an instance of JavaObject that 
>> happens to
>> be of type java/lang/Class, there is no direct way to get the JavaClass
>> corresponding to the class for which this object is the class object. 
>> You
>> have to go all the way around, enumerate all the JavaClassLoaders and 
>> all
>> their defined JavaClasses, until you find one whose 
>> JavaClass.getObject()
>> is equal to your original JavaObject. I believe this is because in some
>> implementations of the core readers, providing this direct link would be
>> just as expensive as the roundabout way that I just described. But I 
>> have
>> to believe that in some other core reader implementations, this link 
>> could
>> be provided much more cheaply. So could we take advantage of it when
>> possible?
>>
>>
>> -- Daniel --
>>
>>
>> Nicholas.Sterling@Sun.COM wrote on 2009-04-08 02:37:06 AM:
>>
>>  
>>> Daniel Julin wrote:
>>>    
>>>> Some thoughts about these iterators, also based on earlier experiences
>>>>       
>> with
>>  
>>>> the DumpAnalyzer tool:
>>>>
>>>>       
>> ...
>>  
>>>> (2) The API does not actually define any specific order in which the
>>>> entries are returned by the various iterators, and I wish it would. 
>>>> For
>>>> example:
>>>>
>>>> * When walking through all the objects on a heap, some heap analysis
>>>> functions (and some file formats like PHD) require that the objects be
>>>> returned in the order corresponding to the increasing addresses where
>>>>       
>> they
>>  
>>>> are located on that heap.  It turns out that, in all the
>>>>       
>> implementations
>>  
>>>> that I've seen so far, JavaHeap.getObjects() does provide that order,
>>>>       
>> but
>>  
>>>> nowhere does it say that I can count on it in every future
>>>>       
>> implementation.
>>  
>>> Of course, for some future collector it might be difficult to produce
>>> the objects in that order.  What if there were a way of setting the
>>> order you want, and if the provider can't do it, then it could throw an
>>> exception saying that that's unimplemented.
>>>

Re: Kato API javadoc - the order in which entries are returned from iterators

Posted by Stuart Monteith <st...@stoo.me.uk>.

Hi,
    The link from JavaClass to it's JavaObject java/lang/Class instance 
but not vice-versa is a common problem, and I believe there should be a 
return path, simply because it is a typical thing to do.

The situation with the ordering is even worse, things aren't returned in 
any defined order, with some exceptions (such as stack frames).
However, which ordering would be correct? While there is certainly a 
case for evaluating the relationships between the JavaClasses, 
JavaClassLoader, JavaObjects,  JavaMonitor (There is "JavaObject 
JavaMonitor.getObject()" but no "JavaMonitor JavaObject.getMonitor()") 
etc., we can enumerate all of them, but the ordering of results is a 
more general question. Are we discussing SQL/OQL as a solution to that?

How would the ordering be specified?

A simple, but fixed way would be to offer precanned ordering:

public class JavaClassLoader {
    public enum Order { BYNAME, BYID, BYSUPERCLASSNAME, NONE};

    public Iterator<JavaClass> getDefinedClasses(Order order);
    public Iterator<JavaClass> getCachedClasses(Order order);
}

Would this be sufficient, or would we like to do more? Very often there 
isn't a lot to be said about a particular object without reference to 
others.

Stuart


Daniel Julin wrote:
> I like the idea of __asking__ the API if it could please give us the
> entries in a particular order, but accepting the fact that maybe it can't
> and dealing with that case explicitly when needed.
>
> What drives me crazy right now is having to expensively sort lots of
> entries in my analyzer modules, and thinking that maybe the underlying core
> reader library could have given me these entries in the right order much
> more cheaply, if only I could ask.
>
> Note that this principle of taking advantage of shortcuts that may
> optionally be available in the core reader library implementation, may not
> be limited to the order of entries in iterators. For example, in the
> current API, if you're looking at an instance of JavaObject that happens to
> be of type java/lang/Class, there is no direct way to get the JavaClass
> corresponding to the class for which this object is the class object. You
> have to go all the way around, enumerate all the JavaClassLoaders and all
> their defined JavaClasses, until you find one whose JavaClass.getObject()
> is equal to your original JavaObject. I believe this is because in some
> implementations of the core readers, providing this direct link would be
> just as expensive as the roundabout way that I just described. But I have
> to believe that in some other core reader implementations, this link could
> be provided much more cheaply. So could we take advantage of it when
> possible?
>
>
> -- Daniel --
>
>
> Nicholas.Sterling@Sun.COM wrote on 2009-04-08 02:37:06 AM:
>
>   
>> Daniel Julin wrote:
>>     
>>> Some thoughts about these iterators, also based on earlier experiences
>>>       
> with
>   
>>> the DumpAnalyzer tool:
>>>
>>>       
> ...
>   
>>> (2) The API does not actually define any specific order in which the
>>> entries are returned by the various iterators, and I wish it would. For
>>> example:
>>>
>>> * When walking through all the objects on a heap, some heap analysis
>>> functions (and some file formats like PHD) require that the objects be
>>> returned in the order corresponding to the increasing addresses where
>>>       
> they
>   
>>> are located on that heap.  It turns out that, in all the
>>>       
> implementations
>   
>>> that I've seen so far, JavaHeap.getObjects() does provide that order,
>>>       
> but
>   
>>> nowhere does it say that I can count on it in every future
>>>       
> implementation.
>   
>> Of course, for some future collector it might be difficult to produce
>> the objects in that order.  What if there were a way of setting the
>> order you want, and if the provider can't do it, then it could throw an
>> exception saying that that's unimplemented.
>>

Re: Kato API javadoc - the order in which entries are returned from iterators

Posted by Daniel Julin <dp...@us.ibm.com>.

I like the idea of __asking__ the API if it could please give us the
entries in a particular order, but accepting the fact that maybe it can't
and dealing with that case explicitly when needed.

What drives me crazy right now is having to expensively sort lots of
entries in my analyzer modules, and thinking that maybe the underlying core
reader library could have given me these entries in the right order much
more cheaply, if only I could ask.

Note that this principle of taking advantage of shortcuts that may
optionally be available in the core reader library implementation, may not
be limited to the order of entries in iterators. For example, in the
current API, if you're looking at an instance of JavaObject that happens to
be of type java/lang/Class, there is no direct way to get the JavaClass
corresponding to the class for which this object is the class object. You
have to go all the way around, enumerate all the JavaClassLoaders and all
their defined JavaClasses, until you find one whose JavaClass.getObject()
is equal to your original JavaObject. I believe this is because in some
implementations of the core readers, providing this direct link would be
just as expensive as the roundabout way that I just described. But I have
to believe that in some other core reader implementations, this link could
be provided much more cheaply. So could we take advantage of it when
possible?

-- Daniel --

Nicholas.Sterling@Sun.COM wrote on 2009-04-08 02:37:06 AM:

> Daniel Julin wrote:
> > Some thoughts about these iterators, also based on earlier experiences
with
> > the DumpAnalyzer tool:
> >
...
> > (2) The API does not actually define any specific order in which the
> > entries are returned by the various iterators, and I wish it would. For
> > example:
> >
> > * When walking through all the objects on a heap, some heap analysis
> > functions (and some file formats like PHD) require that the objects be
> > returned in the order corresponding to the increasing addresses where
they
> > are located on that heap.  It turns out that, in all the
implementations
> > that I've seen so far, JavaHeap.getObjects() does provide that order,
but
> > nowhere does it say that I can count on it in every future
implementation.
> >
> Of course, for some future collector it might be difficult to produce
> the objects in that order.  What if there were a way of setting the
> order you want, and if the provider can't do it, then it could throw an
> exception saying that that's unimplemented.

Re: Kato API javadoc - using Iterable

Posted by Daniel Julin <dp...@us.ibm.com>.

Just to make matters a little bit more complicated for the use of Iterable,
please note that for some current Kato/DTFJ objects, there is more than one
potential iterator __of the same type__.

For example, JavaClassLoader has both a getCachedClasses() and a
getDefinedClasses() method, both of which return an iterator of JavaClass.
There may be others....


-- Daniel --


Nicholas.Sterling@Sun.COM wrote on 2009-04-09 06:08:08 PM:
> Steve Poole wrote:
> > On Wed, Apr 8, 2009 at 7:37 AM, Nicholas Sterling
<Nicholas.Sterling@sun.
> >
> > Rather than returning an Iterator for the objects on the heap, why not
make
> > JavaHeap extend Iterable?  That way we could write
> >
> >   for ( JavaObject object : heap ) { ... }
> >
> > without having to call getObjects().  If we are using generics, I
believe
> > this would work for both objects and sections, because we would extend
both
> > Iterable<JavaObject> and Iterable<ImageSection>,  i.e.
> >
> >   for ( JavaObject   object  : heap ) { ... }
> >   for ( ImageSection section : heap ) { ... }
> >
> >
> >
> > Two questions
> >
> > 1) Isn't an Iterable just an iterator under the covers?
> >
> An Iterable is a thing which can *return* an Iterator via the iterator()
> method.  In a for-statement like those above, the thing after the colon
> has to be Iterable, because the compiler is going to generate code to
> ask for its Iterator.
> > 2) I thought you could only have one Iterable implemented by a class?
> >
> >
> Unfortunately, you are right.  The following does not work:
>
>     import java.util.ArrayList;
>
>     public class GenericInterfaceTest
>         _implements Iterable<String>, Iterable<Integer>_ {
>
>         ArrayList<String>  strings  = new ArrayList<String >();
>         ArrayList<Integer> integers = new ArrayList<Integer>();
>
>         public GenericInterfaceTest() {
>             strings.add("foo");
>             strings.add("bar");
>             integers.add(1);
>             integers.add(2);
>         }
>
>         _public Iterator<String> iterator()_ {
>             return strings.iterator();
>         }
>
>         _public Iterator<Integer> iterator()_ {
>             return integers.iterator();
>         }
>
>         public static void main( String[] args ) {
>             GenericInterfaceTest git = new GenericInterfaceTest();
>             for ( String  string  : git ) { System.out.println
( string  ); }
>             for ( Integer integer : git ) { System.out.println
( integer ); }
>         }
>     }
>
> Since the method being interited from the interface, iterator(), only
> differs in its return type, it can't work.  Actually, I think
> implementing the same interface twice with different types is disallowed
> in any case because of type erasure
> <http://forums-beta.sun.com/thread.jspa?messageID=1418132>.
>
> Presumably the list of sections is of manageable size, though, so we
> could have a method that returns a List of them, such that we could say
>
>   for ( JavaObject   object  : heap            ) { ... }
>   for ( ImageSection section : heap.sections() ) { ... }

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.


Steve Poole wrote:
> On Wed, Apr 8, 2009 at 7:37 AM, Nicholas Sterling <Nicholas.Sterling@sun.
>
> Rather than returning an Iterator for the objects on the heap, why not make
> JavaHeap extend Iterable?  That way we could write
>
>   for ( JavaObject object : heap ) { ... }
>
> without having to call getObjects().  If we are using generics, I believe
> this would work for both objects and sections, because we would extend both
> Iterable<JavaObject> and Iterable<ImageSection>,  i.e.
>
>   for ( JavaObject   object  : heap ) { ... }
>   for ( ImageSection section : heap ) { ... }
>
>   
>
> Two questions
>
> 1) Isn't an Iterable just an iterator under the covers?
>   
An Iterable is a thing which can *return* an Iterator via the iterator() 
method.  In a for-statement like those above, the thing after the colon 
has to be Iterable, because the compiler is going to generate code to 
ask for its Iterator.
> 2) I thought you could only have one Iterable implemented by a class?
>
>   
Unfortunately, you are right.  The following does not work:

    import java.util.ArrayList;

    public class GenericInterfaceTest
        _implements Iterable<String>, Iterable<Integer>_ {

        ArrayList<String>  strings  = new ArrayList<String >();
        ArrayList<Integer> integers = new ArrayList<Integer>();

        public GenericInterfaceTest() {
            strings.add("foo");
            strings.add("bar");
            integers.add(1);
            integers.add(2);
        }

        _public Iterator<String> iterator()_ {
            return strings.iterator();
        }

        _public Iterator<Integer> iterator()_ {
            return integers.iterator();
        }

        public static void main( String[] args ) {
            GenericInterfaceTest git = new GenericInterfaceTest();
            for ( String  string  : git ) { System.out.println( string  ); }
            for ( Integer integer : git ) { System.out.println( integer ); }
        }
    }

Since the method being interited from the interface, iterator(), only 
differs in its return type, it can't work.  Actually, I think 
implementing the same interface twice with different types is disallowed 
in any case because of type erasure 
<http://forums-beta.sun.com/thread.jspa?messageID=1418132>.

Presumably the list of sections is of manageable size, though, so we 
could have a method that returns a List of them, such that we could say

  for ( JavaObject   object  : heap            ) { ... }
  for ( ImageSection section : heap.sections() ) { ... }


>>> (3) At various times in the past, we had some discussions about
>>> potentially
>>> using a cursor-style API rather than an iterator, for large sets like the
>>> one from JavaHeap.getObjects(), to avoid excessive object allocation in
>>> the
>>> analyzer tool JVM.  How do you feel about that?
>>>
>>>
>>>       
>> Between fast allocation techniques, fast GC for short-lived objects, and
>> the use of escape analysis to enable stack allocation, I'm not sure there's
>> a big win in a cursor-style API.  Is the main disadvantage of a cursor-style
>> API that you have to copy objects if you want to remember them, as opposed
>> to just hanging on to references as they fly by?
>>     
>
>
> The big win for the cursor design is that you do not have to create any new
> objects when visiting a list - so you could argue that copying just what you
> want need is actually a blessing not a curse.
>
>   
Yes, I agree, and it may be worth doing.  But my point was that avoiding 
allocation and GC of short-lived objects is almost surely not a *big* 
win in a modern VM, and we should have reasonable expectations.  Let's 
suppose for the moment that the net effect of using a cursor approach is 
to make diagnostic tools doing mostly that kind of work, say, 5-10% 
faster -- is that worth forcing people to explicitly copy objects?  
Cursors were a big win at the time JDBC was created because object 
allocation and GC were huge performance problems at the time.

If we did use cursors, would clone() be sufficient to copy a JavaObject, 
or would a deeper copy be required?

Again, I'm not really opposed to the use of cursors.  I just don't want 
us to go that route in hopes of achieving a big performance benefit, 
because that's probably not realistic.

Nicholas

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

On Wed, Apr 8, 2009 at 7:37 AM, Nicholas Sterling <Nicholas.Sterling@sun.com
> wrote:

>
>
> Daniel Julin wrote:
>
>> Some thoughts about these iterators, also based on earlier experiences
>> with
>> the DumpAnalyzer tool:
>>
>>
>> (1) The set of entries returned by some of these iterators can be quite
>> large. Especially for JavaHeap.getObjects(), and also, to a lesser degree,
>> JavaClassLoader.getDefinedClasses(), ImageModule.getSymbols(), etc. If we
>> go to a model that allows random access, can we do it in a way that avoids
>> forcing a pre-loading of every instance of every entry in the set, onto
>> the
>> heap of the JVM in which we are running the analyzer tool.
>>
>>
>>
>>
> Yes, and we should be very careful about assuming that a particular list
> will be small in all future VMs.
>
> Rather than returning an Iterator for the objects on the heap, why not make
> JavaHeap extend Iterable?  That way we could write
>
>   for ( JavaObject object : heap ) { ... }
>
> without having to call getObjects().  If we are using generics, I believe
> this would work for both objects and sections, because we would extend both
> Iterable<JavaObject> and Iterable<ImageSection>,  i.e.
>
>   for ( JavaObject   object  : heap ) { ... }
>   for ( ImageSection section : heap ) { ... }
>

Two questions

1) Isn't an Iterable just an iterator under the covers?
2) I thought you could only have one Iterable implemented by a class?


>
>  (2) The API does not actually define any specific order in which the
>> entries are returned by the various iterators, and I wish it would. For
>> example:
>>
>> * When walking through all the objects on a heap, some heap analysis
>> functions (and some file formats like PHD) require that the objects be
>> returned in the order corresponding to the increasing addresses where they
>> are located on that heap.  It turns out that, in all the implementations
>> that I've seen so far, JavaHeap.getObjects() does provide that order, but
>> nowhere does it say that I can count on it in every future implementation.
>>
>>
> Of course, for some future collector it might be difficult to produce the
> objects in that order.  What if there were a way of setting the order you
> want, and if the provider can't do it, then it could throw an exception
> saying that that's unimplemented.
>
>> * When writing unit tests for analysis tools, it is very convenient to be
>> able to count on a stable order returned by every iterator. Many tests can
>> be written by printing all the output from some function, and simply
>> comparing that output from one run of the tool to the next to detect
>> regressions. This stable order was actually not provided by many iterators
>> in current DTFJ implementations, and has caused considerable headache in
>> the early days of the implementation of the DumpAnalyzer tool. We ended-up
>> adding our own sort routines on top of many DTFJ iterators... which of
>> course conflicts with point (1) above, to avoid pre-loading every entry.
>>
>>
>> (3) At various times in the past, we had some discussions about
>> potentially
>> using a cursor-style API rather than an iterator, for large sets like the
>> one from JavaHeap.getObjects(), to avoid excessive object allocation in
>> the
>> analyzer tool JVM.  How do you feel about that?
>>
>>
>>
> Between fast allocation techniques, fast GC for short-lived objects, and
> the use of escape analysis to enable stack allocation, I'm not sure there's
> a big win in a cursor-style API.  Is the main disadvantage of a cursor-style
> API that you have to copy objects if you want to remember them, as opposed
> to just hanging on to references as they fly by?


The big win for the cursor design is that you do not have to create any new
objects when visiting a list - so you could argue that copying just what you
want need is actually a blessing not a curse.



>
> Nicholas
>
>
>
>
>
>> -- Daniel --
>>
>>
>>
>> Steve Poole <sp...@googlemail.com> wrote on 2009-04-06 05:19:07 PM:
>>
>>
>>> On Mon, Apr 6, 2009 at 9:45 PM, Nicholas Sterling
>>>
>>>
>> <Nicholas.Sterling@sun.com
>>
>>
>>> wrote:
>>>>      Carmine Cristallo wrote:
>>>>
>>>>
>>>>
>>>>> Hi all!A number of potential work items are starting to emerge from
>>>>>
>>>>>
>>>> this
>>
>>
>>> thread. I'll try to enumerate them:
>>>>>
>>>>> 1. refactor the API to use generics. Basically, every method that now
>>>>> returns an Iterator should have its signature modified. And while
>>>>>
>>>>>
>>>> we're at
>>
>>
>>> it... is Iterator<...> the right "thing" to return? Wouldn't a
>>>>>
>>>>>
>>>> collection
>>
>>
>>> (List<...>?) suit better?
>>>>>
>>>>>
>>>>>
>>>>>
>>>> Ah, good point, although there might be some cases where the number of
>>>> values would be huge (like objects on the heap), and for those you
>>>>
>>>>
>>> probably
>>
>>
>>> do just want to provide an Iterator.
>>>>
>>>>
>>>>
>>> The main problem with iterators is providing any sort of random access.
>>>
>>>
>> You
>>
>>
>>> end up with repeated walks through the iterator.   Having lists seemed
>>>
>>>
>> like
>>
>>
>>> a good alternative.  I took a copy of DTFJ last year and replaced the
>>> iterators with lists -  then I  easily added a jxpath  (
>>> http://commons.apache.org/jxpath/)  layer on top.  It was pretty cool -
>>>
>>>
>> if
>>
>>
>>> we agree on providing a random access mechanism of any sort it should be
>>> fairly simple to redo the jxpath experiment.
>>>
>>>
>>>
>>>> That reminds me -- Steve, weren't you talking about an event-driven
>>>> (SAX-like) parser at one point, in which one specifies the classes of
>>>> interest in the target heap and the code to be executed for each? I
>>>>
>>>>
>>> suppose
>>
>>
>>> that could, and probably should be, build on *top* of an Iterator.
>>>>
>>>>
>>>>
>>> Yes - I was wondering out loud if the "DOM" approach we have with the API
>>>
>>>
>> is
>>
>>
>>> sufficent.   Its obvious when you start implementing the underlying
>>>
>>>
>> support
>>
>>
>>> for this sort of API just how important it is to be lazy. A "SAX" like
>>> approach could possibly provide  oppotunities to be even lazier!.
>>>
>>>
>>>
>>>> Nicholas
>>>>
>>>>
>>>>  2. give a better implementation - as the one suggested by Nicholas -
>>>>
>>>>
>>> to
>>
>>
>>> ImageThread#getRegister(). How about renaming it to "getRegisterMap
>>>>>
>>>>>
>>>> ()",
>>
>>
>>> returning a RegisterMap interface?
>>>>> 3. refactor the TCK to decouple the setup classes from the test
>>>>>
>>>>>
>>>> classes,
>>
>>
>>> as
>>>>> suggested by Stuart.
>>>>>
>>>>> Steve... should we start to open Jira work items for the above
>>>>>
>>>>>
>>>> activities?
>>
>>
>>>    Carmine
>>>>>
>>>>> On Mon, Apr 6, 2009 at 8:24 PM, Nicholas Sterling <
>>>>> Nicholas.Sterling@sun.com
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>> wrote:
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>>> It's very nice being able to look at this javadoc -- thanks!
>>>>>>
>>>>>> It might help to have a little introductory text in some of the key
>>>>>> classes
>>>>>> giving some context, something along the lines of the DTFJ example on
>>>>>> your
>>>>>> web site that opens a core dump and iterates through the threads.
>>>>>>
>>>>>> I wonder if ImageThread should return interface RegisterSet, of which
>>>>>> there
>>>>>> would be various implementations for various CPU types, each
>>>>>>
>>>>>>
>>>>> containing a
>>
>>
>>> map from a Register enum to a RegisterValue.
>>>>>>
>>>>>> I hadn't realized until I started looking through this javadoc how
>>>>>>
>>>>>>
>>>>> much
>>
>>
>>> easier the use of generics makes it to understand an API.  For
>>>>>>
>>>>>>
>>>>> example,
>>
>>
>>> under JavaClassLoader I see methods getCachedClasses() and
>>>>>> getDefinedClasses(), but I can't tell from their signatures whether
>>>>>>
>>>>>>
>>>>> they
>>
>>
>>> return the same type or not.  That info is in the method
>>>>>>
>>>>>>
>>>>> descriptions,
>>
>>
>>> but
>>>>>> it's a lot more work to flip back and forth between the Summary and
>>>>>>
>>>>>>
>>>>> the
>>
>>
>>> Detail.
>>>>>>
>>>>>> Nicholas
>>>>>>
>>>>>>
>>>>>>
>>>>>> Steve Poole wrote:
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <
>>>>>>> Nicholas.Sterling@sun.com
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>> wrote:
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>> Great!  I've passed this on to the HotSpot folks for comment.
>>>>>>>>
>>>>>>>> I think I remember us talking about there being some provision for
>>>>>>>> accessing the vendor-specific VM constructs that implement the
>>>>>>>>
>>>>>>>>
>>>>>>> heap,
>>
>>
>>> etc.,
>>>>>>>> in addition to the Java objects in it.  Will that be done by, for
>>>>>>>> example,
>>>>>>>> casting a JavaVM to a HotSpotVM and using the latter's extra
>>>>>>>>
>>>>>>>>
>>>>>>> methods?
>>
>>
>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>> That's the most obvious solution I think.
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>> 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?
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>> 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
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>
>>>>
>>
>>
>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.


Daniel Julin wrote:
> Some thoughts about these iterators, also based on earlier experiences with
> the DumpAnalyzer tool:
>
>
> (1) The set of entries returned by some of these iterators can be quite
> large. Especially for JavaHeap.getObjects(), and also, to a lesser degree,
> JavaClassLoader.getDefinedClasses(), ImageModule.getSymbols(), etc. If we
> go to a model that allows random access, can we do it in a way that avoids
> forcing a pre-loading of every instance of every entry in the set, onto the
> heap of the JVM in which we are running the analyzer tool.
>
>
>   
Yes, and we should be very careful about assuming that a particular list 
will be small in all future VMs.

Rather than returning an Iterator for the objects on the heap, why not 
make JavaHeap extend Iterable?  That way we could write

    for ( JavaObject object : heap ) { ... }

without having to call getObjects().  If we are using generics, I 
believe this would work for both objects and sections, because we would 
extend both Iterable<JavaObject> and Iterable<ImageSection>,  i.e.

    for ( JavaObject   object  : heap ) { ... }
    for ( ImageSection section : heap ) { ... }

> (2) The API does not actually define any specific order in which the
> entries are returned by the various iterators, and I wish it would. For
> example:
>
> * When walking through all the objects on a heap, some heap analysis
> functions (and some file formats like PHD) require that the objects be
> returned in the order corresponding to the increasing addresses where they
> are located on that heap.  It turns out that, in all the implementations
> that I've seen so far, JavaHeap.getObjects() does provide that order, but
> nowhere does it say that I can count on it in every future implementation.
>   
Of course, for some future collector it might be difficult to produce 
the objects in that order.  What if there were a way of setting the 
order you want, and if the provider can't do it, then it could throw an 
exception saying that that's unimplemented.
> * When writing unit tests for analysis tools, it is very convenient to be
> able to count on a stable order returned by every iterator. Many tests can
> be written by printing all the output from some function, and simply
> comparing that output from one run of the tool to the next to detect
> regressions. This stable order was actually not provided by many iterators
> in current DTFJ implementations, and has caused considerable headache in
> the early days of the implementation of the DumpAnalyzer tool. We ended-up
> adding our own sort routines on top of many DTFJ iterators... which of
> course conflicts with point (1) above, to avoid pre-loading every entry.
>
>
> (3) At various times in the past, we had some discussions about potentially
> using a cursor-style API rather than an iterator, for large sets like the
> one from JavaHeap.getObjects(), to avoid excessive object allocation in the
> analyzer tool JVM.  How do you feel about that?
>
>   
Between fast allocation techniques, fast GC for short-lived objects, and 
the use of escape analysis to enable stack allocation, I'm not sure 
there's a big win in a cursor-style API.  Is the main disadvantage of a 
cursor-style API that you have to copy objects if you want to remember 
them, as opposed to just hanging on to references as they fly by?

Nicholas



>
> -- Daniel --
>
>
>
> Steve Poole <sp...@googlemail.com> wrote on 2009-04-06 05:19:07 PM:
>   
>> On Mon, Apr 6, 2009 at 9:45 PM, Nicholas Sterling
>>     
> <Nicholas.Sterling@sun.com
>   
>>> wrote:
>>>       
>>> Carmine Cristallo wrote:
>>>
>>>       
>>>> Hi all!A number of potential work items are starting to emerge from
>>>>         
> this
>   
>>>> thread. I'll try to enumerate them:
>>>>
>>>> 1. refactor the API to use generics. Basically, every method that now
>>>> returns an Iterator should have its signature modified. And while
>>>>         
> we're at
>   
>>>> it... is Iterator<...> the right "thing" to return? Wouldn't a
>>>>         
> collection
>   
>>>> (List<...>?) suit better?
>>>>
>>>>
>>>>         
>>> Ah, good point, although there might be some cases where the number of
>>> values would be huge (like objects on the heap), and for those you
>>>       
> probably
>   
>>> do just want to provide an Iterator.
>>>
>>>       
>> The main problem with iterators is providing any sort of random access.
>>     
> You
>   
>> end up with repeated walks through the iterator.   Having lists seemed
>>     
> like
>   
>> a good alternative.  I took a copy of DTFJ last year and replaced the
>> iterators with lists -  then I  easily added a jxpath  (
>> http://commons.apache.org/jxpath/)  layer on top.  It was pretty cool -
>>     
> if
>   
>> we agree on providing a random access mechanism of any sort it should be
>> fairly simple to redo the jxpath experiment.
>>
>>     
>>> That reminds me -- Steve, weren't you talking about an event-driven
>>> (SAX-like) parser at one point, in which one specifies the classes of
>>> interest in the target heap and the code to be executed for each? I
>>>       
> suppose
>   
>>> that could, and probably should be, build on *top* of an Iterator.
>>>
>>>       
>> Yes - I was wondering out loud if the "DOM" approach we have with the API
>>     
> is
>   
>> sufficent.   Its obvious when you start implementing the underlying
>>     
> support
>   
>> for this sort of API just how important it is to be lazy. A "SAX" like
>> approach could possibly provide  oppotunities to be even lazier!.
>>
>>     
>>> Nicholas
>>>
>>>
>>>  2. give a better implementation - as the one suggested by Nicholas -
>>>       
> to
>   
>>>> ImageThread#getRegister(). How about renaming it to "getRegisterMap
>>>>         
> ()",
>   
>>>> returning a RegisterMap interface?
>>>> 3. refactor the TCK to decouple the setup classes from the test
>>>>         
> classes,
>   
>>>> as
>>>> suggested by Stuart.
>>>>
>>>> Steve... should we start to open Jira work items for the above
>>>>         
> activities?
>   
>>>>     Carmine
>>>>
>>>> On Mon, Apr 6, 2009 at 8:24 PM, Nicholas Sterling <
>>>> Nicholas.Sterling@sun.com
>>>>
>>>>
>>>>         
>>>>> wrote:
>>>>>
>>>>>
>>>>>           
>>>>
>>>>         
>>>>> It's very nice being able to look at this javadoc -- thanks!
>>>>>
>>>>> It might help to have a little introductory text in some of the key
>>>>> classes
>>>>> giving some context, something along the lines of the DTFJ example on
>>>>> your
>>>>> web site that opens a core dump and iterates through the threads.
>>>>>
>>>>> I wonder if ImageThread should return interface RegisterSet, of which
>>>>> there
>>>>> would be various implementations for various CPU types, each
>>>>>           
> containing a
>   
>>>>> map from a Register enum to a RegisterValue.
>>>>>
>>>>> I hadn't realized until I started looking through this javadoc how
>>>>>           
> much
>   
>>>>> easier the use of generics makes it to understand an API.  For
>>>>>           
> example,
>   
>>>>> under JavaClassLoader I see methods getCachedClasses() and
>>>>> getDefinedClasses(), but I can't tell from their signatures whether
>>>>>           
> they
>   
>>>>> return the same type or not.  That info is in the method
>>>>>           
> descriptions,
>   
>>>>> but
>>>>> it's a lot more work to flip back and forth between the Summary and
>>>>>           
> the
>   
>>>>> Detail.
>>>>>
>>>>> Nicholas
>>>>>
>>>>>
>>>>>
>>>>> Steve Poole wrote:
>>>>>
>>>>>
>>>>>
>>>>>           
>>>>>> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <
>>>>>> Nicholas.Sterling@sun.com
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>             
>>>>>>> wrote:
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>               
>>>>>>
>>>>>>             
>>>>>>> Great!  I've passed this on to the HotSpot folks for comment.
>>>>>>>
>>>>>>> I think I remember us talking about there being some provision for
>>>>>>> accessing the vendor-specific VM constructs that implement the
>>>>>>>               
> heap,
>   
>>>>>>> etc.,
>>>>>>> in addition to the Java objects in it.  Will that be done by, for
>>>>>>> example,
>>>>>>> casting a JavaVM to a HotSpotVM and using the latter's extra
>>>>>>>               
> methods?
>   
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>               
>>>>>> That's the most obvious solution I think.
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>             
>>>>>>> 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?
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>             
>>>>>>> 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
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>                 
>>>>         
>
>

Re: Kato API javadoc

Posted by Daniel Julin <dp...@us.ibm.com>.

Some thoughts about these iterators, also based on earlier experiences with
the DumpAnalyzer tool:


(1) The set of entries returned by some of these iterators can be quite
large. Especially for JavaHeap.getObjects(), and also, to a lesser degree,
JavaClassLoader.getDefinedClasses(), ImageModule.getSymbols(), etc. If we
go to a model that allows random access, can we do it in a way that avoids
forcing a pre-loading of every instance of every entry in the set, onto the
heap of the JVM in which we are running the analyzer tool.



(2) The API does not actually define any specific order in which the
entries are returned by the various iterators, and I wish it would. For
example:

* When walking through all the objects on a heap, some heap analysis
functions (and some file formats like PHD) require that the objects be
returned in the order corresponding to the increasing addresses where they
are located on that heap.  It turns out that, in all the implementations
that I've seen so far, JavaHeap.getObjects() does provide that order, but
nowhere does it say that I can count on it in every future implementation.

* When writing unit tests for analysis tools, it is very convenient to be
able to count on a stable order returned by every iterator. Many tests can
be written by printing all the output from some function, and simply
comparing that output from one run of the tool to the next to detect
regressions. This stable order was actually not provided by many iterators
in current DTFJ implementations, and has caused considerable headache in
the early days of the implementation of the DumpAnalyzer tool. We ended-up
adding our own sort routines on top of many DTFJ iterators... which of
course conflicts with point (1) above, to avoid pre-loading every entry.



(3) At various times in the past, we had some discussions about potentially
using a cursor-style API rather than an iterator, for large sets like the
one from JavaHeap.getObjects(), to avoid excessive object allocation in the
analyzer tool JVM.  How do you feel about that?



-- Daniel --



Steve Poole <sp...@googlemail.com> wrote on 2009-04-06 05:19:07 PM:
>
> On Mon, Apr 6, 2009 at 9:45 PM, Nicholas Sterling
<Nicholas.Sterling@sun.com
> > wrote:
>
> >
> >
> > Carmine Cristallo wrote:
> >
> >> Hi all!A number of potential work items are starting to emerge from
this
> >> thread. I'll try to enumerate them:
> >>
> >> 1. refactor the API to use generics. Basically, every method that now
> >> returns an Iterator should have its signature modified. And while
we're at
> >> it... is Iterator<...> the right "thing" to return? Wouldn't a
collection
> >> (List<...>?) suit better?
> >>
> >>
> > Ah, good point, although there might be some cases where the number of
> > values would be huge (like objects on the heap), and for those you
probably
> > do just want to provide an Iterator.
> >
>
> The main problem with iterators is providing any sort of random access.
You
> end up with repeated walks through the iterator.   Having lists seemed
like
> a good alternative.  I took a copy of DTFJ last year and replaced the
> iterators with lists -  then I  easily added a jxpath  (
> http://commons.apache.org/jxpath/)  layer on top.  It was pretty cool -
if
> we agree on providing a random access mechanism of any sort it should be
> fairly simple to redo the jxpath experiment.
>
> >
> > That reminds me -- Steve, weren't you talking about an event-driven
> > (SAX-like) parser at one point, in which one specifies the classes of
> > interest in the target heap and the code to be executed for each? I
suppose
> > that could, and probably should be, build on *top* of an Iterator.
> >
>
> Yes - I was wondering out loud if the "DOM" approach we have with the API
is
> sufficent.   Its obvious when you start implementing the underlying
support
> for this sort of API just how important it is to be lazy. A "SAX" like
> approach could possibly provide  oppotunities to be even lazier!.
>
> >
> > Nicholas
> >
> >
> >  2. give a better implementation - as the one suggested by Nicholas -
to
> >> ImageThread#getRegister(). How about renaming it to "getRegisterMap
()",
> >> returning a RegisterMap interface?
> >> 3. refactor the TCK to decouple the setup classes from the test
classes,
> >> as
> >> suggested by Stuart.
> >>
> >> Steve... should we start to open Jira work items for the above
activities?
> >>
> >>
> >>     Carmine
> >>
> >> On Mon, Apr 6, 2009 at 8:24 PM, Nicholas Sterling <
> >> Nicholas.Sterling@sun.com
> >>
> >>
> >>> wrote:
> >>>
> >>>
> >>
> >>
> >>
> >>> It's very nice being able to look at this javadoc -- thanks!
> >>>
> >>> It might help to have a little introductory text in some of the key
> >>> classes
> >>> giving some context, something along the lines of the DTFJ example on
> >>> your
> >>> web site that opens a core dump and iterates through the threads.
> >>>
> >>> I wonder if ImageThread should return interface RegisterSet, of which
> >>> there
> >>> would be various implementations for various CPU types, each
containing a
> >>> map from a Register enum to a RegisterValue.
> >>>
> >>> I hadn't realized until I started looking through this javadoc how
much
> >>> easier the use of generics makes it to understand an API.  For
example,
> >>> under JavaClassLoader I see methods getCachedClasses() and
> >>> getDefinedClasses(), but I can't tell from their signatures whether
they
> >>> return the same type or not.  That info is in the method
descriptions,
> >>> but
> >>> it's a lot more work to flip back and forth between the Summary and
the
> >>> Detail.
> >>>
> >>> Nicholas
> >>>
> >>>
> >>>
> >>> Steve Poole wrote:
> >>>
> >>>
> >>>
> >>>> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <
> >>>> Nicholas.Sterling@sun.com
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>> wrote:
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>
> >>>>
> >>>>
> >>>>> Great!  I've passed this on to the HotSpot folks for comment.
> >>>>>
> >>>>> I think I remember us talking about there being some provision for
> >>>>> accessing the vendor-specific VM constructs that implement the
heap,
> >>>>> etc.,
> >>>>> in addition to the Java objects in it.  Will that be done by, for
> >>>>> example,
> >>>>> casting a JavaVM to a HotSpotVM and using the latter's extra
methods?
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>> That's the most obvious solution I think.
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>> 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?
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>> 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
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>
> >>>>
> >>>
> >>
> >>
> >

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

On Mon, Apr 6, 2009 at 9:45 PM, Nicholas Sterling <Nicholas.Sterling@sun.com
> wrote:

>
>
> Carmine Cristallo wrote:
>
>> Hi all!A number of potential work items are starting to emerge from this
>> thread. I'll try to enumerate them:
>>
>> 1. refactor the API to use generics. Basically, every method that now
>> returns an Iterator should have its signature modified. And while we're at
>> it... is Iterator<...> the right "thing" to return? Wouldn't a collection
>> (List<...>?) suit better?
>>
>>
> Ah, good point, although there might be some cases where the number of
> values would be huge (like objects on the heap), and for those you probably
> do just want to provide an Iterator.
>

The main problem with iterators is providing any sort of random access.  You
end up with repeated walks through the iterator.   Having lists seemed like
a good alternative.  I took a copy of DTFJ last year and replaced the
iterators with lists -  then I  easily added a jxpath  (
http://commons.apache.org/jxpath/)  layer on top.  It was pretty cool - if
we agree on providing a random access mechanism of any sort it should be
fairly simple to redo the jxpath experiment.

>
> That reminds me -- Steve, weren't you talking about an event-driven
> (SAX-like) parser at one point, in which one specifies the classes of
> interest in the target heap and the code to be executed for each?  I suppose
> that could, and probably should be, build on *top* of an Iterator.
>

Yes - I was wondering out loud if the "DOM" approach we have with the API is
sufficent.   Its obvious when you start implementing the underlying support
for this sort of API just how important it is to be lazy. A "SAX" like
approach could possibly provide  oppotunities to be even lazier!.

>
> Nicholas
>
>
>  2. give a better implementation - as the one suggested by Nicholas - to
>> ImageThread#getRegister(). How about renaming it to "getRegisterMap()",
>> returning a RegisterMap interface?
>> 3. refactor the TCK to decouple the setup classes from the test classes,
>> as
>> suggested by Stuart.
>>
>> Steve... should we start to open Jira work items for the above activities?
>>
>>
>>     Carmine
>>
>> On Mon, Apr 6, 2009 at 8:24 PM, Nicholas Sterling <
>> Nicholas.Sterling@sun.com
>>
>>
>>> wrote:
>>>
>>>
>>
>>
>>
>>> It's very nice being able to look at this javadoc -- thanks!
>>>
>>> It might help to have a little introductory text in some of the key
>>> classes
>>> giving some context, something along the lines of the DTFJ example on
>>> your
>>> web site that opens a core dump and iterates through the threads.
>>>
>>> I wonder if ImageThread should return interface RegisterSet, of which
>>> there
>>> would be various implementations for various CPU types, each containing a
>>> map from a Register enum to a RegisterValue.
>>>
>>> I hadn't realized until I started looking through this javadoc how much
>>> easier the use of generics makes it to understand an API.  For example,
>>> under JavaClassLoader I see methods getCachedClasses() and
>>> getDefinedClasses(), but I can't tell from their signatures whether they
>>> return the same type or not.  That info is in the method descriptions,
>>> but
>>> it's a lot more work to flip back and forth between the Summary and the
>>> Detail.
>>>
>>> Nicholas
>>>
>>>
>>>
>>> Steve Poole wrote:
>>>
>>>
>>>
>>>> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <
>>>> Nicholas.Sterling@sun.com
>>>>
>>>>
>>>>
>>>>
>>>>> wrote:
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>>
>>>>> Great!  I've passed this on to the HotSpot folks for comment.
>>>>>
>>>>> I think I remember us talking about there being some provision for
>>>>> accessing the vendor-specific VM constructs that implement the heap,
>>>>> etc.,
>>>>> in addition to the Java objects in it.  Will that be done by, for
>>>>> example,
>>>>> casting a JavaVM to a HotSpotVM and using the latter's extra methods?
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>> That's the most obvious solution I think.
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>> 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?
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>> 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
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>>
>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.


Carmine Cristallo wrote:
> Hi all!A number of potential work items are starting to emerge from this
> thread. I'll try to enumerate them:
>
> 1. refactor the API to use generics. Basically, every method that now
> returns an Iterator should have its signature modified. And while we're at
> it... is Iterator<...> the right "thing" to return? Wouldn't a collection
> (List<...>?) suit better?
>   
Ah, good point, although there might be some cases where the number of 
values would be huge (like objects on the heap), and for those you 
probably do just want to provide an Iterator.

That reminds me -- Steve, weren't you talking about an event-driven 
(SAX-like) parser at one point, in which one specifies the classes of 
interest in the target heap and the code to be executed for each?  I 
suppose that could, and probably should be, build on *top* of an Iterator.

Nicholas

> 2. give a better implementation - as the one suggested by Nicholas - to
> ImageThread#getRegister(). How about renaming it to "getRegisterMap()",
> returning a RegisterMap interface?
> 3. refactor the TCK to decouple the setup classes from the test classes, as
> suggested by Stuart.
>
> Steve... should we start to open Jira work items for the above activities?
>
>
>      Carmine
>
> On Mon, Apr 6, 2009 at 8:24 PM, Nicholas Sterling <Nicholas.Sterling@sun.com
>   
>> wrote:
>>     
>
>   
>> It's very nice being able to look at this javadoc -- thanks!
>>
>> It might help to have a little introductory text in some of the key classes
>> giving some context, something along the lines of the DTFJ example on your
>> web site that opens a core dump and iterates through the threads.
>>
>> I wonder if ImageThread should return interface RegisterSet, of which there
>> would be various implementations for various CPU types, each containing a
>> map from a Register enum to a RegisterValue.
>>
>> I hadn't realized until I started looking through this javadoc how much
>> easier the use of generics makes it to understand an API.  For example,
>> under JavaClassLoader I see methods getCachedClasses() and
>> getDefinedClasses(), but I can't tell from their signatures whether they
>> return the same type or not.  That info is in the method descriptions, but
>> it's a lot more work to flip back and forth between the Summary and the
>> Detail.
>>
>> Nicholas
>>
>>
>>
>> Steve Poole wrote:
>>
>>     
>>> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <
>>> Nicholas.Sterling@sun.com
>>>
>>>
>>>       
>>>> wrote:
>>>>
>>>>
>>>>         
>>>
>>>       
>>>> Great!  I've passed this on to the HotSpot folks for comment.
>>>>
>>>> I think I remember us talking about there being some provision for
>>>> accessing the vendor-specific VM constructs that implement the heap,
>>>> etc.,
>>>> in addition to the Java objects in it.  Will that be done by, for
>>>> example,
>>>> casting a JavaVM to a HotSpotVM and using the latter's extra methods?
>>>>
>>>>
>>>>
>>>>         
>>> That's the most obvious solution I think.
>>>
>>>
>>>
>>>       
>>>> 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?
>>>
>>>
>>>
>>>       
>>>> 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
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>           
>>>       
>
>

Re: Kato API javadoc

Posted by Carmine Cristallo <ca...@gmail.com>.

Hi all!A number of potential work items are starting to emerge from this
thread. I'll try to enumerate them:

1. refactor the API to use generics. Basically, every method that now
returns an Iterator should have its signature modified. And while we're at
it... is Iterator<...> the right "thing" to return? Wouldn't a collection
(List<...>?) suit better?
2. give a better implementation - as the one suggested by Nicholas - to
ImageThread#getRegister(). How about renaming it to "getRegisterMap()",
returning a RegisterMap interface?
3. refactor the TCK to decouple the setup classes from the test classes, as
suggested by Stuart.

Steve... should we start to open Jira work items for the above activities?


     Carmine

On Mon, Apr 6, 2009 at 8:24 PM, Nicholas Sterling <Nicholas.Sterling@sun.com
> wrote:

> It's very nice being able to look at this javadoc -- thanks!
>
> It might help to have a little introductory text in some of the key classes
> giving some context, something along the lines of the DTFJ example on your
> web site that opens a core dump and iterates through the threads.
>
> I wonder if ImageThread should return interface RegisterSet, of which there
> would be various implementations for various CPU types, each containing a
> map from a Register enum to a RegisterValue.
>
> I hadn't realized until I started looking through this javadoc how much
> easier the use of generics makes it to understand an API.  For example,
> under JavaClassLoader I see methods getCachedClasses() and
> getDefinedClasses(), but I can't tell from their signatures whether they
> return the same type or not.  That info is in the method descriptions, but
> it's a lot more work to flip back and forth between the Summary and the
> Detail.
>
> Nicholas
>
>
>
> Steve Poole wrote:
>
>> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <
>> Nicholas.Sterling@sun.com
>>
>>
>>> wrote:
>>>
>>>
>>
>>
>>
>>> Great!  I've passed this on to the HotSpot folks for comment.
>>>
>>> I think I remember us talking about there being some provision for
>>> accessing the vendor-specific VM constructs that implement the heap,
>>> etc.,
>>> in addition to the Java objects in it.  Will that be done by, for
>>> example,
>>> casting a JavaVM to a HotSpotVM and using the latter's extra methods?
>>>
>>>
>>>
>>
>> That's the most obvious solution I think.
>>
>>
>>
>>> 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?
>>
>>
>>
>>> 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
>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>>
>>
>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.

It's very nice being able to look at this javadoc -- thanks!

It might help to have a little introductory text in some of the key 
classes giving some context, something along the lines of the DTFJ 
example on your web site that opens a core dump and iterates through the 
threads.

I wonder if ImageThread should return interface RegisterSet, of which 
there would be various implementations for various CPU types, each 
containing a map from a Register enum to a RegisterValue.

I hadn't realized until I started looking through this javadoc how much 
easier the use of generics makes it to understand an API.  For example, 
under JavaClassLoader I see methods getCachedClasses() and 
getDefinedClasses(), but I can't tell from their signatures whether they 
return the same type or not.  That info is in the method descriptions, 
but it's a lot more work to flip back and forth between the Summary and 
the Detail.

Nicholas


Steve Poole wrote:
> On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <Nicholas.Sterling@sun.com
>   
>> wrote:
>>     
>
>   
>> Great!  I've passed this on to the HotSpot folks for comment.
>>
>> I think I remember us talking about there being some provision for
>> accessing the vendor-specific VM constructs that implement the heap, etc.,
>> in addition to the Java objects in it.  Will that be done by, for example,
>> casting a JavaVM to a HotSpotVM and using the latter's extra methods?
>>
>>     
>
> That's the most obvious solution I think.
>
>   
>> 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?
>
>   
>> 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
>>>
>>>
>>>
>>>       
>
>

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

On Mon, Apr 6, 2009 at 6:51 AM, Nicholas Sterling <Nicholas.Sterling@sun.com
> wrote:

>
> Great!  I've passed this on to the HotSpot folks for comment.
>
> I think I remember us talking about there being some provision for
> accessing the vendor-specific VM constructs that implement the heap, etc.,
> in addition to the Java objects in it.  Will that be done by, for example,
> casting a JavaVM to a HotSpotVM and using the latter's extra methods?
>

That's the most obvious solution I think.

>
> 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?

>
>
> 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
>>
>>
>>
>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.

Great!  I've passed this on to the HotSpot folks for comment.

I think I remember us talking about there being some provision for 
accessing the vendor-specific VM constructs that implement the heap, 
etc., in addition to the Java objects in it.  Will that be done by, for 
example, casting a JavaVM to a HotSpotVM and using the latter's extra 
methods?

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?

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
>
>

Re: Kato API javadoc

Posted by Christian Glatschke <ch...@glatschke.com>.

Hi Steve,

I would really appreciate to have a conf call to walk through the doc.


Cheers,

Christian Glatschke

Steve Poole schrieb:
> 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
>
>

Re: Conference Call

Posted by Sonal Goyal <so...@gmail.com>.

Hi,
A con call would be great. I am fine with all days in the coming week except
Wednesday. My preferred time slot:

08:30 - 12:30 IST (03:00 UTC - 07:00 UTC)
and
18:00 - 23:00 IST (12:30 UTC - 17:30 UTC)

Thanks and Regards,
Sonal


On Thu, Apr 16, 2009 at 2:34 PM, Bobrovsky, Konstantin S <
konstantin.s.bobrovsky@intel.com> wrote:

> Hi all,
>
> I'm OK with the following timeslots [California (or Pacific Standard)
> time]:
>
> ...-9am PST (...-11pm my time)
> 6pm-... PST (8am-... my time)
>
> All days next week except Thursday (if early morning PST slot is used) will
> suit me.
>
> Thanks,
> Konst
>
> Intel Novosibirsk
> Closed Joint Stock Company Intel A/O
> Registered legal address: Krylatsky Hills Business Park,
> 17 Krylatskaya Str., Bldg 4, Moscow 121614,
> Russian Federation
>
>
> -----Original Message-----
> From: Nicholas.Sterling@Sun.COM [mailto:Nicholas.Sterling@Sun.COM]
> Sent: Thursday, April 16, 2009 1:43 PM
> To: kato-spec@incubator.apache.org
> Subject: Re: Conference Call
>
> Sounds great!
>
> Presumably you are talking about early morning in California.  In that
> case Tue, Thu, or Fri would be best, although I'll try to make it
> whatever day is chosen.
>
> Nicholas
>
>
> Stuart Monteith wrote:
> > Hello,
> >    I would like to set up a conference call for next week. Using the
> > following: https://www.webdialogs.com/ it is possible to record
> > the call and the screen of the person hosting the meeting. Anyone
> > should be able to dial in, and if they wish, join the meeting to view,
> > for example, a web browser with the JavaDoc. The recordings are in
> > flash, but I'm sure we should be able to extract the audio and also
> > transcribe it for posterity.
> >
> > If everyone is ok with this arrangement, I'd like to try and arrange
> > it for sometime next week. I've not arranged an international
> > conference call before, but can I suggest we use UTC to state the
> > times? For instance, UK working time is currently 08:00 to 16:30 UTC.
> >
> > I estimate the time range from -7 UTC (California) through -1 UTC (UK)
> > into +3 UTC (Moscow) and +5:30 (India). This is 12 1/2 hours. Please
> > let me know if my estimate is incorrect.
> >
> > As I understand it the call would be to walk through the API and
> > clarify any issues people may have it (that's my interpretation).
> >
> > Please let me know what you think about dates and times.
> >
> > Thanks,
> >    Stuart
> >
> > Steve Poole wrote:
> >> Ant, We'll try our best  to make this as open as possible - we should be
> >> able to record the call at the very least.
> >>
> >> On Mon, Apr 6, 2009 at 9:19 AM, ant elder <an...@gmail.com> wrote:
> >>
> >>
> >>> On Mon, Apr 6, 2009 at 8:49 AM, Steve Poole <sp...@googlemail.com>
> >>> wrote:
> >>>
> >>>> On Mon, Apr 6, 2009 at 8:30 AM, Nicholas Sterling <
> >>>>
> >>> Nicholas.Sterling@sun.com
> >>>
> >>>>> wrote:
> >>>>>         Steve, if we do end up having a concall, which I think
> >>>>> would probably
> >>>>>
> >>> help,
> >>>
> >>>>> would you mind if I invited Alan Bateman of the HotSpot team to
> >>>>> attend?
> >>>>>
> >>>> Sure that would be fine.
> >>>>
> >>>>
> >>> I'm sure you all know that the dev list is the preferred place for
> >>> communication in Apache projects so phone calls can be frowned upon.
> >>> They're not unheard of though, other projects do use them on occasion,
> >>> and in this particular circumstance to help explain the Kato seed code
> >>> i think its ok. I'd hope that access would be open to anyone and via a
> >>> publicized toll free number. Would also be great to make a recording
> >>> of the call and put that up on the Kato website (i know thats not
> >>> always possible to arrange).
> >>>
> >>>   ...ant
> >>>
> >>>
> >>
> >>
>

RE: Conference Call

Posted by "Bobrovsky, Konstantin S" <ko...@intel.com>.

Hi all,

I'm OK with the following timeslots [California (or Pacific Standard) time]:

...-9am PST (...-11pm my time)
6pm-... PST (8am-... my time)

All days next week except Thursday (if early morning PST slot is used) will suit me.

Thanks,
Konst

Intel Novosibirsk
Closed Joint Stock Company Intel A/O
Registered legal address: Krylatsky Hills Business Park, 
17 Krylatskaya Str., Bldg 4, Moscow 121614, 
Russian Federation
 

-----Original Message-----
From: Nicholas.Sterling@Sun.COM [mailto:Nicholas.Sterling@Sun.COM] 
Sent: Thursday, April 16, 2009 1:43 PM
To: kato-spec@incubator.apache.org
Subject: Re: Conference Call

Sounds great!

Presumably you are talking about early morning in California.  In that 
case Tue, Thu, or Fri would be best, although I'll try to make it 
whatever day is chosen.

Nicholas


Stuart Monteith wrote:
> Hello,
>    I would like to set up a conference call for next week. Using the 
> following: https://www.webdialogs.com/ it is possible to record
> the call and the screen of the person hosting the meeting. Anyone 
> should be able to dial in, and if they wish, join the meeting to view, 
> for example, a web browser with the JavaDoc. The recordings are in 
> flash, but I'm sure we should be able to extract the audio and also 
> transcribe it for posterity.
>
> If everyone is ok with this arrangement, I'd like to try and arrange 
> it for sometime next week. I've not arranged an international 
> conference call before, but can I suggest we use UTC to state the 
> times? For instance, UK working time is currently 08:00 to 16:30 UTC.
>
> I estimate the time range from -7 UTC (California) through -1 UTC (UK) 
> into +3 UTC (Moscow) and +5:30 (India). This is 12 1/2 hours. Please 
> let me know if my estimate is incorrect.
>
> As I understand it the call would be to walk through the API and 
> clarify any issues people may have it (that's my interpretation).
>
> Please let me know what you think about dates and times.
>
> Thanks,
>    Stuart
>
> Steve Poole wrote:
>> Ant, We'll try our best  to make this as open as possible - we should be
>> able to record the call at the very least.
>>
>> On Mon, Apr 6, 2009 at 9:19 AM, ant elder <an...@gmail.com> wrote:
>>
>>  
>>> On Mon, Apr 6, 2009 at 8:49 AM, Steve Poole <sp...@googlemail.com>
>>> wrote:
>>>    
>>>> On Mon, Apr 6, 2009 at 8:30 AM, Nicholas Sterling <
>>>>       
>>> Nicholas.Sterling@sun.com
>>>    
>>>>> wrote:
>>>>>         Steve, if we do end up having a concall, which I think 
>>>>> would probably
>>>>>         
>>> help,
>>>    
>>>>> would you mind if I invited Alan Bateman of the HotSpot team to 
>>>>> attend?
>>>>>         
>>>> Sure that would be fine.
>>>>
>>>>       
>>> I'm sure you all know that the dev list is the preferred place for
>>> communication in Apache projects so phone calls can be frowned upon.
>>> They're not unheard of though, other projects do use them on occasion,
>>> and in this particular circumstance to help explain the Kato seed code
>>> i think its ok. I'd hope that access would be open to anyone and via a
>>> publicized toll free number. Would also be great to make a recording
>>> of the call and put that up on the Kato website (i know thats not
>>> always possible to arrange).
>>>
>>>   ...ant
>>>
>>>     
>>
>>

Re: Conference Call

Posted by Nicholas Sterling <Ni...@Sun.COM>.

Sounds great!

Presumably you are talking about early morning in California.  In that 
case Tue, Thu, or Fri would be best, although I'll try to make it 
whatever day is chosen.

Nicholas


Stuart Monteith wrote:
> Hello,
>    I would like to set up a conference call for next week. Using the 
> following: https://www.webdialogs.com/ it is possible to record
> the call and the screen of the person hosting the meeting. Anyone 
> should be able to dial in, and if they wish, join the meeting to view, 
> for example, a web browser with the JavaDoc. The recordings are in 
> flash, but I'm sure we should be able to extract the audio and also 
> transcribe it for posterity.
>
> If everyone is ok with this arrangement, I'd like to try and arrange 
> it for sometime next week. I've not arranged an international 
> conference call before, but can I suggest we use UTC to state the 
> times? For instance, UK working time is currently 08:00 to 16:30 UTC.
>
> I estimate the time range from -7 UTC (California) through -1 UTC (UK) 
> into +3 UTC (Moscow) and +5:30 (India). This is 12 1/2 hours. Please 
> let me know if my estimate is incorrect.
>
> As I understand it the call would be to walk through the API and 
> clarify any issues people may have it (that's my interpretation).
>
> Please let me know what you think about dates and times.
>
> Thanks,
>    Stuart
>
> Steve Poole wrote:
>> Ant, We'll try our best  to make this as open as possible - we should be
>> able to record the call at the very least.
>>
>> On Mon, Apr 6, 2009 at 9:19 AM, ant elder <an...@gmail.com> wrote:
>>
>>  
>>> On Mon, Apr 6, 2009 at 8:49 AM, Steve Poole <sp...@googlemail.com>
>>> wrote:
>>>    
>>>> On Mon, Apr 6, 2009 at 8:30 AM, Nicholas Sterling <
>>>>       
>>> Nicholas.Sterling@sun.com
>>>    
>>>>> wrote:
>>>>>         Steve, if we do end up having a concall, which I think 
>>>>> would probably
>>>>>         
>>> help,
>>>    
>>>>> would you mind if I invited Alan Bateman of the HotSpot team to 
>>>>> attend?
>>>>>         
>>>> Sure that would be fine.
>>>>
>>>>       
>>> I'm sure you all know that the dev list is the preferred place for
>>> communication in Apache projects so phone calls can be frowned upon.
>>> They're not unheard of though, other projects do use them on occasion,
>>> and in this particular circumstance to help explain the Kato seed code
>>> i think its ok. I'd hope that access would be open to anyone and via a
>>> publicized toll free number. Would also be great to make a recording
>>> of the call and put that up on the Kato website (i know thats not
>>> always possible to arrange).
>>>
>>>   ...ant
>>>
>>>     
>>
>>

Conference Call

Posted by Stuart Monteith <st...@stoo.me.uk>.

Hello,
    I would like to set up a conference call for next week. Using the 
following: https://www.webdialogs.com/ it is possible to record
the call and the screen of the person hosting the meeting. Anyone should 
be able to dial in, and if they wish, join the meeting to view, for 
example, a web browser with the JavaDoc. The recordings are in flash, 
but I'm sure we should be able to extract the audio and also transcribe 
it for posterity.

If everyone is ok with this arrangement, I'd like to try and arrange it 
for sometime next week. I've not arranged an international conference 
call before, but can I suggest we use UTC to state the times? For 
instance, UK working time is currently 08:00 to 16:30 UTC.

I estimate the time range from -7 UTC (California) through -1 UTC (UK) 
into +3 UTC (Moscow) and +5:30 (India). This is 12 1/2 hours. Please let 
me know if my estimate is incorrect.

As I understand it the call would be to walk through the API and clarify 
any issues people may have it (that's my interpretation).

Please let me know what you think about dates and times.

Thanks,
    Stuart

Steve Poole wrote:
> Ant, We'll try our best  to make this as open as possible - we should be
> able to record the call at the very least.
>
> On Mon, Apr 6, 2009 at 9:19 AM, ant elder <an...@gmail.com> wrote:
>
>   
>> On Mon, Apr 6, 2009 at 8:49 AM, Steve Poole <sp...@googlemail.com>
>> wrote:
>>     
>>> On Mon, Apr 6, 2009 at 8:30 AM, Nicholas Sterling <
>>>       
>> Nicholas.Sterling@sun.com
>>     
>>>> wrote:
>>>>         
>>>> Steve, if we do end up having a concall, which I think would probably
>>>>         
>> help,
>>     
>>>> would you mind if I invited Alan Bateman of the HotSpot team to attend?
>>>>         
>>> Sure that would be fine.
>>>
>>>       
>> I'm sure you all know that the dev list is the preferred place for
>> communication in Apache projects so phone calls can be frowned upon.
>> They're not unheard of though, other projects do use them on occasion,
>> and in this particular circumstance to help explain the Kato seed code
>> i think its ok. I'd hope that access would be open to anyone and via a
>> publicized toll free number. Would also be great to make a recording
>> of the call and put that up on the Kato website (i know thats not
>> always possible to arrange).
>>
>>   ...ant
>>
>>     
>
>

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

Ant, We'll try our best  to make this as open as possible - we should be
able to record the call at the very least.

On Mon, Apr 6, 2009 at 9:19 AM, ant elder <an...@gmail.com> wrote:

> On Mon, Apr 6, 2009 at 8:49 AM, Steve Poole <sp...@googlemail.com>
> wrote:
> > On Mon, Apr 6, 2009 at 8:30 AM, Nicholas Sterling <
> Nicholas.Sterling@sun.com
> >> wrote:
> >
> >>
> >> Steve, if we do end up having a concall, which I think would probably
> help,
> >> would you mind if I invited Alan Bateman of the HotSpot team to attend?
> >
> >
> > Sure that would be fine.
> >
>
> I'm sure you all know that the dev list is the preferred place for
> communication in Apache projects so phone calls can be frowned upon.
> They're not unheard of though, other projects do use them on occasion,
> and in this particular circumstance to help explain the Kato seed code
> i think its ok. I'd hope that access would be open to anyone and via a
> publicized toll free number. Would also be great to make a recording
> of the call and put that up on the Kato website (i know thats not
> always possible to arrange).
>
>   ...ant
>

Re: Kato API javadoc

Posted by ant elder <an...@gmail.com>.

On Mon, Apr 6, 2009 at 8:49 AM, Steve Poole <sp...@googlemail.com> wrote:
> On Mon, Apr 6, 2009 at 8:30 AM, Nicholas Sterling <Nicholas.Sterling@sun.com
>> wrote:
>
>>
>> Steve, if we do end up having a concall, which I think would probably help,
>> would you mind if I invited Alan Bateman of the HotSpot team to attend?
>
>
> Sure that would be fine.
>

I'm sure you all know that the dev list is the preferred place for
communication in Apache projects so phone calls can be frowned upon.
They're not unheard of though, other projects do use them on occasion,
and in this particular circumstance to help explain the Kato seed code
i think its ok. I'd hope that access would be open to anyone and via a
publicized toll free number. Would also be great to make a recording
of the call and put that up on the Kato website (i know thats not
always possible to arrange).

   ...ant

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.

Thanks, Steve.

Nicholas


Steve Poole wrote:
> On Mon, Apr 6, 2009 at 8:30 AM, Nicholas Sterling <Nicholas.Sterling@sun.com
>   
>> wrote:
>>     
>
>   
>> Steve, if we do end up having a concall, which I think would probably help,
>> would you mind if I invited Alan Bateman of the HotSpot team to attend?
>>     
>
>
> Sure that would be fine.
>
>   
>> 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
>>>
>>>
>>>
>>>       
>
>

Re: Kato API javadoc

Posted by Steve Poole <sp...@googlemail.com>.

On Mon, Apr 6, 2009 at 8:30 AM, Nicholas Sterling <Nicholas.Sterling@sun.com
> wrote:

>
> Steve, if we do end up having a concall, which I think would probably help,
> would you mind if I invited Alan Bateman of the HotSpot team to attend?


Sure that would be fine.

>
>
> 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
>>
>>
>>
>

Re: Kato API javadoc

Posted by Nicholas Sterling <Ni...@Sun.COM>.

Steve, if we do end up having a concall, which I think would probably 
help, would you mind if I invited Alan Bateman of the HotSpot team to 
attend?

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
>
>