[
https://issues.apache.org/jira/browse/SAMZA-295?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14044865#comment-14044865
]
Martin Kleppmann commented on SAMZA-295:
----------------------------------------
At first glance, I think this is a good idea. Samza's Javadocs are more
intimidating than necessary, because there are quite a lot of APIs. If we could
make the Javadocs show only the interfaces that job implementers need to know
about, they would be much more compact.
However, I'm not sure where we'd draw the line exactly. I'd say
BlockingEnvelopeMap is quite clearly on the internals side, and StreamTask is
obviously on the public side. But what about SerdeFactory? Quite reasonable to
think that job authors might write their own serdes. TaskLifecycleListener is a
bit more internal, but may still be useful to job authors (e.g. freeing
resources before container shutdown). etc.
One heuristic might be to classify everything as public that we refer to in the
documentation. And the documentation currently goes into quite a lot of details
that are fairly advanced (e.g. message choosers).
> Classify public APIs between job-writers and framework-extenders
> ----------------------------------------------------------------
>
> Key: SAMZA-295
> URL: https://issues.apache.org/jira/browse/SAMZA-295
> Project: Samza
> Issue Type: Improvement
> Reporter: Jakob Homan
> Fix For: 0.8.0
>
>
> Currently all the exposed Java APIs are mingled together, both those meant
> for developers writing simple Samza tasks (StreamTask, WindowableTask,
> SystemStreamPartition, etc.) and those APIs needed for extending Samza itself
> (CheckpointManager, TaskLifeCycleListener, BlockingEnvelopMap, etc.). The
> latter group is likely not of use to those needing the former and may clutter
> and confuse. It would be good to split these, either at the package level,
> or via annotations (similar to [Hadoop's audience
> annotations|https://issues.apache.org/jira/browse/HADOOP-5073]).
--
This message was sent by Atlassian JIRA
(v6.2#6252)
