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