[
https://issues.apache.org/jira/browse/HADOOP-6668?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12866425#action_12866425
]
Sanjay Radia commented on HADOOP-6668:
--------------------------------------
Have gone through the Suresh's original proposal from HADOOP-6289 and Tom's
patch and comments on it.
There are several areas of disagreements - I will comment on each of them
separately.
Let me start with metrics - it is very instructive use case with some subtle
issues.
Suresh got it mostly right in his proposal. Here is slightly modified version
to highlight the
reasoning behind the classification choices for metrics:
# The actual metrics themsleves - many or most are *audience-public*; more
comfortable tagging them *evolving* rather than *stable*.
The actual metrics have to be documented separately, since making the
implementation-class audience-pubic is not appropriate.
** RPC metrics
** JVM Metrics
** HDFS metrics
** MR Metrics
# Interfaces for those implementing metrics (*Audience-LimitedPrivate* MR, HDFS)
Developers use these Interfaces for adding new metrics to the Hadoop system
(For example classes in item 3. use these interfaces to implement metrics)
** org/apache/hadoop/metrics/util/MetricsDynamicMBeanBase.java hdfs
** org/apache/hadoop/metrics/util/MetricsIntValue.java hdfs
** org/apache/hadoop/metrics/util/MetricsLongValue.java hdfs
** org/apache/hadoop/metrics/util/MetricsRegistry.java hdfs
** org/apache/hadoop/metrics/util/MetricsTimeVaryingInt.java hdfs
** org/apache/hadoop/metrics/util/MetricsTimeVaryingLong.java hdfs
** org/apache/hadoop/metrics/util/MetricsTimeVaryingRate.java hdfs
** org/apache/hadoop/metrics/util/MBeanUtil.java
** org/apache/hadoop/metrics/Updater.java hdfs mapreduce
** org/apache/hadoop/metrics/MetricsUtil.java
# Actual implementations of metrics (*Audience-Private*)
(Note the actual metrics can be public - see item 1)
** org/apache/hadoop/ipc/metrics/RpcActivityMBean.java
** org/apache/hadoop/ipc/metrics/RpcMetrics.java
** org/apache/hadoop/ipc/metrics/RpcMgt.java
** org/apache/hadoop/ipc/metrics/RpcMgtMBean.java
** org/apache/hadoop/metrics/jvm/EventCounter.java
** org/apache/hadoop/metrics/jvm/JvmMetrics.java
# Interfaces needed to implement the plugins (See the actual impls in item 5:
Ganglia, File, etc) - *Audience-public*, evolving
** org/apache/hadoop/metrics/spi/AbstractMetricsContext.java
** org/apache/hadoop/metrics/spi/CompositeContext.java
** org/apache/hadoop/metrics/spi/MetricsRecordImpl.java
** org/apache/hadoop/metrics/spi/MetricValue.java
** org/apache/hadoop/metrics/spi/OutputRecord.java
** org/apache/hadoop/metrics/spi/Util.java
# The impelmentation of metrics plugins
The actual impl is *audience-private* but the class *name* is public since the
class name is used in the config file.
So mark the class as *audience-public*(evolving), but mark all its public
methods as *audience-private*.
** org/apache/hadoop/metrics/ganglia/GangliaContext.java
** org/apache/hadoop/metrics/file/FileContext.java hdfs
** org/apache/hadoop/metrics/spi/NoEmitMetricsContext.java
** org/apache/hadoop/metrics/spi/NullContext.java
** org/apache/hadoop/metrics/spi/NullContextWithUpdateThread.java
# Metrics Framework Impl - *audience-private*
** org/apache/hadoop/metrics/MetricsContext.java hdfs mapreduce
** org/apache/hadoop/metrics/util/MetricsBase.java
** org/apache/hadoop/metrics/MetricsRecord.java hdfs mapreduce
** org/apache/hadoop/metrics/ContextFactory.java
** org/apache/hadoop/metrics/MetricsException.java
** org/apache/hadoop/metrics/MetricsServlet.java
> 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.
