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 Wed, 05 May 2010 03:20:04 GMT

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

Tom White commented on HADOOP-6668:

>Limited private for use by which components or subprojects? 
Limited private to MR and HDFS.
>> How would I write my own metrics context?
Who is "I"? If MR or HDFS developer then he is part of the target audience.
If "I" is an application developer then he runs a risk using a limited-private API - it may
change in incompatible ways of the MR and HDFS projects are okay with it.

Sorry, "I" refers to an application developer writing a new metrics context. There is a service
provider interface in org.apache.hadoop.metrics.spi, which clearly needs to be available to
such a developer. My question was really about what is the appropriate component for LimitedPrivate,
since an application developer may not host it in MR or HDFS. The option you outline is probably
the best - mark the SPI classes as LimitedPrivate (MR and HDFS), and then the developer would
use the developer javadoc. The only thing that isn't quite right is that the application developer
is using an interface that is private to MR and HDFS, but it would work.

The metrics APIs are separate form the actual metrics.
You can consider marking specific classes that implement metrics public or private - but if
you mark them as public then you are asserting that the actual implementation classes for
the specific metrics are public - ie the impl class API is public.
If your intension is to make specific sets of metrics (say for NN) public then you have to
document that in your documentation - the annotation mechanism cannot help here unless we
extend it.

I understand, but what we need to solve is the discoverability problem - if we mark all the
metrics classes as LimitedPrivate (which is what I think you are suggesting), then how do
users find the documentation to configure them?

> 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