hadoop-common-issues mailing list archives

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

    [ https://issues.apache.org/jira/browse/HADOOP-6668?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12863950#action_12863950
] 

Sanjay Radia commented on HADOOP-6668:
--------------------------------------


The propsoal in HADOOP-5073 and HADOOP-6289 have used different criteria than
the one stated in this Jira (see TW's comment in the begining of this Jira)
Let me clarify:
> * Public user APIs should be marked as 'public stable'. These appear in public Javadoc.
> * APIs that are exposed to the user but not coded against directly should be marked as
'public evolving'. ... 
> These appear in public Javadoc.

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,)" 
I disagree with your metrics example: we should not expose APIs like metrics as audience public.
They should be limited private. 
Don't mark an interface  audience-public unless it is absolutely necessary.
 
> * Non-user facing APIs that are used within HADOOP subprojects should be marked as 'limited-private
evolving' 
> (e.g. RPC) or 'limited-private unstable'. These appear in developer Javadoc.
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*. They impact  interoperation and in the future they will impact
rolling upgrades.
Again see the HADOOP-5073's FAQ.

> * Anything that is private implementation code should be marked as 'private unstable'.
These appear in developer Javadoc.
Agreed.

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

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


Mime
View raw message