001 /*
002 * Copyright 2009-2016 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2009-2016 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 */
021 package com.unboundid.ldap.sdk.persist;
022
023
024
025 import java.lang.annotation.ElementType;
026 import java.lang.annotation.Documented;
027 import java.lang.annotation.Retention;
028 import java.lang.annotation.RetentionPolicy;
029 import 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})
046 public @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 * <BR><BR>
102 * When generating an entry DN, the persistence framework will construct an
103 * RDN using all fields marked with {@code LDAPField} that have
104 * {@code inRDN=true} and all getter methods marked with {@code LDAPGetter}
105 * that have {@code inRDN=true}. A class marked with {@code LDAPObject} must
106 * either have at least one {@code LDAPField} or {@code LDAPGetter} with
107 * {@code inRDN=true}, or it must be a direct subclass of another class marked
108 * with {@code LDAPObject}. If a class has one or more fields and/or getters
109 * with {@code inRDN=true}, then only those fields/getters will be used to
110 * construct the RDN, even if that class is a direct subclass of another class
111 * marked with {@code LDAPObject}.
112 */
113 boolean inRDN() default false;
114
115
116
117 /**
118 * Indicates whether this field should be lazily-loaded, which means that the
119 * associated attribute will not be retrieved by default so this field will
120 * be uninitialized. This may be useful for attributes which are not always
121 * needed and that may be expensive to retrieve or could require a lot of
122 * memory to hold. The contents of such fields may be loaded on demand if
123 * their values are needed. Fields marked for lazy loading will never be
124 * considered required for decoding, and they must not be given default values
125 * or marked for inclusion in entry RDNs.
126 */
127 boolean lazilyLoad() default false;
128
129
130
131 /**
132 * Indicates whether this field is required to be assigned a value in decode
133 * processing. If this is {@code true}, then attempts to initialize a Java
134 * object from an LDAP entry which does not contain a value for the associated
135 * attribute will result in an exception.
136 */
137 boolean requiredForDecode() default false;
138
139
140
141 /**
142 * Indicates whether this field is required to have a value for encode
143 * processing. If this is {@code true}, then attempts to construct an entry
144 * or set of modifications for an object that does not have a value for this
145 * field will result in an exception.
146 */
147 boolean requiredForEncode() default false;
148
149
150
151 /**
152 * The class that provides the logic for encoding a field to an LDAP
153 * attribute, and for initializing a field from an LDAP attribute.
154 */
155 Class<? extends ObjectEncoder> encoderClass()
156 default DefaultObjectEncoder.class;
157
158
159
160 /**
161 * Indicates whether and under what circumstances the value of this field may
162 * be included in a search filter generated to search for entries that match
163 * the object.
164 */
165 FilterUsage filterUsage() default FilterUsage.CONDITIONALLY_ALLOWED;
166
167
168
169 /**
170 * The name of the attribute type in which the associated field will be stored
171 * in LDAP entries. If no value is provided, then it will be assumed that the
172 * LDAP attribute name matches the name of the associated field.
173 */
174 String attribute() default "";
175
176
177
178 /**
179 * The string representation(s) of the default value(s) to assign to this
180 * field if there are no values for the associated attribute in the
181 * corresponding LDAP entry being used to initialize the object. If no
182 * default values are defined, then an exception will be thrown if the field
183 * is {@link #requiredForEncode}, or the field will be set to {@code null} if
184 * it is not required.
185 */
186 String[] defaultDecodeValue() default {};
187
188
189
190 /**
191 * The string representation(s) of the default value to use when adding an
192 * entry to the directory if this field has a {@code null} value.
193 */
194 String[] defaultEncodeValue() default {};
195
196
197
198 /**
199 * The name(s) of the object class(es) in which the associated attribute may
200 * be used. This is primarily intended for use in generating LDAP schema from
201 * Java object types.
202 * <BR><BR>
203 * Values may include any combination of the structural and/or auxiliary
204 * object classes named in the {@link LDAPObject} annotation type for the
205 * associated class. If no values are provided, then it will be assumed to
206 * be only included in the structural object class.
207 */
208 String[] objectClass() default {};
209 }