org.glassfish.external.arc

Enum Stability

java.lang.Object

java.lang.Enum<Stability>

org.glassfish.external.arc.Stability

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Stability>

public enum Stability
extends java.lang.Enum<Stability>

Taxonomy values. See http://opensolaris.org/os/community/arc/policies/interface-taxonomy/

Policy

• Applies to All software produced by SMI
• Authority SAC
• Approval SAC
• Effective April, 1992
• Policy
• All software interfaces must be classified according to this taxonomy. Interfaces are defined as APIs, files and directory structures, file formats, protocols, (sometimes) even performance and reliability behaviors, and any other attribute upon which another component might reasonably depend.
• An ARC must review, approve and archive the specification for all interfaces other than Project Private and Internal. Unreviewed, unapproved interfaces are assumed to be Internal. An adequate specification, suitable for archiving must exist for all interfaces submitted for review. Often Project Private interfaces are also reviewed if the presentation of them aids the understanding of the entire project or it is expected they will be promoted to a broader classification in the future.
• Adequate customer documentation must exist for all Public interfaces. It is strongly preferred that manual pages exist for all Public interfaces (supported on Solaris), even if only significant content of those pages are SYNOPSIS and ATTRIBUTES sections and a textual pointer to other documentation. Independent of the form of documentation delivery, the interface taxonomy commitment level must be presented to the consumer.
• In cases where the organization delivering the interface implementation does not control the interface specification, the controlling body must be be clearly cited in the documentation. In the case where a well-defined, versioned document is the specification, both the name and precise version must be be cited.

Enum Constant Summary

Enum Constants

Enum Constant and Description
COMMITTED +----------------------------------------------------------------------------+ | Committed (formerly Stable, Public; encompasses Standard, Evolving) | |----------------------------------------------------------------------------| | | Specification | Open | | |---------------------+--------------------------------------------------| | | Incompatible Change | major release (X.0) | | |---------------------+--------------------------------------------------| | | ARC review of Specs | Yes | | |---------------------+--------------------------------------------------| | | Examples | Compiler command line options, | | | | hardware (SBus, PCI, USB), RPC, POSIX utilities | +----------------------------------------------------------------------------+
EXPERIMENTAL Not a formal term.
NOT_AN_INTERFACE +--------------------------------------------------------------------+ | Not-an-interface | |--------------------------------------------------------------------| | | Specification | None | | |---------------------+------------------------------------------| | | Incompatible Change | micro release (x.y.z) or patch release | | |---------------------+------------------------------------------| | | Arc review of Specs | None | | |---------------------+------------------------------------------| | | Examples | CLI output, error text | +--------------------------------------------------------------------+
PRIVATE See: http://opensolaris.org/os/community/arc/policies/interface-taxonomy/
UNCOMMITTED +--------------------------------------------------------------------------+ | Uncommitted (formerly Unstable) | |--------------------------------------------------------------------------| | | Specification | Open | | |---------------------+------------------------------------------------| | | Incompatible Change | minor release (x.Y) with impact assessment | | |---------------------+------------------------------------------------| | | ARC review of Specs | Yes | | |---------------------+------------------------------------------------| | | Examples | SUNW* package abbreviations, some config utils | +--------------------------------------------------------------------------+
UNSPECIFIED Interrim classification; a real one should be chosen asap.
VOLATILE +--------------------------------------------------------------------+ | Volatile (encompasses External) | |--------------------------------------------------------------------| | | Specification | Open | | |---------------------+------------------------------------------| | | Incompatible Change | micro release (x.y.z) or patch release | | |---------------------+------------------------------------------| | | Arc review of Specs | A precise reference is normally recorded | | |---------------------+------------------------------------------| | | Examples | Gimp user interface, IETF internet-draft | +--------------------------------------------------------------------+

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String	mName

Method Summary

