001/* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt 010 * or http://forgerock.org/license/CDDLv1.0.html. 011 * See the License for the specific language governing permissions 012 * and limitations under the License. 013 * 014 * When distributing Covered Code, include this CDDL HEADER in each 015 * file and include the License file at legal-notices/CDDLv1_0.txt. 016 * If applicable, add the following below this CDDL HEADER, with the 017 * fields enclosed by brackets "[]" replaced with your own identifying 018 * information: 019 * Portions Copyright [yyyy] [name of copyright owner] 020 * 021 * CDDL HEADER END 022 * 023 * 024 * Copyright 2008 Sun Microsystems, Inc. 025 * Portions Copyright 2014 ForgeRock AS 026 */ 027package org.opends.server.types; 028 029 030 031 032 033/** 034 * This class implements an enumeration whose values may be used to 035 * indicate the stability level of API classes and/or methods. Code 036 * which is part of the OpenDS public API should be marked with a 037 * {@code COMMITTED}, {@code UNCOMMITTED}, {@code VOLAITLE}, or 038 * {@code OBSOLETE} stability level in order to indicate the relative 039 * likelihood that the associated interface will be changed in an 040 * incompatible way in the future. 041 * <BR><BR> 042 * Third-party developers are free to create code that introduces 043 * dependencies on OpenDS APIs that are marked {@code COMMITTED}, 044 * {@code UNCOMMITTED}, or {@code VOLATILE}, with an understanding 045 * that the less stable an OpenDS API is, the more likely that 046 * third-party code which relies upon it may need to be altered in 047 * order to work properly with future versions. 048 * <BR><BR> 049 * Changes to the stability level of a class or package should only be 050 * made between major releases and must be denoted in the release 051 * notes for all releases with that major version. If a public API 052 * element that is marked {@code COMMITTED}, {@code UNCOMMITTED}, or 053 * {@code VOLATILE} is to be made private, it is strongly recommended 054 * that it first be transitioned to {@code OBSOLETE} before ultimately 055 * being marked {@code PRIVATE}. 056 * <BR><BR> 057 * New packages and classes introduced into the OpenDS code base may 058 * be assigned any stability level. New methods introduced into 059 * existing classes that are part of the public API may be created 060 * with any stability level as long as the introduction of that method 061 * is compliant with the stability level of the class. If a method 062 * that is part of the OpenDS public API is not marked with an 063 * explicit stability level, then it should be assumed that it has the 064 * same stability level as the class that contains it. 065 */ 066@org.opends.server.types.PublicAPI( 067 stability=org.opends.server.types.StabilityLevel.UNCOMMITTED, 068 mayInstantiate=false, 069 mayExtend=false, 070 mayInvoke=true) 071public enum StabilityLevel 072{ 073 /** 074 * The associated package, class, or method may be made available 075 * for third-party use, and the APIs that it exposes should be 076 * considered stable. Incompatible changes may only be introduced 077 * between major versions, and even then such changes should be 078 * considered very rare and will require strong justification and 079 * be explicitly denoted in the release notes for all releases with 080 * that major version. 081 * <BR><BR> 082 * Note that interface changes may be allowed between non-major 083 * releases if they do not impact backward compatibility. 084 */ 085 COMMITTED, 086 087 088 089 /** 090 * The associated package, class, or method may be made available 091 * for third-party use, and the APIs that it exposes may be 092 * considered moderately stable. Incompatible changes may be 093 * introduced between major and/or minor versions, but only with 094 * strong justification and explicit denotation in the release notes 095 * for all subsequent releases with that major version. 096 * <BR><BR> 097 * Note that interface changes may be allowed between non-major and 098 * non-minor releases if they do not impact backward compatibility. 099 */ 100 UNCOMMITTED, 101 102 103 104 /** 105 * The associated package, class, or method may be made available 106 * for third-party use, but the APIs that it exposes should not be 107 * considered stable. Incompatible changes may be introduced 108 * between major, minor, and point versions, and may also be 109 * introduced in patches or hotfixes. Any incompatible interface 110 * changes should be denoted in the release notes for all subsequent 111 * releases with that major version. 112 * <BR><BR> 113 * Note that if it is believed that a given class or interface will 114 * likely have incompatible changes in the future, then it should be 115 * declared with a stability level of {@code VOLATILE}, even if that 116 * those incompatible changes are expected to occur between major 117 * releases. 118 */ 119 VOLATILE, 120 121 122 123 /** 124 * The associated package, class, or method should be considered 125 * obsolete, and no new code should be created that depends on it. 126 * The associated code may be removed in future versions without any 127 * additional prior notice. 128 */ 129 OBSOLETE, 130 131 132 133 /** 134 * The associated package, class, or method should be considered 135 * part of the OpenDS private API and should not be used by 136 * third-party code. No prior notice is required for incompatible 137 * changes to code with a {@code PRIVATE} classification. 138 */ 139 PRIVATE; 140} 141