hadoop-common-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Tom White (JIRA)" <j...@apache.org>
Subject [jira] Commented: (HADOOP-6668) Apply audience and stability annotations to classes in common
Date Tue, 04 May 2010 19:57:57 GMT

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

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,)" 

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.

I disagree with your metrics example: we should not expose APIs like metrics as audience public.
They should be limited private. 

Limited private for use by which components or subprojects? How would I write my own metrics

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

I agree with this. (Indeed I marked ClientProtocol in MAPREDUCE-1623 private stable.)

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

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.

View raw message