001/*
002 * Copyright 2009-2014 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2009-2014 UnboundID Corp.
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  boolean failOnInvalidValue() default true;
057
058
059
060  /**
061   * Indicates whether attempts to initialize an object should fail if the
062   * LDAP attribute has multiple values but the associated field can only hold a
063   * single value.  If this is {@code true}, then an exception will be thrown in
064   * such instances.  If this is {@code false}, then only the first value
065   * returned will be used, and attempts to modify the corresponding entry in
066   * the directory may cause those additional values to be lost.
067   */
068  boolean failOnTooManyValues() default true;
069
070
071
072  /**
073   * Indicates whether this field should be included in the LDAP entry that is
074   * generated when adding a new instance of the associated object to the
075   * directory.  Note that any field which is to be included in entry RDNs will
076   * always be included in add operations regardless of the value of this
077   * element.
078   */
079  boolean inAdd() default true;
080
081
082
083  /**
084   * Indicates whether this field should be examined and included in the set of
085   * LDAP modifications if it has been changed when modifying an existing
086   * instance of the associated object in the directory.  Note that any field
087   * which is to be included in entry RDNs will never be included in modify
088   * operations regardless of the value of this element.
089   */
090  boolean inModify() default true;
091
092
093
094  /**
095   * Indicates whether the value of this field should be included in the RDN of
096   * entries created from the associated object.  Any field which is to be
097   * included entry RDNs will be considered required for add operations
098   * regardless of the value of the {@link #requiredForEncode} element of this
099   * annotation type, and will be included in add operations regardless of the
100   * value of the {@link #inAdd} element.
101   */
102  boolean inRDN() default false;
103
104
105
106  /**
107   * Indicates whether this field should be lazily-loaded, which means that the
108   * associated attribute will not be retrieved by default so this field will
109   * be uninitialized.  This may be useful for attributes which are not always
110   * needed and that may be expensive to retrieve or could require a lot of
111   * memory to hold.  The contents of such fields may be loaded on demand if
112   * their values are needed.  Fields marked for lazy loading will never be
113   * considered required for decoding, and they must not be given default values
114   * or marked for inclusion in entry RDNs.
115   */
116  boolean lazilyLoad() default false;
117
118
119
120  /**
121   * Indicates whether this field is required to be assigned a value in decode
122   * processing.  If this is {@code true}, then attempts to initialize a Java
123   * object from an LDAP entry which does not contain a value for the associated
124   * attribute will result in an exception.
125   */
126  boolean requiredForDecode() default false;
127
128
129
130  /**
131   * Indicates whether this field is required to have a value for encode
132   * processing.  If this is {@code true}, then attempts to construct an entry
133   * or set of modifications for an object that does not have a value for this
134   * field will result in an exception.
135   */
136  boolean requiredForEncode() default false;
137
138
139
140  /**
141   * The class that provides the logic for encoding a field to an LDAP
142   * attribute, and for initializing a field from an LDAP attribute.
143   */
144  Class<? extends ObjectEncoder> encoderClass()
145       default DefaultObjectEncoder.class;
146
147
148
149  /**
150   * Indicates whether and under what circumstances the value of this field may
151   * be included in a search filter generated to search for entries that match
152   * the object.
153   */
154  FilterUsage filterUsage() default FilterUsage.CONDITIONALLY_ALLOWED;
155
156
157
158  /**
159   * The name of the attribute type in which the associated field will be stored
160   * in LDAP entries.  If no value is provided, then it will be assumed that the
161   * LDAP attribute name matches the name of the associated field.
162   */
163  String attribute() default "";
164
165
166
167  /**
168   * The string representation(s) of the default value(s) to assign to this
169   * field if there are no values for the associated attribute in the
170   * corresponding LDAP entry being used to initialize the object.  If no
171   * default values are defined, then an exception will be thrown if the field
172   * is {@link #requiredForEncode}, or the field will be set to {@code null} if
173   * it is not required.
174   */
175  String[] defaultDecodeValue() default {};
176
177
178
179  /**
180   * The string representation(s) of the default value to use when adding an
181   * entry to the directory if this field has a {@code null} value.
182   */
183  String[] defaultEncodeValue() default {};
184
185
186
187  /**
188   * The name(s) of the object class(es) in which the associated attribute may
189   * be used.  This is primarily intended for use in generating LDAP schema from
190   * Java object types.
191   * <BR><BR>
192   * Values may include any combination of the structural and/or auxiliary
193   * object classes named in the {@link LDAPObject} annotation type for the
194   * associated class.  If no values are provided, then it will be assumed to
195   * be only included in the structural object class.
196   */
197  String[] objectClass() default {};
198}