001/* 002 * Copyright 2009-2018 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2009-2018 Ping Identity Corporation 007 * 008 * This program is free software; you can redistribute it and/or modify 009 * it under the terms of the GNU General Public License (GPLv2 only) 010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 011 * as published by the Free Software Foundation. 012 * 013 * This program is distributed in the hope that it will be useful, 014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 016 * GNU General Public License for more details. 017 * 018 * You should have received a copy of the GNU General Public License 019 * along with this program; if not, see <http://www.gnu.org/licenses>. 020 */ 021package com.unboundid.ldap.sdk.persist; 022 023 024 025import java.lang.annotation.ElementType; 026import java.lang.annotation.Documented; 027import java.lang.annotation.Retention; 028import java.lang.annotation.RetentionPolicy; 029import java.lang.annotation.Target; 030 031 032 033/** 034 * This annotation type may be used to mark fields whose values should be 035 * persisted in an LDAP directory server. It should only be used for fields in 036 * classes that contain the {@link LDAPObject} annotation type. Fields marked 037 * with this annotation type must be non-final and non-static, but they may have 038 * any access modifier (including {@code public}, {@code protected}, 039 * {@code private}, or no access modifier at all indicating package-level 040 * access). The associated attribute must not be referenced by any other 041 * {@code LDAPField} annotation types. 042 */ 043@Documented() 044@Retention(RetentionPolicy.RUNTIME) 045@Target(value={ElementType.FIELD}) 046public @interface LDAPField 047{ 048 /** 049 * Indicates whether attempts to initialize an object should fail if the LDAP 050 * attribute has a value that cannot be stored in the associated field. If 051 * this is {@code true}, then an exception will be thrown in such instances. 052 * If this is {@code false}, then the field will remain uninitialized, and 053 * attempts to modify the corresponding entry in the directory may cause the 054 * existing values to be lost. 055 * 056 * @return {@code true} if attempts to initialize an object should fail if 057 * the LDAP attribute has a value that cannot be stored in the 058 * associated field, or {@code false} if not. 059 */ 060 boolean failOnInvalidValue() default true; 061 062 063 064 /** 065 * Indicates whether attempts to initialize an object should fail if the 066 * LDAP attribute has multiple values but the associated field can only hold a 067 * single value. If this is {@code true}, then an exception will be thrown in 068 * such instances. If this is {@code false}, then only the first value 069 * returned will be used, and attempts to modify the corresponding entry in 070 * the directory may cause those additional values to be lost. 071 * 072 * @return {@code true} if attempts to initialize an object should fail if 073 * the LDAP attribute has multiple values but the associated field 074 * can only hold a single value, or {@code false} if not. 075 */ 076 boolean failOnTooManyValues() default true; 077 078 079 080 /** 081 * Indicates whether this field should be included in the LDAP entry that is 082 * generated when adding a new instance of the associated object to the 083 * directory. Note that any field which is to be included in entry RDNs will 084 * always be included in add operations regardless of the value of this 085 * element. 086 * 087 * @return {@code true} if this field should be included in the LDAP entry 088 * that is generated when adding a new instance of the associated 089 * object to the directory, or {@code false} if not. 090 */ 091 boolean inAdd() default true; 092 093 094 095 /** 096 * Indicates whether this field should be examined and included in the set of 097 * LDAP modifications if it has been changed when modifying an existing 098 * instance of the associated object in the directory. Note that any field 099 * which is to be included in entry RDNs will never be included in modify 100 * operations regardless of the value of this element. 101 * 102 * @return {@code true} if this field should be examined and included in the 103 * set of LDAP modifications if it has been changed, or {@code false} 104 * if not. 105 */ 106 boolean inModify() default true; 107 108 109 110 /** 111 * Indicates whether the value of this field should be included in the RDN of 112 * entries created from the associated object. Any field which is to be 113 * included entry RDNs will be considered required for add operations 114 * regardless of the value of the {@link #requiredForEncode} element of this 115 * annotation type, and will be included in add operations regardless of the 116 * value of the {@link #inAdd} element. 117 * <BR><BR> 118 * When generating an entry DN, the persistence framework will construct an 119 * RDN using all fields marked with {@code LDAPField} that have 120 * {@code inRDN=true} and all getter methods marked with {@code LDAPGetter} 121 * that have {@code inRDN=true}. A class marked with {@code LDAPObject} must 122 * either have at least one {@code LDAPField} or {@code LDAPGetter} with 123 * {@code inRDN=true}, or it must be a direct subclass of another class marked 124 * with {@code LDAPObject}. If a class has one or more fields and/or getters 125 * with {@code inRDN=true}, then only those fields/getters will be used to 126 * construct the RDN, even if that class is a direct subclass of another class 127 * marked with {@code LDAPObject}. 128 * 129 * @return {@code true} if the value of this field should be included in the 130 * RDN of entries created from the associated object, or 131 * {@code false} if not. 132 */ 133 boolean inRDN() default false; 134 135 136 137 /** 138 * Indicates whether this field should be lazily loaded, which means that the 139 * associated attribute will not be retrieved by default so this field will 140 * be uninitialized. This may be useful for attributes which are not always 141 * needed and that may be expensive to retrieve or could require a lot of 142 * memory to hold. The contents of such fields may be loaded on demand if 143 * their values are needed. Fields marked for lazy loading will never be 144 * considered required for decoding, and they must not be given default values 145 * or marked for inclusion in entry RDNs. 146 * 147 * @return {@code true} if this field should be lazily loaded, or 148 * {@code false} if not. 149 */ 150 boolean lazilyLoad() default false; 151 152 153 154 /** 155 * Indicates whether this field is required to be assigned a value in decode 156 * processing. If this is {@code true}, then attempts to initialize a Java 157 * object from an LDAP entry which does not contain a value for the associated 158 * attribute will result in an exception. 159 * 160 * @return {@code true} if this field is required to be assigned a value in 161 * decode processing, or {@code false} if not. 162 */ 163 boolean requiredForDecode() default false; 164 165 166 167 /** 168 * Indicates whether this field is required to have a value for encode 169 * processing. If this is {@code true}, then attempts to construct an entry 170 * or set of modifications for an object that does not have a value for this 171 * field will result in an exception. 172 * 173 * @return {@code true} if this field is required to have a value for encode 174 * processing, or {@code false} if not. 175 */ 176 boolean requiredForEncode() default false; 177 178 179 180 /** 181 * The class that provides the logic for encoding a field to an LDAP 182 * attribute, and for initializing a field from an LDAP attribute. 183 * 184 * @return The encoder class for the field. 185 */ 186 Class<? extends ObjectEncoder> encoderClass() 187 default DefaultObjectEncoder.class; 188 189 190 191 /** 192 * Indicates whether and under what circumstances the value of this field may 193 * be included in a search filter generated to search for entries that match 194 * the object. 195 * 196 * @return The filter usage value for this field. 197 */ 198 FilterUsage filterUsage() default FilterUsage.CONDITIONALLY_ALLOWED; 199 200 201 202 /** 203 * The name of the attribute type in which the associated field will be stored 204 * in LDAP entries. If no value is provided, then it will be assumed that the 205 * LDAP attribute name matches the name of the associated field. 206 * 207 * @return The name of the attribute type in which the associated field will 208 * be stored in LDAP entries, or an empty string if the attribute 209 * name should match the name of the associated field. 210 */ 211 String attribute() default ""; 212 213 214 215 /** 216 * The string representations of the default values to assign to this 217 * field if there are no values for the associated attribute in the 218 * corresponding LDAP entry being used to initialize the object. If no 219 * default values are defined, then an exception will be thrown if the field 220 * is {@link #requiredForEncode}, or the field will be set to {@code null} if 221 * it is not required. 222 * 223 * @return The string representations of the default values to assign to this 224 * field if there are no values for the associated attribute in the 225 * corresponding LDAP entry, or an empty array if there should not be 226 * any default values. 227 */ 228 String[] defaultDecodeValue() default {}; 229 230 231 232 /** 233 * The string representations of the default values to use when adding an 234 * entry to the directory if this field has a {@code null} value. 235 * 236 * @return The string representations of the default values to use when 237 * adding an entry to the directory if this field has a {@code null} 238 * value, or an empty array if there should not be any default 239 * values. 240 */ 241 String[] defaultEncodeValue() default {}; 242 243 244 245 /** 246 * The names of the object classes in which the associated attribute may be 247 * used. This is primarily intended for use in generating LDAP schema from 248 * Java object types. 249 * <BR><BR> 250 * Values may include any combination of the structural and/or auxiliary 251 * object classes named in the {@link LDAPObject} annotation type for the 252 * associated class. If no values are provided, then it will be assumed to 253 * be only included in the structural object class. 254 * 255 * @return The names of the object classes in which the associated attribute 256 * may be used, or an empty array if it should be assumed to only be 257 * included in the structural object class. 258 */ 259 String[] objectClass() default {}; 260}