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