001/*
002 * Copyright 2009-2019 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2009-2019 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}