1 /* 2 * Copyright (c) 2008, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.org.glassfish.external.arc; 27 28 29 30 /** 31 Taxonomy values. 32 See http://opensolaris.org/os/community/arc/policies/interface-taxonomy/ 33 <p> 34 <h3>Policy</h3> 35 <ul> 36 <li>Applies to All software produced by SMI</li> 37 <li>Authority SAC</li> 38 <li>Approval SAC</li> 39 <li>Effective April, 1992</li> 40 <li>Policy </li> 41 <ul><li>All software interfaces must be classified according to this taxonomy. 42 Interfaces are defined as APIs, files and directory structures, file formats, protocols, 43 (sometimes) even performance and reliability behaviors, and any other attribute upon 44 which another component might reasonably depend.</li> 45 46 <li>An ARC must review, approve and archive the specification for all interfaces 47 other than Project Private and Internal. Unreviewed, unapproved interfaces are assumed 48 to be Internal. An adequate specification, suitable for archiving must exist for all 49 interfaces submitted for review. Often Project Private interfaces are also reviewed if 50 the presentation of them aids the understanding of the entire project or it is expected 51 they will be promoted to a broader classification in the future.</li> 52 53 <li>Adequate customer documentation must exist for all Public interfaces. 54 It is strongly preferred that manual pages exist for all Public interfaces 55 (supported on Solaris), even if only significant content of those pages are SYNOPSIS 56 and ATTRIBUTES sections and a textual pointer to other documentation. 57 Independent of the form of documentation delivery, the interface taxonomy commitment 58 level must be presented to the consumer.</li> 59 60 <li>In cases where the organization delivering the interface implementation does not 61 control the interface specification, the controlling body must be be clearly cited 62 in the documentation. In the case where a well-defined, versioned document is the 63 specification, both the name and precise version must be be cited.</li> 64 </ul> 65 </ul> 66 @author llc 67 */ 68 public enum Stability { 69 /** 70 <pre> 71 +----------------------------------------------------------------------------+ 72 | Committed (formerly Stable, Public; encompasses Standard, Evolving) | 73 |----------------------------------------------------------------------------| 74 | | Specification | Open | 75 | |---------------------+--------------------------------------------------| 76 | | Incompatible Change | major release (X.0) | 77 | |---------------------+--------------------------------------------------| 78 | | ARC review of Specs | Yes | 79 | |---------------------+--------------------------------------------------| 80 | | Examples | Compiler command line options, | 81 | | | hardware (SBus, PCI, USB), RPC, POSIX utilities | 82 +----------------------------------------------------------------------------+ 83 </pre> 84 We publish the specification of these interfaces, typically as manual pages or other product documentation. 85 We also tell customers we will remain compatible with them. (Scott McNealy's principle that "Compatibility is a 86 constraint, not a goal") The intention of a Committed interface is to enable arbitrary third parties to develop 87 applications to these interfaces, release them, and have confidence that they will run on all releases of the product 88 after the one in which the interface was introduced, and within the same Major release. Even at a Major release, 89 incompatible changes are expected to be rare, and to have strong justifications. 90 <p> 91 Committed interfaces are often proposed to be industry standards, as was the case with RPC. 92 Also, interfaces defined and controlled as industry standards are most often treated as Committed interfaces. 93 <p> 94 These are interfaces whose specification is often under the provider's control or which are specified by a 95 clearly versioned document controlled by a well-defined organization. If the interface specification is not 96 under the implementation provider's control, the provider must be willing to fork from the interface specification 97 if required to maintain compatibility. In the case of interface specifications controlled by a standards body, 98 the commitment must be to a clearly identified version of the specification, minimizing the likelihood of an 99 incompatible change (but it can happen through formal spec interpretations). 100 <p> 101 Also, if the interface specification is not under the control of the interface implementation provider, 102 then the controlling body and/or public, versioned document must be be noted in the documentation. 103 This is particularly important for specifications controlled by recognized standards organizations. 104 <p> 105 Although a truely exceptional event, incompatible changes are possible in any release if 106 the associated defect is serious enough as outlined in the EXEMPTIONS section of this document or 107 in a Minor release by following the End of Feature process. 108 */ 109 COMMITTED( "Committed" ), 110 111 /** 112 <pre> 113 +--------------------------------------------------------------------------+ 114 | Uncommitted (formerly Unstable) | 115 |--------------------------------------------------------------------------| 116 | | Specification | Open | 117 | |---------------------+------------------------------------------------| 118 | | Incompatible Change | minor release (x.Y) with impact assessment | 119 | |---------------------+------------------------------------------------| 120 | | ARC review of Specs | Yes | 121 | |---------------------+------------------------------------------------| 122 | | Examples | SUNW* package abbreviations, some config utils | 123 +--------------------------------------------------------------------------+ 124 </pre> 125 No guarantees are made about either source or binary compatibility of these interfaces 126 from one Minor release to the next. The most drastic incompatible change of removal of 127 the interface in a Minor release is allowed. Uncommitted interfaces are generally not 128 appropriate for use by release-independent products. 129 <p> 130 Uncommitted is not a license for gratuitous change. Any incompatible changes to the 131 interface should be motivated by true improvement to the interface which may include 132 justifiable ease of use considerations. The general expectation is that Uncommitted 133 interfaces are not likely to change incompatibly and if such changes occur they will be 134 small in impact and should often have a mitigation plan. 135 <p> 136 Uncommitted interfaces generally fall into one of the following subcategories: 137 <p> 138 <ul> 139 <li> 140 Interfaces that are experimental or transitional. 141 They are typically used to give outside developers early access to new or 142 rapidly-changing technology, or to provide an interim solution to a problem where a 143 more general solution is anticipated. 144 </li> 145 146 <li> 147 Interfaces whose specification is controlled by an outside body and the 148 implementation provider is only willing to commit to forking until the next minor 149 release point should that outside body introduce incompatible change. 150 Note that this "middle of the road" approach is often the best business decision 151 when the controlling body hasn't established a history of respecting compatibility. 152 </li> 153 154 <li> 155 Interfaces whose target audience values innovation (and possibly ease of use) over 156 stability. This attribute is often asserted for administrative interfaces for higher 157 web tier components. Note that ARC review may request data to support such an assertion. 158 </li> 159 <p> 160 A project's intention to import an Uncommitted interface from another consolidation should 161 be discussed with the ARC early. The stability classification of the interface -- or 162 a replacement interface -- might be raised. The opinion allowing any project to import an 163 Uncommitted interface must explain why it is acceptable, and a contract must be put into 164 place allowing this use. For Sun products, the similarity in the usage of Uncommitted and 165 Consolidation Private interfaces should be noted. 166 <p> 167 Any documentation for an Uncommitted interface must contain warnings that "these interfaces 168 are subject to change without warning and should not be used in unbundled products". 169 In some situations, it may be appropriate to document Uncommitted interfaces in white papers 170 rather than in standard product documentation. When changes are introduced, the changes 171 should be mentioned in the release notes for the affected release. 172 <p> 173 NOTE: If we choose to offer a draft standard implementation but state our intention to track 174 the standard (or the portions we find technically sound or likely to be standardized), 175 we set customer expectations for incompatible changes by classifying the interface Uncommitted. 176 The interface must be reclassified Committed when standard is final. 177 Such an intention could be encoded "Uncommitted->Committed".) 178 </pre> 179 */ 180 UNCOMMITTED( "Uncommitted" ), 181 182 183 /** 184 <pre> 185 +--------------------------------------------------------------------+ 186 | Volatile (encompasses External) | 187 |--------------------------------------------------------------------| 188 | | Specification | Open | 189 | |---------------------+------------------------------------------| 190 | | Incompatible Change | micro release (x.y.z) or patch release | 191 | |---------------------+------------------------------------------| 192 | | Arc review of Specs | A precise reference is normally recorded | 193 | |---------------------+------------------------------------------| 194 | | Examples | Gimp user interface, IETF internet-draft | 195 +--------------------------------------------------------------------+ 196 </pre> 197 Volatile interfaces may change at any time and for any reason. 198 <p> 199 Use of the Volatile interface stability level allows interface providers to 200 quickly track a fluid, rapidly evolving specification. In many cases, this is 201 preferred to providing additional stability to the interface, as it may better 202 meet the expectations of the consumer. 203 <p> 204 The most common application of this taxonomy level is to interfaces that are 205 controlled by a body other than the final implementation provider, but unlike 206 specifications controlled by standards bodies or communities we place trust in, 207 it can not be asserted that an incompatible change to the interface 208 specification would be exceedingly rare. In some cases it may not even be 209 possible to clearly identify the controlling body. Although not prohibited by 210 this taxonomy, the Volatile classification is not typically applied to 211 interfaces where the specification is controlled by the implementation provider. 212 <p> 213 It should be noted that in some cases it will be preferable to apply a less 214 fluid interface classification to an interface even if the controlling body is 215 separate from the implementor. Use of the Uncommitted classification extends the 216 stability commitment over micro/patch releases, allowing use of additional 217 support models for software that depends upon these interfaces, at the potential 218 cost of less frequent updates. Committed should be considered for required, core 219 interfaces. If instability in the interface definition can't be reconciled with 220 the requirement for stability, then alternate solutions should be considered. 221 <p> 222 This classification is typically used for free or open source software (FOSS), 223 also referred to as community software, and similar models where it is deemed 224 more important to track the community with minimal latency than to provide 225 stability to our customers. When applying this classification level to community 226 software, particular attention should be paid to the considerations presented in 227 the preceding paragraph. 228 <p> 229 It also may be appropriate to apply the Volatile classification level to 230 interfaces in the process of being defined by trusted or widely accepted 231 organization. These are generically referred to as draft standards. An "IETF 232 internet draft" is a well understood example of a specification under 233 development. 234 <p> 235 There may also cases where Volatile is appropriate for experimental interfaces, 236 but in most cases Uncommitted should be considered first. 237 <p> 238 Irrespective of the control of the specification, the Volatile classification 239 must not be applied to "core" interfaces (those that must be used) for which no 240 alternate (and more stable) interface exists. Volatile interfaces must also 241 adhere to Sun internal standards in the following areas: 242 <ul> 243 <li>Security, Authentication</li> 244 <li>The existence of (perhaps vestigial) Manual Pages and conformance to Sun section numbering</li> 245 <li>File System Semantics (Solaris examples: /usr may be read-only, /var is where 246 all significant run-time growth occurs, ...)</li> 247 </ul> 248 All Volatile interfaces should be labeled as such in all associated 249 documentation and the consequence of using such interfaces must be explained 250 either as part of that documentation or by reference. 251 <p> 252 Shipping incompatible change in a patch should be strongly avoided. It is not 253 strictly prohibited for the following two reasons: 254 <ul> 255 <li>Since the patch provider may not be in explicit control of the changes to the 256 upstream implementation, it cannot guarantee with reasonable assurance that an 257 unidentified incompatibility is not present. 258 </li> 259 <li>A strong business case may exist for shipping a newer version as a patch if that 260 newer version closes significant escalations. 261 </li> 262 </ul> 263 In general, the intent of allowing change in a patch is to allow for change in 264 Update Releases. 265 <p> 266 Sun products should consider Volatile interfaces as equivalent to Consolidation 267 Private. A contract is required for use of these interfaces outside of the 268 supplying consolidation. 269 <p> 270 Extreme care in the use of Volatile interfaces is required by layered or 271 unbundled products. Layered products that depend upon Volatile interfaces must 272 include as part of their review material how they intend to manage the 273 dependency. It is not explicitly prohibited, but it is probable that unbundled 274 or layered products that ship asynchronously from the Volatile interfaces upon 275 which they depend will face nearly insurmountable difficulty in constructing a 276 plan to manage such a dependency. 277 */ 278 VOLATILE( "Volatile" ), 279 280 /** 281 <pre> 282 +--------------------------------------------------------------------+ 283 | Not-an-interface | 284 |--------------------------------------------------------------------| 285 | | Specification | None | 286 | |---------------------+------------------------------------------| 287 | | Incompatible Change | micro release (x.y.z) or patch release | 288 | |---------------------+------------------------------------------| 289 | | Arc review of Specs | None | 290 | |---------------------+------------------------------------------| 291 | | Examples | CLI output, error text | 292 +--------------------------------------------------------------------+ 293 </pre> 294 In the course of reviewing or documenting interfaces, the situation often occurs 295 that an attribute will be present which may be inferred to be an interface, but 296 actually is not. A couple of common examples of this are output from CLIs 297 intended only for human consumption and the exact layout of a GUI. 298 <p> 299 This classification is simply a convenience term to be used to clarify such 300 situations where such confusion is identified as likely. Failure to apply this 301 term to an attribute is no indication that said attribute is some form of 302 interface. It only indicates that the potential for confusion was not 303 identified. 304 */ 305 NOT_AN_INTERFACE( "Not-An-Interface" ), 306 307 /** 308 See: http://opensolaris.org/os/community/arc/policies/interface-taxonomy/ 309 <p> 310 Javadoc or other means should establish the nature of the private interface. 311 */ 312 PRIVATE( "Private" ), 313 314 315 /** 316 Not a formal term. Indicates that the interface, while visible, is experimental, 317 and can be removed at any time. 318 */ 319 EXPERIMENTAL( "Experimental" ), 320 321 /** 322 Interrim classification; a real one should be chosen asap. 323 */ 324 UNSPECIFIED( "Unspecified" ); 325 326 private final String mName; 327 private Stability( final String name ) { mName = name; } 328 329 public String toString() { return mName; } 330 }