001    /*
002     * Copyright 2009-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2009-2016 UnboundID Corp.
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     */
021    package com.unboundid.ldap.sdk.persist;
022    
023    
024    
025    import java.lang.annotation.ElementType;
026    import java.lang.annotation.Documented;
027    import java.lang.annotation.Retention;
028    import java.lang.annotation.RetentionPolicy;
029    import 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})
047    public @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      boolean inAdd() default true;
057    
058    
059    
060      /**
061       * Indicates whether the value returned from this method should be included in
062       * the set of LDAP modifications if it has been changed when modifying an
063       * existing instance of the associated object in the directory.  Note that any
064       * getter value which is to be included in entry RDNs will never be included
065       * in modify operations regardless of the value of this element.
066       */
067      boolean inModify() default true;
068    
069    
070    
071      /**
072       * Indicates whether the value returned from this method should be included in
073       * the RDN of entries created from the associated object.  Any getter value
074       * which is to be included entry RDNs will always be included in add
075       * operations regardless of the value of the {@link #inAdd} element.
076       * <BR><BR>
077       * When generating an entry DN, the persistence framework will construct an
078       * RDN using all fields marked with {@code LDAPField} that have
079       * {@code inRDN=true} and all getter methods marked with {@code LDAPGetter}
080       * that have {@code inRDN=true}.  A class marked with {@code LDAPObject} must
081       * either have at least one {@code LDAPField} or {@code LDAPGetter} with
082       * {@code inRDN=true}, or it must be a direct subclass of another class marked
083       * with {@code LDAPObject}.  If a class has one or more fields and/or getters
084       * with {@code inRDN=true}, then only those fields/getters will be used to
085       * construct the RDN, even if that class is a direct subclass of another class
086       * marked with {@code LDAPObject}.
087       */
088      boolean inRDN() default false;
089    
090    
091    
092      /**
093       * The class that provides the logic for encoding the method return value to
094       * an LDAP attribute.
095       */
096      Class<? extends ObjectEncoder> encoderClass()
097           default DefaultObjectEncoder.class;
098    
099    
100    
101      /**
102       * Indicates whether and under what circumstances the value returned from this
103       * method may be included in a search filter generated to search for entries
104       * that match the object.
105       */
106      FilterUsage filterUsage() default FilterUsage.CONDITIONALLY_ALLOWED;
107    
108    
109    
110      /**
111       * The name of the attribute type in which the associated getter value will be
112       * stored in LDAP entries.  If this is not provided, then the method name must
113       * start with "get" and it will be assumed that the attribute name is the
114       * remainder of the method name.
115       */
116      String attribute() default "";
117    
118    
119    
120      /**
121       * The name(s) of the object class(es) in which the associated attribute may
122       * be used.  This is primarily intended for use in generating LDAP schema from
123       * Java object types.
124       * <BR><BR>
125       * Values may include any combination of the structural and/or auxiliary
126       * object classes named in the {@link LDAPObject} annotation type for the
127       * associated class.  If no values are provided, then it will be assumed to
128       * be only included in the structural object class.
129       */
130      String[] objectClass() default {};
131    }