001    /*
002     * Copyright 2009-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2009-2015 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 methods which may be used to set
035     * values in the associated object using attributes read from an LDAP directory
036     * server.  It should only be used for methods in classes that contain the
037     * {@link LDAPObject} annotation type.  Those methods must not be static and
038     * must take a single argument, which is the value to set from the corresponding
039     * LDAP attribute, but they may have any access modifier (including
040     * {@code public}, {@code protected}, {@code private}, or no access modifier at
041     * all indicating package-level access).  The associated attribute must not be
042     * referenced by any other {@link LDAPField} or {@code LDAPSetter} annotations
043     * in the same class, and it may be referenced by at most one {@link LDAPGetter}
044     * annotation.
045     */
046    @Documented()
047    @Retention(RetentionPolicy.RUNTIME)
048    @Target(value={ElementType.METHOD})
049    public @interface LDAPSetter
050    {
051      /**
052       * Indicates whether attempts to initialize an object should fail if the LDAP
053       * attribute has a value that cannot be represented in the required argument
054       * type for the associated method.  If this is {@code true}, then an exception
055       * will be thrown in such instances.  If this is {@code false}, then the
056       * associated method will not be invoked, and attempts to modify the
057       * corresponding entry in the directory may cause the existing values to be
058       * lost.
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 argument for the associated
067       * method only accepts a single value.  If this is {@code true}, then an
068       * exception will be thrown in such instances.  If this is {@code false}, then
069       * only the first value returned will be used, and attempts to modify the
070       * corresponding entry in the directory may cause those additional values to
071       * be lost.
072       */
073      boolean failOnTooManyValues() default true;
074    
075    
076    
077      /**
078       * The class that provides the logic for encoding the value of this method to
079       * an LDAP attribute.
080       */
081      Class<? extends ObjectEncoder> encoderClass()
082           default DefaultObjectEncoder.class;
083    
084    
085    
086      /**
087       * The name of the attribute type in which the value of the associated method
088       * will be stored.  If this is not provided, then the method name must start
089       * with "set" and it will be assumed that the attribute name is the remainder
090       * of the method name.
091       */
092      String attribute() default "";
093    }