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