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