Modifier and Type	Method and Description
java.lang.String	toString()
static Stability	valueOf(java.lang.String name) Returns the enum constant of this type with the specified name.
static Stability[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

COMMITTED

public static final Stability COMMITTED

    +----------------------------------------------------------------------------+                         
    | Committed (formerly Stable, Public; encompasses Standard, Evolving)        |                         
    |----------------------------------------------------------------------------|                         
    |   | Specification       | Open                                             |                         
    |   |---------------------+--------------------------------------------------|                         
    |   | Incompatible Change | major release (X.0)                              |                         
    |   |---------------------+--------------------------------------------------|                         
    |   | ARC review of Specs | Yes                                              |                         
    |   |---------------------+--------------------------------------------------|                         
    |   | Examples            | Compiler command line options,                   |
    |   |                     | hardware  (SBus, PCI, USB), RPC, POSIX utilities |                         
    +----------------------------------------------------------------------------+                         
    

We publish the specification of these interfaces, typically as manual pages or other product documentation. We also tell customers we will remain compatible with them. (Scott McNealy's principle that "Compatibility is a constraint, not a goal") The intention of a Committed interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all releases of the product after the one in which the interface was introduced, and within the same Major release. Even at a Major release, incompatible changes are expected to be rare, and to have strong justifications.

Committed interfaces are often proposed to be industry standards, as was the case with RPC. Also, interfaces defined and controlled as industry standards are most often treated as Committed interfaces.

These are interfaces whose specification is often under the provider's control or which are specified by a clearly versioned document controlled by a well-defined organization. If the interface specification is not under the implementation provider's control, the provider must be willing to fork from the interface specification if required to maintain compatibility. In the case of interface specifications controlled by a standards body, the commitment must be to a clearly identified version of the specification, minimizing the likelihood of an incompatible change (but it can happen through formal spec interpretations).

Also, if the interface specification is not under the control of the interface implementation provider, then the controlling body and/or public, versioned document must be be noted in the documentation. This is particularly important for specifications controlled by recognized standards organizations.

Although a truely exceptional event, incompatible changes are possible in any release if the associated defect is serious enough as outlined in the EXEMPTIONS section of this document or in a Minor release by following the End of Feature process.

UNCOMMITTED

public static final Stability UNCOMMITTED

    +--------------------------------------------------------------------------+                           
    | Uncommitted (formerly Unstable)                                          |
    |--------------------------------------------------------------------------|                           
    |   | Specification       | Open                                           |                           
    |   |---------------------+------------------------------------------------|                           
    |   | Incompatible Change | minor release (x.Y) with impact assessment     |                           
    |   |---------------------+------------------------------------------------|                           
    |   | ARC review of Specs | Yes                                            |                           
    |   |---------------------+------------------------------------------------|                           
    |   | Examples            | SUNW* package abbreviations, some config utils |                           
    +--------------------------------------------------------------------------+                           
    

No guarantees are made about either source or binary compatibility of these interfaces from one Minor release to the next. The most drastic incompatible change of removal of the interface in a Minor release is allowed. Uncommitted interfaces are generally not appropriate for use by release-independent products.

Uncommitted is not a license for gratuitous change. Any incompatible changes to the interface should be motivated by true improvement to the interface which may include justifiable ease of use considerations. The general expectation is that Uncommitted interfaces are not likely to change incompatibly and if such changes occur they will be small in impact and should often have a mitigation plan.

Uncommitted interfaces generally fall into one of the following subcategories:

• Interfaces that are experimental or transitional. They are typically used to give outside developers early access to new or rapidly-changing technology, or to provide an interim solution to a problem where a more general solution is anticipated.
• Interfaces whose specification is controlled by an outside body and the implementation provider is only willing to commit to forking until the next minor release point should that outside body introduce incompatible change. Note that this "middle of the road" approach is often the best business decision when the controlling body hasn't established a history of respecting compatibility.
• Interfaces whose target audience values innovation (and possibly ease of use) over stability. This attribute is often asserted for administrative interfaces for higher web tier components. Note that ARC review may request data to support such an assertion.

A project's intention to import an Uncommitted interface from another consolidation should be discussed with the ARC early. The stability classification of the interface -- or a replacement interface -- might be raised. The opinion allowing any project to import an Uncommitted interface must explain why it is acceptable, and a contract must be put into place allowing this use. For Sun products, the similarity in the usage of Uncommitted and Consolidation Private interfaces should be noted.

Any documentation for an Uncommitted interface must contain warnings that "these interfaces are subject to change without warning and should not be used in unbundled products". In some situations, it may be appropriate to document Uncommitted interfaces in white papers rather than in standard product documentation. When changes are introduced, the changes should be mentioned in the release notes for the affected release.

NOTE: If we choose to offer a draft standard implementation but state our intention to track the standard (or the portions we find technically sound or likely to be standardized), we set customer expectations for incompatible changes by classifying the interface Uncommitted. The interface must be reclassified Committed when standard is final. Such an intention could be encoded "Uncommitted->Committed".)

VOLATILE

public static final Stability VOLATILE

    +--------------------------------------------------------------------+                                 
    | Volatile (encompasses External)                                    |                                 
    |--------------------------------------------------------------------|                                 
    |   | Specification       | Open                                     |                                 
    |   |---------------------+------------------------------------------|                                 
    |   | Incompatible Change | micro release (x.y.z) or patch release   |                                 
    |   |---------------------+------------------------------------------|                                 
    |   | Arc review of Specs | A precise reference is normally recorded |                                 
    |   |---------------------+------------------------------------------|                                 
    |   | Examples            | Gimp user interface, IETF internet-draft |                                 
    +--------------------------------------------------------------------+                                 

Volatile interfaces may change at any time and for any reason.

Use of the Volatile interface stability level allows interface providers to quickly track a fluid, rapidly evolving specification. In many cases, this is preferred to providing additional stability to the interface, as it may better meet the expectations of the consumer.

The most common application of this taxonomy level is to interfaces that are controlled by a body other than the final implementation provider, but unlike specifications controlled by standards bodies or communities we place trust in, it can not be asserted that an incompatible change to the interface specification would be exceedingly rare. In some cases it may not even be possible to clearly identify the controlling body. Although not prohibited by this taxonomy, the Volatile classification is not typically applied to interfaces where the specification is controlled by the implementation provider.

It should be noted that in some cases it will be preferable to apply a less fluid interface classification to an interface even if the controlling body is separate from the implementor. Use of the Uncommitted classification extends the stability commitment over micro/patch releases, allowing use of additional support models for software that depends upon these interfaces, at the potential cost of less frequent updates. Committed should be considered for required, core interfaces. If instability in the interface definition can't be reconciled with the requirement for stability, then alternate solutions should be considered.

This classification is typically used for free or open source software (FOSS), also referred to as community software, and similar models where it is deemed more important to track the community with minimal latency than to provide stability to our customers. When applying this classification level to community software, particular attention should be paid to the considerations presented in the preceding paragraph.

It also may be appropriate to apply the Volatile classification level to interfaces in the process of being defined by trusted or widely accepted organization. These are generically referred to as draft standards. An "IETF internet draft" is a well understood example of a specification under development.

There may also cases where Volatile is appropriate for experimental interfaces, but in most cases Uncommitted should be considered first.

Irrespective of the control of the specification, the Volatile classification must not be applied to "core" interfaces (those that must be used) for which no alternate (and more stable) interface exists. Volatile interfaces must also adhere to Sun internal standards in the following areas:

• Security, Authentication
• The existence of (perhaps vestigial) Manual Pages and conformance to Sun section numbering
• File System Semantics (Solaris examples: /usr may be read-only, /var is where all significant run-time growth occurs, ...)

All Volatile interfaces should be labeled as such in all associated documentation and the consequence of using such interfaces must be explained either as part of that documentation or by reference.

Shipping incompatible change in a patch should be strongly avoided. It is not strictly prohibited for the following two reasons:

• Since the patch provider may not be in explicit control of the changes to the upstream implementation, it cannot guarantee with reasonable assurance that an unidentified incompatibility is not present.
• A strong business case may exist for shipping a newer version as a patch if that newer version closes significant escalations.

In general, the intent of allowing change in a patch is to allow for change in Update Releases.

Sun products should consider Volatile interfaces as equivalent to Consolidation Private. A contract is required for use of these interfaces outside of the supplying consolidation.

Extreme care in the use of Volatile interfaces is required by layered or unbundled products. Layered products that depend upon Volatile interfaces must include as part of their review material how they intend to manage the dependency. It is not explicitly prohibited, but it is probable that unbundled or layered products that ship asynchronously from the Volatile interfaces upon which they depend will face nearly insurmountable difficulty in constructing a plan to manage such a dependency.

NOT_AN_INTERFACE

public static final Stability NOT_AN_INTERFACE

    +--------------------------------------------------------------------+                                 
    | Not-an-interface                                                   |
    |--------------------------------------------------------------------|                                 
    |   | Specification       | None                                     |
    |   |---------------------+------------------------------------------|                                 
    |   | Incompatible Change | micro release (x.y.z) or patch release   |                                 
    |   |---------------------+------------------------------------------|                                 
    |   | Arc review of Specs | None                                     |
    |   |---------------------+------------------------------------------|                                 
    |   | Examples            | CLI output, error text                   |
    +--------------------------------------------------------------------+                                 

In the course of reviewing or documenting interfaces, the situation often occurs that an attribute will be present which may be inferred to be an interface, but actually is not. A couple of common examples of this are output from CLIs intended only for human consumption and the exact layout of a GUI.

This classification is simply a convenience term to be used to clarify such situations where such confusion is identified as likely. Failure to apply this term to an attribute is no indication that said attribute is some form of interface. It only indicates that the potential for confusion was not identified.

PRIVATE

public static final Stability PRIVATE

See: http://opensolaris.org/os/community/arc/policies/interface-taxonomy/

Javadoc or other means should establish the nature of the private interface.

EXPERIMENTAL

public static final Stability EXPERIMENTAL

Not a formal term. Indicates that the interface, while visible, is experimental, and can be removed at any time.

UNSPECIFIED

public static final Stability UNSPECIFIED

Interrim classification; a real one should be chosen asap.

Field Detail

mName

private final java.lang.String mName

Method Detail

values

public static Stability[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (Stability c : Stability.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static Stability valueOf(java.lang.String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

java.lang.IllegalArgumentException - if this enum type has no constant with the specified name

java.lang.NullPointerException - if the argument is null

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Enum<Stability>