001/*
002 * Copyright 2009-2018 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2009-2018 Ping Identity Corporation
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 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})
049public @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   * @return  {@code true} if attempts to initialize an object should fail if
061   *          the LDAP attribute has a value that cannot be represented in the
062   *          required argument type, or {@code false} if not.
063   */
064  boolean failOnInvalidValue() default true;
065
066
067
068  /**
069   * Indicates whether attempts to initialize an object should fail if the
070   * LDAP attribute has multiple values but the argument for the associated
071   * method only accepts a single value.  If this is {@code true}, then an
072   * exception will be thrown in such instances.  If this is {@code false}, then
073   * only the first value returned will be used, and attempts to modify the
074   * corresponding entry in the directory may cause those additional values to
075   * be lost.
076   *
077   * @return  {@code true} if attempts to initialize an object should fail if
078   *          the LDAP attribute has multiple values but the argument for the
079   *          associated method only accepts a single value, or {@code false} if
080   *          not.
081   */
082  boolean failOnTooManyValues() default true;
083
084
085
086  /**
087   * The class that provides the logic for encoding the value of this method to
088   * an LDAP attribute.
089   *
090   * @return  The encoder class for this method.
091   */
092  Class<? extends ObjectEncoder> encoderClass()
093       default DefaultObjectEncoder.class;
094
095
096
097  /**
098   * The name of the attribute type in which the value of the associated method
099   * will be stored.  If this is not provided, then the method name must start
100   * with "set" and it will be assumed that the attribute name is the remainder
101   * of the method name.
102   *
103   * @return  The name of the attribute type in which the value of the
104   *          associated method will be stored, or an empty string if the
105   *          attribute name will be assumed to match the method name minus the
106   *          initial "set".
107   */
108  String attribute() default "";
109}