You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@samza.apache.org by "Martin Kleppmann (JIRA)" <ji...@apache.org> on 2014/06/26 19:05:25 UTC
[jira] [Commented] (SAMZA-295) Classify public APIs between
job-writers and framework-extenders
[ 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)