[
https://issues.apache.org/jira/browse/HADOOP-6668?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12863967#action_12863967
]
Tom White commented on HADOOP-6668:
-----------------------------------
{quote}
Java public does not imply audience public. An interface is audience public
only if we expect applications to use it directly. This is probably the biggest
difference between the approach taken in this jira and HADOOP-6289.
I do not fully understand the distinction you are trying to make in " APIs that
are exposed to the user but not coded against directly (e.g. the metrics API,)"
{quote}
Users configure the metrics system, and to do so they need to have a way of
discovering which metrics contexts are available. By marking the metrics
classes like org.apache.hadoop.metrics.file.FileContext Private or
LimitedPrivate you make them no longer discoverable, since we do not publish
javadoc for private elements. (Also its class javadoc has useful information in
it.) The class is public in the sense that it is referenced in the metrics
configuration, even though the user does not code against it directly.
{quote}
I disagree with your metrics example: we should not expose APIs like metrics as
audience public. They should be limited private.
{quote}
Limited private for use by which components or subprojects? How would I write
my own metrics context?
{quote}
In the majority cases I agree, except that
some private interfaces need to be marked as stable: protocols like client
protocol should be marked as
limited-private and stable
{quote}
I agree with this. (Indeed I marked ClientProtocol in MAPREDUCE-1623 private
stable.)
{quote}
> * If an API is not annotated then it defaults to the usual Java visibility
> and Apache HADOOP stability (http://wiki.apache.org/hadoop/Roadmap) rules.
This is different than what was stated in HADOOP-5073. It should default to
audience-private unstable.
{quote}
I don't agree with this since it violates the principle of least surprise - if
an otherwise unannotated class is public, then a user would reasonably expect
it to be public. I think the onus is on developers writing code for Hadoop to
mark things as private. Longer term it may help to separate the client APIs
from the implementation (MAPREDUCE-1638).
> Apply audience and stability annotations to classes in common
> -------------------------------------------------------------
>
> Key: HADOOP-6668
> URL: https://issues.apache.org/jira/browse/HADOOP-6668
> Project: Hadoop Common
> Issue Type: Sub-task
> Components: documentation
> Reporter: Tom White
> Assignee: Tom White
> Priority: Blocker
> Fix For: 0.21.0
>
> Attachments: common.interface-tw-annotated.txt, HADOOP-6668.patch,
> HADOOP-6668.patch, HADOOP-6668.patch, HADOOP-6668.patch, HADOOP-6668.patch,
> HADOOP-6668.patch
>
>
> Mark private implementation classes with the InterfaceAudience.Private or
> InterfaceAudience.LimitedPrivate annotation to exclude them from user Javadoc
> and JDiff.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
