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 +}
