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 whose return values should
035 * be persisted in an LDAP directory server.  It should only be used for methods
036 * in classes that contain the {@link LDAPObject} annotation type.  Those
037 * methods must not be static and must have a non-{@code void} return type, but
038 * they may have any access modifier (including {@code public},
039 * {@code protected}, {@code private}, or no access modifier at all indicating
040 * package-level access).  The associated attribute must not be referenced by
041 * any other {@link LDAPField} or {@code LDAPGetter} annotations in the same
042 * class, and it may be referenced by at most one {@link LDAPSetter} annotation.
043 */
044@Documented()
045@Retention(RetentionPolicy.RUNTIME)
046@Target(value={ElementType.METHOD})
047public @interface LDAPGetter
048{
049  /**
050   * Indicates whether the value returned from this method should be included in
051   * the LDAP entry that is generated when adding a new instance of the
052   * associated object to the directory.  Note that any getter value which is
053   * to be included in entry RDNs will always be included in add operations
054   * regardless of the value of this element.
055   *
056   * @return  {@code true} if the value returned from this method should be
057   *          included in the LDAP entry that is generated when adding a new
058   *          instance of the associated object to the directory, or
059   *          {@code false} if not.
060   */
061  boolean inAdd() default true;
062
063
064
065  /**
066   * Indicates whether the value returned from this method should be included in
067   * the set of LDAP modifications if it has been changed when modifying an
068   * existing instance of the associated object in the directory.  Note that any
069   * getter value which is to be included in entry RDNs will never be included
070   * in modify operations regardless of the value of this element.
071   *
072   * @return  {@code true} if the value returned from this method should be
073   *          included in the set of LDAP modifications if it has been changed
074   *          when modifying an existing instance of the associated object in
075   *          the directory, or {@code false} if not.
076   */
077  boolean inModify() default true;
078
079
080
081  /**
082   * Indicates whether the value returned from this method should be included in
083   * the RDN of entries created from the associated object.  Any getter value
084   * which is to be included entry RDNs will always be included in add
085   * operations regardless of the value of the {@link #inAdd} element.
086   * <BR><BR>
087   * When generating an entry DN, the persistence framework will construct an
088   * RDN using all fields marked with {@code LDAPField} that have
089   * {@code inRDN=true} and all getter methods marked with {@code LDAPGetter}
090   * that have {@code inRDN=true}.  A class marked with {@code LDAPObject} must
091   * either have at least one {@code LDAPField} or {@code LDAPGetter} with
092   * {@code inRDN=true}, or it must be a direct subclass of another class marked
093   * with {@code LDAPObject}.  If a class has one or more fields and/or getters
094   * with {@code inRDN=true}, then only those fields/getters will be used to
095   * construct the RDN, even if that class is a direct subclass of another class
096   * marked with {@code LDAPObject}.
097   *
098   * @return  {@code true} if the value returned from this method should be
099   *          included in the RDN of entries created from the associated
100   *          object, or {@code false} if not.
101   */
102  boolean inRDN() default false;
103
104
105
106  /**
107   * The class that provides the logic for encoding the method return value to
108   * an LDAP attribute.
109   *
110   * @return  The encoder class for this getter.
111   */
112  Class<? extends ObjectEncoder> encoderClass()
113       default DefaultObjectEncoder.class;
114
115
116
117  /**
118   * Indicates whether and under what circumstances the value returned from this
119   * method may be included in a search filter generated to search for entries
120   * that match the object.
121   *
122   * @return  The filter usage value for this getter.
123   */
124  FilterUsage filterUsage() default FilterUsage.CONDITIONALLY_ALLOWED;
125
126
127
128  /**
129   * The name of the attribute type in which the associated getter value will be
130   * stored in LDAP entries.  If this is not provided, then the method name must
131   * start with "get" and it will be assumed that the attribute name is the
132   * remainder of the method name.
133   *
134   * @return  The name of the attribute type in which the associated getter
135   *          value will be stored in LDAP entries, or an empty string if it
136   *          will be assumed that the attribute name matches the getter method
137   *          name without the initial "get".
138   */
139  String attribute() default "";
140
141
142
143  /**
144   * The names of the object classes in which the associated attribute may
145   * be used.  This is primarily intended for use in generating LDAP schema from
146   * Java object types.
147   * <BR><BR>
148   * Values may include any combination of the structural and/or auxiliary
149   * object classes named in the {@link LDAPObject} annotation type for the
150   * associated class.  If no values are provided, then it will be assumed to
151   * be only included in the structural object class.
152   *
153   * @return  The names of the object classes in which the associated attribute
154   *          may be used, or an empty array if it will be assumed to only be
155   *          included in the structural object class.
156   */
157  String[] objectClass() default {};
158}