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