1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/jaxws_classes/com/sun/org/glassfish/external/arc/Stability.java Wed Apr 27 01:27:09 2016 +0800 1.3 @@ -0,0 +1,329 @@ 1.4 +/* 1.5 + * Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Oracle designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Oracle in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1.25 + * or visit www.oracle.com if you need additional information or have any 1.26 + * questions. 1.27 + */ 1.28 + 1.29 + 1.30 +package com.sun.org.glassfish.external.arc; 1.31 + 1.32 +/** 1.33 + Taxonomy values. 1.34 + See http://opensolaris.org/os/community/arc/policies/interface-taxonomy/ 1.35 + <p> 1.36 + <h3>Policy</h3> 1.37 + <ul> 1.38 + <li>Applies to All software produced by SMI</li> 1.39 + <li>Authority SAC</li> 1.40 + <li>Approval SAC</li> 1.41 + <li>Effective April, 1992</li> 1.42 + <li>Policy </li> 1.43 + <ul><li>All software interfaces must be classified according to this taxonomy. 1.44 + Interfaces are defined as APIs, files and directory structures, file formats, protocols, 1.45 + (sometimes) even performance and reliability behaviors, and any other attribute upon 1.46 + which another component might reasonably depend.</li> 1.47 + 1.48 + <li>An ARC must review, approve and archive the specification for all interfaces 1.49 + other than Project Private and Internal. Unreviewed, unapproved interfaces are assumed 1.50 + to be Internal. An adequate specification, suitable for archiving must exist for all 1.51 + interfaces submitted for review. Often Project Private interfaces are also reviewed if 1.52 + the presentation of them aids the understanding of the entire project or it is expected 1.53 + they will be promoted to a broader classification in the future.</li> 1.54 + 1.55 + <li>Adequate customer documentation must exist for all Public interfaces. 1.56 + It is strongly preferred that manual pages exist for all Public interfaces 1.57 + (supported on Solaris), even if only significant content of those pages are SYNOPSIS 1.58 + and ATTRIBUTES sections and a textual pointer to other documentation. 1.59 + Independent of the form of documentation delivery, the interface taxonomy commitment 1.60 + level must be presented to the consumer.</li> 1.61 + 1.62 + <li>In cases where the organization delivering the interface implementation does not 1.63 + control the interface specification, the controlling body must be be clearly cited 1.64 + in the documentation. In the case where a well-defined, versioned document is the 1.65 + specification, both the name and precise version must be be cited.</li> 1.66 + </ul> 1.67 + </ul> 1.68 + @author llc 1.69 + */ 1.70 +public enum Stability { 1.71 + /** 1.72 + <pre> 1.73 + +----------------------------------------------------------------------------+ 1.74 + | Committed (formerly Stable, Public; encompasses Standard, Evolving) | 1.75 + |----------------------------------------------------------------------------| 1.76 + | | Specification | Open | 1.77 + | |---------------------+--------------------------------------------------| 1.78 + | | Incompatible Change | major release (X.0) | 1.79 + | |---------------------+--------------------------------------------------| 1.80 + | | ARC review of Specs | Yes | 1.81 + | |---------------------+--------------------------------------------------| 1.82 + | | Examples | Compiler command line options, | 1.83 + | | | hardware (SBus, PCI, USB), RPC, POSIX utilities | 1.84 + +----------------------------------------------------------------------------+ 1.85 + </pre> 1.86 + We publish the specification of these interfaces, typically as manual pages or other product documentation. 1.87 + We also tell customers we will remain compatible with them. (Scott McNealy's principle that "Compatibility is a 1.88 + constraint, not a goal") The intention of a Committed interface is to enable arbitrary third parties to develop 1.89 + applications to these interfaces, release them, and have confidence that they will run on all releases of the product 1.90 + after the one in which the interface was introduced, and within the same Major release. Even at a Major release, 1.91 + incompatible changes are expected to be rare, and to have strong justifications. 1.92 + <p> 1.93 + Committed interfaces are often proposed to be industry standards, as was the case with RPC. 1.94 + Also, interfaces defined and controlled as industry standards are most often treated as Committed interfaces. 1.95 + <p> 1.96 + These are interfaces whose specification is often under the provider's control or which are specified by a 1.97 + clearly versioned document controlled by a well-defined organization. If the interface specification is not 1.98 + under the implementation provider's control, the provider must be willing to fork from the interface specification 1.99 + if required to maintain compatibility. In the case of interface specifications controlled by a standards body, 1.100 + the commitment must be to a clearly identified version of the specification, minimizing the likelihood of an 1.101 + incompatible change (but it can happen through formal spec interpretations). 1.102 + <p> 1.103 + Also, if the interface specification is not under the control of the interface implementation provider, 1.104 + then the controlling body and/or public, versioned document must be be noted in the documentation. 1.105 + This is particularly important for specifications controlled by recognized standards organizations. 1.106 + <p> 1.107 + Although a truely exceptional event, incompatible changes are possible in any release if 1.108 + the associated defect is serious enough as outlined in the EXEMPTIONS section of this document or 1.109 + in a Minor release by following the End of Feature process. 1.110 + */ 1.111 + COMMITTED( "Committed" ), 1.112 + 1.113 +/** 1.114 + <pre> 1.115 + +--------------------------------------------------------------------------+ 1.116 + | Uncommitted (formerly Unstable) | 1.117 + |--------------------------------------------------------------------------| 1.118 + | | Specification | Open | 1.119 + | |---------------------+------------------------------------------------| 1.120 + | | Incompatible Change | minor release (x.Y) with impact assessment | 1.121 + | |---------------------+------------------------------------------------| 1.122 + | | ARC review of Specs | Yes | 1.123 + | |---------------------+------------------------------------------------| 1.124 + | | Examples | SUNW* package abbreviations, some config utils | 1.125 + +--------------------------------------------------------------------------+ 1.126 + </pre> 1.127 + No guarantees are made about either source or binary compatibility of these interfaces 1.128 + from one Minor release to the next. The most drastic incompatible change of removal of 1.129 + the interface in a Minor release is allowed. Uncommitted interfaces are generally not 1.130 + appropriate for use by release-independent products. 1.131 + <p> 1.132 + Uncommitted is not a license for gratuitous change. Any incompatible changes to the 1.133 + interface should be motivated by true improvement to the interface which may include 1.134 + justifiable ease of use considerations. The general expectation is that Uncommitted 1.135 + interfaces are not likely to change incompatibly and if such changes occur they will be 1.136 + small in impact and should often have a mitigation plan. 1.137 + <p> 1.138 + Uncommitted interfaces generally fall into one of the following subcategories: 1.139 + <p> 1.140 + <ul> 1.141 + <li> 1.142 + Interfaces that are experimental or transitional. 1.143 + They are typically used to give outside developers early access to new or 1.144 + rapidly-changing technology, or to provide an interim solution to a problem where a 1.145 + more general solution is anticipated. 1.146 + </li> 1.147 + 1.148 + <li> 1.149 + Interfaces whose specification is controlled by an outside body and the 1.150 + implementation provider is only willing to commit to forking until the next minor 1.151 + release point should that outside body introduce incompatible change. 1.152 + Note that this "middle of the road" approach is often the best business decision 1.153 + when the controlling body hasn't established a history of respecting compatibility. 1.154 + </li> 1.155 + 1.156 + <li> 1.157 + Interfaces whose target audience values innovation (and possibly ease of use) over 1.158 + stability. This attribute is often asserted for administrative interfaces for higher 1.159 + web tier components. Note that ARC review may request data to support such an assertion. 1.160 + </li> 1.161 + <p> 1.162 + A project's intention to import an Uncommitted interface from another consolidation should 1.163 + be discussed with the ARC early. The stability classification of the interface -- or 1.164 + a replacement interface -- might be raised. The opinion allowing any project to import an 1.165 + Uncommitted interface must explain why it is acceptable, and a contract must be put into 1.166 + place allowing this use. For Sun products, the similarity in the usage of Uncommitted and 1.167 + Consolidation Private interfaces should be noted. 1.168 + <p> 1.169 + Any documentation for an Uncommitted interface must contain warnings that "these interfaces 1.170 + are subject to change without warning and should not be used in unbundled products". 1.171 + In some situations, it may be appropriate to document Uncommitted interfaces in white papers 1.172 + rather than in standard product documentation. When changes are introduced, the changes 1.173 + should be mentioned in the release notes for the affected release. 1.174 + <p> 1.175 + NOTE: If we choose to offer a draft standard implementation but state our intention to track 1.176 + the standard (or the portions we find technically sound or likely to be standardized), 1.177 + we set customer expectations for incompatible changes by classifying the interface Uncommitted. 1.178 + The interface must be reclassified Committed when standard is final. 1.179 + Such an intention could be encoded "Uncommitted->Committed".) 1.180 +</pre> 1.181 + */ 1.182 + UNCOMMITTED( "Uncommitted" ), 1.183 + 1.184 + 1.185 +/** 1.186 +<pre> 1.187 + +--------------------------------------------------------------------+ 1.188 + | Volatile (encompasses External) | 1.189 + |--------------------------------------------------------------------| 1.190 + | | Specification | Open | 1.191 + | |---------------------+------------------------------------------| 1.192 + | | Incompatible Change | micro release (x.y.z) or patch release | 1.193 + | |---------------------+------------------------------------------| 1.194 + | | Arc review of Specs | A precise reference is normally recorded | 1.195 + | |---------------------+------------------------------------------| 1.196 + | | Examples | Gimp user interface, IETF internet-draft | 1.197 + +--------------------------------------------------------------------+ 1.198 +</pre> 1.199 + Volatile interfaces may change at any time and for any reason. 1.200 + <p> 1.201 + Use of the Volatile interface stability level allows interface providers to 1.202 + quickly track a fluid, rapidly evolving specification. In many cases, this is 1.203 + preferred to providing additional stability to the interface, as it may better 1.204 + meet the expectations of the consumer. 1.205 + <p> 1.206 + The most common application of this taxonomy level is to interfaces that are 1.207 + controlled by a body other than the final implementation provider, but unlike 1.208 + specifications controlled by standards bodies or communities we place trust in, 1.209 + it can not be asserted that an incompatible change to the interface 1.210 + specification would be exceedingly rare. In some cases it may not even be 1.211 + possible to clearly identify the controlling body. Although not prohibited by 1.212 + this taxonomy, the Volatile classification is not typically applied to 1.213 + interfaces where the specification is controlled by the implementation provider. 1.214 + <p> 1.215 + It should be noted that in some cases it will be preferable to apply a less 1.216 + fluid interface classification to an interface even if the controlling body is 1.217 + separate from the implementor. Use of the Uncommitted classification extends the 1.218 + stability commitment over micro/patch releases, allowing use of additional 1.219 + support models for software that depends upon these interfaces, at the potential 1.220 + cost of less frequent updates. Committed should be considered for required, core 1.221 + interfaces. If instability in the interface definition can't be reconciled with 1.222 + the requirement for stability, then alternate solutions should be considered. 1.223 + <p> 1.224 + This classification is typically used for free or open source software (FOSS), 1.225 + also referred to as community software, and similar models where it is deemed 1.226 + more important to track the community with minimal latency than to provide 1.227 + stability to our customers. When applying this classification level to community 1.228 + software, particular attention should be paid to the considerations presented in 1.229 + the preceding paragraph. 1.230 + <p> 1.231 + It also may be appropriate to apply the Volatile classification level to 1.232 + interfaces in the process of being defined by trusted or widely accepted 1.233 + organization. These are generically referred to as draft standards. An "IETF 1.234 + internet draft" is a well understood example of a specification under 1.235 + development. 1.236 + <p> 1.237 + There may also cases where Volatile is appropriate for experimental interfaces, 1.238 + but in most cases Uncommitted should be considered first. 1.239 + <p> 1.240 + Irrespective of the control of the specification, the Volatile classification 1.241 + must not be applied to "core" interfaces (those that must be used) for which no 1.242 + alternate (and more stable) interface exists. Volatile interfaces must also 1.243 + adhere to Sun internal standards in the following areas: 1.244 + <ul> 1.245 + <li>Security, Authentication</li> 1.246 + <li>The existence of (perhaps vestigial) Manual Pages and conformance to Sun section numbering</li> 1.247 + <li>File System Semantics (Solaris examples: /usr may be read-only, /var is where 1.248 + all significant run-time growth occurs, ...)</li> 1.249 + </ul> 1.250 + All Volatile interfaces should be labeled as such in all associated 1.251 + documentation and the consequence of using such interfaces must be explained 1.252 + either as part of that documentation or by reference. 1.253 + <p> 1.254 + Shipping incompatible change in a patch should be strongly avoided. It is not 1.255 + strictly prohibited for the following two reasons: 1.256 + <ul> 1.257 + <li>Since the patch provider may not be in explicit control of the changes to the 1.258 + upstream implementation, it cannot guarantee with reasonable assurance that an 1.259 + unidentified incompatibility is not present. 1.260 + </li> 1.261 + <li>A strong business case may exist for shipping a newer version as a patch if that 1.262 + newer version closes significant escalations. 1.263 + </li> 1.264 + </ul> 1.265 + In general, the intent of allowing change in a patch is to allow for change in 1.266 + Update Releases. 1.267 + <p> 1.268 + Sun products should consider Volatile interfaces as equivalent to Consolidation 1.269 + Private. A contract is required for use of these interfaces outside of the 1.270 + supplying consolidation. 1.271 + <p> 1.272 + Extreme care in the use of Volatile interfaces is required by layered or 1.273 + unbundled products. Layered products that depend upon Volatile interfaces must 1.274 + include as part of their review material how they intend to manage the 1.275 + dependency. It is not explicitly prohibited, but it is probable that unbundled 1.276 + or layered products that ship asynchronously from the Volatile interfaces upon 1.277 + which they depend will face nearly insurmountable difficulty in constructing a 1.278 + plan to manage such a dependency. 1.279 + */ 1.280 + VOLATILE( "Volatile" ), 1.281 + 1.282 +/** 1.283 +<pre> 1.284 + +--------------------------------------------------------------------+ 1.285 + | Not-an-interface | 1.286 + |--------------------------------------------------------------------| 1.287 + | | Specification | None | 1.288 + | |---------------------+------------------------------------------| 1.289 + | | Incompatible Change | micro release (x.y.z) or patch release | 1.290 + | |---------------------+------------------------------------------| 1.291 + | | Arc review of Specs | None | 1.292 + | |---------------------+------------------------------------------| 1.293 + | | Examples | CLI output, error text | 1.294 + +--------------------------------------------------------------------+ 1.295 +</pre> 1.296 + In the course of reviewing or documenting interfaces, the situation often occurs 1.297 + that an attribute will be present which may be inferred to be an interface, but 1.298 + actually is not. A couple of common examples of this are output from CLIs 1.299 + intended only for human consumption and the exact layout of a GUI. 1.300 + <p> 1.301 + This classification is simply a convenience term to be used to clarify such 1.302 + situations where such confusion is identified as likely. Failure to apply this 1.303 + term to an attribute is no indication that said attribute is some form of 1.304 + interface. It only indicates that the potential for confusion was not 1.305 + identified. 1.306 + */ 1.307 + NOT_AN_INTERFACE( "Not-An-Interface" ), 1.308 + 1.309 + /** 1.310 + See: http://opensolaris.org/os/community/arc/policies/interface-taxonomy/ 1.311 + <p> 1.312 + Javadoc or other means should establish the nature of the private interface. 1.313 + */ 1.314 + PRIVATE( "Private" ), 1.315 + 1.316 + 1.317 + /** 1.318 + Not a formal term. Indicates that the interface, while visible, is experimental, 1.319 + and can be removed at any time. 1.320 + */ 1.321 + EXPERIMENTAL( "Experimental" ), 1.322 + 1.323 + /** 1.324 + Interrim classification; a real one should be chosen asap. 1.325 + */ 1.326 + UNSPECIFIED( "Unspecified" ); 1.327 + 1.328 + private final String mName; 1.329 + private Stability( final String name ) { mName = name; } 1.330 + 1.331 + public String toString() { return mName; } 1.332 +}