Rethink GCToolKit API flow: GCAnalyzer returns GCAnalysis

[brunoborges]

For discussion:

Bruno and I had a discussion about this API in general. It was very refreshing to have his un-initiated perspective here. One of the ideas he tossed into the ring was having an 'analyzer' API, to which my response was that is what GCToolkit is.

Later, I got to thinking about it and I see where he's coming from. I think, perhaps, we should rename the GCToolKit class to GCAnalyzer, and have the analyze method return a GCAnalysis which would be what JavaVirtualMachine is now. I think this would make it more clear to the user what to do and what to use.

Thoughts?

Originally posted by @dsgrieve in #70 (comment)

[brunoborges]

This is also related to #6.

// @kcpeppe @karianna

[karianna]

I agree that the name of JavaVirtualMachine could be improved to more accurately represent what it is (which is really the GC information for that JVM as pulled out of the log). I'm not 100% sure it's a full analysis though, more of a model?

[brunoborges]

@kcpeppe you mentioned the following:

It sounds good but we’re not offering a GC analysis.

And that is correct. Perhaps the method analyze(dataSource) shouldn't be called that. It should be called aggregate then?

[dsgrieve]

I'll be frank here and state my opinion that what we have now for an API is unsatisfactory. The API is designed to support the Censum way of modeling which makes it difficult for anyone else to use. The Aggregators/Aggregations, and the whole of gctoolkit-vertx, is a layer of abstraction that is unnecessary. I believe that the majority of users want to just get a stream of events from the parser:

GCLogFile logFile = new GCLogFile(path);
Stream<JVMEvent> jvmEventStream = GCLogParser.parse(logFile); 

[karianna]

Can we offer both? That is have an opinionated API that we know clients use today, as well as a raw 'data stream' API?

[dsgrieve]

@karianna There is value to the current API. In my opinion, the current API should be built on a more fundamental API.

completed with refactoring