| <!--- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <html> |
| <head> |
| <meta charset="utf-8"> |
| <title>Apache Yetus</title> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="description" content=""> |
| <meta name="author" content=""> |
| |
| <link href="../../../assets/css/bootstrap.css" rel="stylesheet"> |
| <link href="../../../assets/css/bootstrap-theme.css" rel="stylesheet"> |
| <link href="../../../assets/css/font-awesome.css" rel="stylesheet"> |
| |
| <!-- JS --> |
| <script type="text/javascript" src="../../../assets/js/jquery-2.1.4.min.js"></script> |
| <script type="text/javascript" src="../../../assets/js/bootstrap.js"></script> |
| </head> |
| <body> |
| |
| <div class="navbar navbar-inverse navbar-static-top" role="navigation"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="img-responsive pull-left" href="/"> |
| <img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../../assets/img/yetus_logo.png" alt="Apache Yetus logo" /> |
| </a> |
| </div> |
| <div class="navbar-collapse collapse"> |
| <ul class="nav navbar-nav"> |
| <li><a href="/downloads/">Downloads</a> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu"> |
| <li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li> |
| <li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li> |
| <li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li> |
| <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a> |
| </li> |
| <li><a href="/documentation/history/">History of the Project</a> |
| </li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu" aria-labelledby="drop1"> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a> |
| <ul class="dropdown-menu" role="menu"> |
| <li><a href="https://www.apache.org">Apache Homepage</a> |
| </li> |
| <li><a href="https://www.apache.org/licenses/">Apache License</a> |
| </li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| </li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| </li> |
| <li><a href="https://www.apache.org/security/">Security</a> |
| </li> |
| </ul> |
| </li> |
| </li> |
| </ul> |
| </div> |
| <!--/.nav-collapse --> |
| </div> |
| </div> |
| |
| <div class="container"> |
| <!--- |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. See accompanying LICENSE file. |
| --> |
| |
| <h1 id="apache-yetus-interface-taxonomy-audience-and-stability-classification">Apache Yetus Interface Taxonomy: Audience and Stability Classification</h1> |
| |
| <!-- MarkdownTOC levels="1,2,3" autolink="true" indent=" " bullets="*" bracket="round" --> |
| |
| <ul> |
| <li><a href="#motivation">Motivation</a></li> |
| <li><a href="#interface-classification">Interface Classification</a> |
| <ul> |
| <li><a href="#audience">Audience</a> |
| <ul> |
| <li><a href="#private">Private</a></li> |
| <li><a href="#limited-private">Limited-Private</a></li> |
| <li><a href="#public">Public</a></li> |
| </ul> |
| </li> |
| <li><a href="#stability">Stability</a> |
| <ul> |
| <li><a href="#stable">Stable</a></li> |
| <li><a href="#evolving">Evolving</a></li> |
| <li><a href="#deprecated">Deprecated</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#how-are-the-classifications-recorded">How are the Classifications Recorded</a></li> |
| <li><a href="#faq">FAQ</a></li> |
| </ul> |
| |
| <!-- /MarkdownTOC --> |
| |
| <h1 id="motivation">Motivation</h1> |
| |
| <p>The interface taxonomy classification provided by Apache Yetus annotations is for guidance to developers and users of interfaces. The classification guides a developer to declare the targeted audience or users of an interface and also its stability.</p> |
| |
| <ul> |
| <li> |
| <p>Benefits to the user of an interface: Knows which interfaces to use or not use and their stability.</p> |
| </li> |
| <li> |
| <p>Benefits to the developer: to prevent accidental changes of interfaces and<br /> |
| hence accidental impact on users or other components or system. This is<br /> |
| particularly useful in large systems with many developers who may not all have a shared state/history of the project.</p> |
| </li> |
| </ul> |
| |
| <h1 id="interface-classification">Interface Classification</h1> |
| |
| <p>Yetus provides the following interface classification, derived from the<br /> |
| <a href="https://web.archive.org/web/20061013114610/http://opensolaris.org/os/community/arc/policies/interface-taxonomy/">OpenSolaris taxonomy</a><br /> |
| and, to some extent, from taxonomy used inside Yahoo.<br /> |
| Interfaces have two main attributes: Audience and Stability</p> |
| |
| <h2 id="audience">Audience</h2> |
| |
| <p>Audience denotes the potential consumers of the interface. While many interfaces are internal/private to the implementation, others are public/external interfaces and are meant for wider consumption by applications and/or clients. For example, POSIX definitions in libc are external, while large parts of the kernel are internal or private interfaces. Also, some interfaces are targeted towards other specific subsystems.</p> |
| |
| <p>Identifying the audience of an interface helps define the impact of breaking<br /> |
| it. For instance, it might be okay to break the compatibility of an interface<br /> |
| whose audience is a small number of specific subsystems. On the other hand, it<br /> |
| is probably not okay to break a protocol interfaces that millions of Internet<br /> |
| users depend on.</p> |
| |
| <p>Yetus uses the following kinds of audience in order of increasing/wider visibility:</p> |
| |
| <h3 id="private">Private</h3> |
| |
| <p>The interface is for internal use within a project(such as Apache Hadoop)<br /> |
| and should not be used by applications or by other projects. It is subject to<br /> |
| change at anytime without notice. Most interfaces of a project are Private (also referred to as project-private).</p> |
| |
| <h3 id="limited-private">Limited-Private</h3> |
| |
| <p>The interface is used by a specified set of projects or systems (typically<br /> |
| closely related projects). Other projects or systems should not use the<br /> |
| interface. Changes to the interface will be communicated/ negotiated with the<br /> |
| specified projects. For example, in the Apache Hadoop project, some interfaces are LimitedPrivate{HDFS, MapReduce} in that they are private to the HDFS and<br /> |
| MapReduce subprojects.</p> |
| |
| <h3 id="public">Public</h3> |
| |
| <p>The interface is for general use by any application.</p> |
| |
| <h2 id="stability">Stability</h2> |
| |
| <p>Stability denotes how stable an interface is, as in when incompatible changes to<br /> |
| the interface are allowed. Yetus provides the following levels of stability.</p> |
| |
| <h3 id="stable">Stable</h3> |
| |
| <p>Can evolve while retaining compatibility for minor release boundaries; in other<br /> |
| words, incompatible changes to APIs marked Stable are generally only allowed<br /> |
| at major releases (i.e. at m.0).</p> |
| |
| <h3 id="evolving">Evolving</h3> |
| |
| <p>Evolving, but incompatible changes are allowed at minor release (i.e. m .x)</p> |
| |
| <h4 id="unstable">Unstable</h4> |
| |
| <p>Incompatible changes to Unstable APIs are allowed any time. This usually makes<br /> |
| sense for only private interfaces.</p> |
| |
| <p>However one may call this out for a supposedly public interface to highlight<br /> |
| that it should not be used as an interface; for public interfaces, labeling it<br /> |
| as Not-an-interface is probably more appropriate than "Unstable".</p> |
| |
| <p>Examples of publicly visible interfaces that are unstable<br /> |
| (i.e. not-an-interface): GUI, CLIs whose output format will change</p> |
| |
| <h3 id="deprecated">Deprecated</h3> |
| |
| <p>APIs that could potentially be removed in the future and should not be used.</p> |
| |
| <h1 id="how-are-the-classifications-recorded">How are the Classifications Recorded</h1> |
| |
| <p>How should the classification be recorded for the annotated APIs?</p> |
| |
| <ul> |
| <li>Each interface or class will have the audience and stability recorded using<br /> |
| annotations in org.apache.yetus.classification package.</li> |
| <li>The javadoc generated by the maven target javadoc:javadoc lists only the public API.</li> |
| <li>One can derive the audience of Java classes and Java interfaces by the<br /> |
| audience of the package in which they are contained. Hence it is useful to<br /> |
| declare the audience of each Java package as public or private (along with the private audience variations).</li> |
| </ul> |
| |
| <h1 id="faq">FAQ</h1> |
| |
| <ul> |
| <li>Why aren't the Java scopes (private, package private and public) good enough? |
| <ul> |
| <li>Java's scoping is not very complete. One is often forced to make a class public in order for other internal components to use it. It does not have friends or sub-package-private like C++.</li> |
| </ul> |
| </li> |
| <li>But I can easily access a private implementation interface if it is Java public. Where is the protection and control? |
| <ul> |
| <li>The purpose of this is not providing absolute access control. Its purpose<br /> |
| is to communicate to users and developers. One can access private<br /> |
| implementation functions in libc; however if they change the internal<br /> |
| implementation details, your application will break and you will have<br /> |
| little sympathy from the folks who are supplying libc. If you use a<br /> |
| non-public interface you understand the risks.</li> |
| </ul> |
| </li> |
| <li>Why bother declaring the stability of a private interface?<br /> |
| Aren't private interfaces always unstable? |
| <ul> |
| <li>Private interfaces are not always unstable. In the cases where they are<br /> |
| stable they capture internal properties of the system and can communicate<br /> |
| these properties to its internal users and to developers of the interface. |
| <ul> |
| <li>e.g. In HDFS, NN-DN protocol is private but stable and can help<br /> |
| implement rolling upgrades. It communicates that this interface should<br /> |
| not be changed in incompatible ways even though it is private.</li> |
| <li>e.g. In HDFS, FSImage stability can help provide more flexible roll backs.</li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li>What is the harm in applications using a private interface that is stable? How is it different than a public stable interface? |
| <ul> |
| <li>While a private interface marked as stable is targeted to change only at<br /> |
| major releases, it may break at other times if the providers of that<br /> |
| interface are willing to changes the internal users of that<br /> |
| interface. Further, a public stable interface is less likely to break even<br /> |
| at major releases (even though it is allowed to break compatibility)<br /> |
| because the impact of the change is larger. If you use a private interface<br /> |
| (regardless of its stability) you run the risk of incompatibility.</li> |
| </ul> |
| </li> |
| <li>Why bother with Limited-private? Isn't it giving special treatment to some projects? That is not fair. |
| <ul> |
| <li>First, most interfaces should be public or private; actually let us state<br /> |
| it even stronger: make it private unless you really want to expose it to<br /> |
| public for general use.</li> |
| <li>Limited-private is for interfaces that are not intended for general<br /> |
| use. They are exposed to related projects that need special hooks. Such a<br /> |
| classification has a cost to both the supplier and consumer of the limited<br /> |
| interface. Both will have to work together if ever there is a need to<br /> |
| break the interface in the future; for example the supplier and the<br /> |
| consumers will have to work together to get coordinated releases of their<br /> |
| respective projects. This should not be taken lightly - if you can get<br /> |
| away with private then do so; if the interface is really for general use<br /> |
| for all applications then you should consider making it public. But remember<br /> |
| that making an interface public has huge responsibility. Sometimes<br /> |
| Limited-private is just right.</li> |
| <li>A good example of a limited-private interface is BlockLocations in the Apache<br /> |
| Hadoop Project, This is fairly low-level interface that they are willing to<br /> |
| expose to MR and perhaps HBase. They are likely to change it down the road<br /> |
| and at that time they will have to get a coordinated effort with the MR<br /> |
| team to release matching releases. While MR and HDFS are always released<br /> |
| in sync today, they may change down the road.</li> |
| <li>If you have a limited-private interface with many projects listed then you are fooling yourself. It is practically public.</li> |
| <li>It might be worth declaring a special audience classification called<br /> |
| {YourProjectName}-Private for your closely related projects.</li> |
| </ul> |
| </li> |
| <li>Can't a private interface be treated as project-private also? For example what is the harm in projects in the Apache Hadoop extended ecosystem, having access to private classes? |
| <ul> |
| <li>Do we want MR accessing class files that are implementation details inside<br /> |
| HDFS? There used to be many such layer violations in the Apache Hadoop<br /> |
| project that they have been cleaning up over the last few years. It is highly<br /> |
| undesirable for such layer violations to creep back in by no separation<br /> |
| between the major components like HDFS and MR.</li> |
| </ul> |
| </li> |
| <li>Aren't all public interfaces stable? |
| <ul> |
| <li>One may mark a public interface as evolving in its early days. Here one is<br /> |
| promising to make an effort to make compatible changes but may need to<br /> |
| break it at minor releases.</li> |
| <li>One example of a public interface that is unstable is where one is<br /> |
| providing an implementation of a standards-body based interface that is<br /> |
| still under development. For example, many companies, in an attempt to be<br /> |
| first to market, have provided implementations of a new NFS protocol even<br /> |
| when the protocol was not fully completed by IETF. The implementor cannot<br /> |
| evolve the interface in a fashion that causes least disruption because<br /> |
| the stability is controlled by the standards body. Hence it is appropriate<br /> |
| to label the interface as unstable.</li> |
| </ul> |
| </li> |
| </ul> |
| |
| </div> |
| |
| <div class="container"> |
| <hr> |
| <footer class="footer"> |
| <div class="row-fluid"> |
| <div class="span12 text-left"> |
| <div class="span12"> |
| Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation. |
| </div> |
| </div> |
| |
| </div> |
| |
| </footer> |
| </div> |
| |
| </body> |
| </html> |