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