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 2012-2015 ForgeRock AS 026 */ 027package org.opends.server.types; 028 029 030 031 032 033import java.lang.annotation.Documented; 034import java.lang.annotation.ElementType; 035import java.lang.annotation.Retention; 036import java.lang.annotation.RetentionPolicy; 037import java.lang.annotation.Target; 038 039 040 041/** 042 * This class defines an annotation type that can be used to describe 043 * the position of a package, class, or method in the OpenDS public 044 * API (including to denote that the associated code should NOT be 045 * considered part of the public API). Third-party developers should 046 * pay attention to these annotations in order to understand how best 047 * to interact with the OpenDS code. For the purposes of this 048 * annotation, a "third-party developer" should be assumed to refer to 049 * anyone who is interacting with the OpenDS code in a manner in which 050 * their work is not expected to become part of the core OpenDS code 051 * base. 052 * <BR><BR> 053 * This annotation type may be used to describe things like: 054 * <UL> 055 * <LI>The stability of the code (how likely it is to change in the 056 * future and whether those changes may be incompatible with 057 * previous implementations).</LI> 058 * <LI>Whether third-party code may be allowed to create new 059 * instances of the associated object type.</LI> 060 * <LI>Whether a class or method may be extended by third-party 061 * code.</LI> 062 * <LI>Whether a class or method may be invoked by third-party 063 * code.</LI> 064 * </UL> 065 * <BR><BR> 066 * Note that for cases in which there are conflicting public API 067 * annotations, the most specific annotation should be considered 068 * authoritative. For example, if a class is marked with 069 * {@code mayInvoke=true} but a method in that class is marked with 070 * {@code mayInvoke=false}, then third-party code should not attempt 071 * to invoke that method because the method-level annotation is more 072 * specific (and therefore overrides) the less-specific class-level 073 * annotation. 074 * <BR><BR> 075 * If a method does not include this annotation, then it should be 076 * assumed to inherit the class-level annotation. If a class does not 077 * include this annotation, then it should be assumed to inherit the 078 * package-level annotation. If a package does not include this 079 * annotation, then it should be assumed the package is private and 080 * should not be used by third-party code. 081 */ 082@Documented 083@Retention(RetentionPolicy.RUNTIME) 084@Target({ ElementType.PACKAGE, 085 ElementType.TYPE, 086 ElementType.METHOD, 087 ElementType.CONSTRUCTOR }) 088public @interface PublicAPI 089{ 090 /** 091 * Retrieves the stability level for the associated class or method. 092 * 093 * return The stability level for the associated class or method. 094 */ 095 StabilityLevel stability() default StabilityLevel.PRIVATE; 096 097 098 099 /** 100 * Indicates whether third-party code should be allowed to directly 101 * create new instances of the associated object type by calling the 102 * constructor or a static factory method defined in that class. 103 * Note that even in cases where third-party code should not 104 * instantiate a given object type, it may be permissible for 105 * third-party code to invoke methods on instances of that object 106 * obtained elsewhere (e.g., provided as an argument to a method 107 * overridden by the third-party code). 108 * 109 * return {@code true} if third-party code should be allowed to 110 * create new instances of the associated object type, or 111 * {@code false} if not. 112 */ 113 boolean mayInstantiate() default false; 114 115 116 117 /** 118 * Indicates whether the associated class/interface/method may be 119 * extended/implemented/overridden by third-party code. In some 120 * cases, the OpenDS code may define an abstract class, interface, 121 * or non-final method that is intended only for internal use and 122 * may be extended by internal code but should not be extended by 123 * classes outside the OpenDS code base. 124 * 125 * return {@code true} if the associated class/interface/method 126 * may be extended by third-party code, or {@code false} if 127 * not. 128 */ 129 boolean mayExtend() default false; 130 131 132 133 /** 134 * Indicates whether the associated method may be invoked by 135 * third-party code. 136 * 137 * return {@code true} if third-party code should be allowed to 138 * invoke the associated method, or {@code false} if not. 139 */ 140 boolean mayInvoke() default false; 141 142 143 144 /** 145 * Retrieves a string that may contain additional notes that should 146 * be taken into consideration by third-party developers that may be 147 * interested in using the associated code. 148 * 149 * return A string that may contain additional notes that should 150 * be taken into consideration by third-party developers 151 * that may be interested in using the associated code. 152 */ 153 String notes() default ""; 154} 155