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    }