001/*
002 * Copyright 2009-2024 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2009-2024 Ping Identity Corporation
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *    http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020/*
021 * Copyright (C) 2009-2024 Ping Identity Corporation
022 *
023 * This program is free software; you can redistribute it and/or modify
024 * it under the terms of the GNU General Public License (GPLv2 only)
025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
026 * as published by the Free Software Foundation.
027 *
028 * This program is distributed in the hope that it will be useful,
029 * but WITHOUT ANY WARRANTY; without even the implied warranty of
030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
031 * GNU General Public License for more details.
032 *
033 * You should have received a copy of the GNU General Public License
034 * along with this program; if not, see <http://www.gnu.org/licenses>.
035 */
036package com.unboundid.ldap.sdk.persist;
037
038
039
040import java.lang.annotation.ElementType;
041import java.lang.annotation.Documented;
042import java.lang.annotation.Retention;
043import java.lang.annotation.RetentionPolicy;
044import java.lang.annotation.Target;
045
046import com.unboundid.util.NotNull;
047
048
049
050/**
051 * This annotation type may be used to mark methods whose return values should
052 * be persisted in an LDAP directory server.  It should only be used for methods
053 * in classes that contain the {@link LDAPObject} annotation type.  Those
054 * methods must not be static and must have a non-{@code void} return type, but
055 * they may have any access modifier (including {@code public},
056 * {@code protected}, {@code private}, or no access modifier at all indicating
057 * package-level access).  The associated attribute must not be referenced by
058 * any other {@link LDAPField} or {@code LDAPGetter} annotations in the same
059 * class, and it may be referenced by at most one {@link LDAPSetter} annotation.
060 */
061@Documented()
062@Retention(RetentionPolicy.RUNTIME)
063@Target(value={ElementType.METHOD})
064public @interface LDAPGetter
065{
066  /**
067   * Indicates whether the value returned from this method should be included in
068   * the LDAP entry that is generated when adding a new instance of the
069   * associated object to the directory.  Note that any getter value which is
070   * to be included in entry RDNs will always be included in add operations
071   * regardless of the value of this element.
072   *
073   * @return  {@code true} if the value returned from this method should be
074   *          included in the LDAP entry that is generated when adding a new
075   *          instance of the associated object to the directory, or
076   *          {@code false} if not.
077   */
078  boolean inAdd() default true;
079
080
081
082  /**
083   * Indicates whether the value returned from this method should be included in
084   * the set of LDAP modifications if it has been changed when modifying an
085   * existing instance of the associated object in the directory.  Note that any
086   * getter value which is to be included in entry RDNs will never be included
087   * in modify operations regardless of the value of this element.
088   *
089   * @return  {@code true} if the value returned from this method should be
090   *          included in the set of LDAP modifications if it has been changed
091   *          when modifying an existing instance of the associated object in
092   *          the directory, or {@code false} if not.
093   */
094  boolean inModify() default true;
095
096
097
098  /**
099   * Indicates whether the value returned from this method should be included in
100   * the RDN of entries created from the associated object.  Any getter value
101   * which is to be included entry RDNs will always be included in add
102   * operations regardless of the value of the {@link #inAdd} element.
103   * <BR><BR>
104   * When generating an entry DN, the persistence framework will construct an
105   * RDN using all fields marked with {@code LDAPField} that have
106   * {@code inRDN=true} and all getter methods marked with {@code LDAPGetter}
107   * that have {@code inRDN=true}.  A class marked with {@code LDAPObject} must
108   * either have at least one {@code LDAPField} or {@code LDAPGetter} with
109   * {@code inRDN=true}, or it must be a direct subclass of another class marked
110   * with {@code LDAPObject}.  If a class has one or more fields and/or getters
111   * with {@code inRDN=true}, then only those fields/getters will be used to
112   * construct the RDN, even if that class is a direct subclass of another class
113   * marked with {@code LDAPObject}.
114   *
115   * @return  {@code true} if the value returned from this method should be
116   *          included in the RDN of entries created from the associated
117   *          object, or {@code false} if not.
118   */
119  boolean inRDN() default false;
120
121
122
123  /**
124   * The class that provides the logic for encoding the method return value to
125   * an LDAP attribute.
126   *
127   * @return  The encoder class for this getter.
128   */
129  @NotNull Class<? extends ObjectEncoder> encoderClass()
130       default DefaultObjectEncoder.class;
131
132
133
134  /**
135   * Indicates whether and under what circumstances the value returned from this
136   * method may be included in a search filter generated to search for entries
137   * that match the object.
138   *
139   * @return  The filter usage value for this getter.
140   */
141  @NotNull FilterUsage filterUsage() default FilterUsage.CONDITIONALLY_ALLOWED;
142
143
144
145  /**
146   * The name of the attribute type in which the associated getter value will be
147   * stored in LDAP entries.  If this is not provided, then the method name must
148   * start with "get" and it will be assumed that the attribute name is the
149   * remainder of the method name.
150   *
151   * @return  The name of the attribute type in which the associated getter
152   *          value will be stored in LDAP entries, or an empty string if it
153   *          will be assumed that the attribute name matches the getter method
154   *          name without the initial "get".
155   */
156  @NotNull String attribute() default "";
157
158
159
160  /**
161   * The names of the object classes in which the associated attribute may
162   * be used.  This is primarily intended for use in generating LDAP schema from
163   * Java object types.
164   * <BR><BR>
165   * Values may include any combination of the structural and/or auxiliary
166   * object classes named in the {@link LDAPObject} annotation type for the
167   * associated class.  If no values are provided, then it will be assumed to
168   * be only included in the structural object class.
169   *
170   * @return  The names of the object classes in which the associated attribute
171   *          may be used, or an empty array if it will be assumed to only be
172   *          included in the structural object class.
173   */
174  @NotNull String[] objectClass() default {};
175}