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}