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 classes for objects that may be
052 * persisted in an LDAP directory server.  It may only be used to mark classes,
053 * and should not be used for interfaces or annotation types.  Classes with this
054 * annotation type must provide a default zero-argument constructor.  Fields in
055 * the associated class which are to be persisted should be marked with the
056 * {@link LDAPField} annotation type.
057 */
058@Documented()
059@Retention(RetentionPolicy.RUNTIME)
060@Target(value={ElementType.TYPE})
061public @interface LDAPObject
062{
063  /**
064   * Indicates whether to request all attributes when performing searches to
065   * retrieve objects of this type.  If this is {@code true}, then the search
066   * request will attempt to retrieve all user and operational attributes.  If
067   * this is {@code false}, then the search request will attempt to retrieve
068   * only those attributes which are referenced by an {@link LDAPField} or
069   * {@link LDAPSetter} annotation.  Note that if this is given a value of
070   * {@code true}, then lazy loading will be disabled.
071   *
072   * @return  {@code true} if all attributes should be requested, or
073   *          {@code false} if only referenced attributes should be requested.
074   */
075  boolean requestAllAttributes() default false;
076
077
078
079  /**
080   * The DN of the entry below which objects of this type will be created if no
081   * alternate parent DN is specified.  A value equal to the empty string
082   * indicates that there should be no default parent DN.
083   * <BR><BR>
084   * If a class marked with the {@code LDAPObject} annotation type does not
085   * specify a default parent DN but is a direct subclass of another class
086   * marked with {@code LDAPObject}, then the subclass will inherit the default
087   * parent DN from the superclass.
088   *
089   * @return  The DN of the entry below which objects of this type will be
090   *          created if no alternate parent DN is specified, or the empty
091   *          string if there should be no default parent DN.
092   */
093  @NotNull String defaultParentDN() default "";
094
095
096
097  /**
098   * The name of a method that should be invoked on an object after all other
099   * decode processing has been performed for that object.  It may perform any
100   * additional work or validation that is not available as part of the LDAP SDK
101   * persistence framework.  If a method name is provided, then that method must
102   * exist in the associated class and it must not take any arguments.  It may
103   * throw any kind of exception if the object is not valid.
104   *
105   * @return  The name of a method that should be invoked on an object after all
106   *          other decode processing has been performed for that object, or an
107   *          empty string if no post-decode method has been defined.
108   */
109  @NotNull String postDecodeMethod() default "";
110
111
112
113  /**
114   * The name of a method that should be invoked after an object has been
115   * encoded to an LDAP entry.  It may alter the generated entry in any way,
116   * including adding, removing, or replacing attributes, or altering the entry
117   * DN.  If a method name is provided, then that method must exist in the
118   * associated class and it must take exactly one argument, with a type of
119   * {@link com.unboundid.ldap.sdk.Entry}.  It may throw any kind of exception
120   * if a problem is found with the entry and it should not be used.
121   *
122   * @return  The name of a method that should be invoked after an object has
123   *          been encoded to an LDAP entry, or an empty string if no
124   *          post-encode method has been defined.
125   */
126  @NotNull String postEncodeMethod() default "";
127
128
129
130  /**
131   * The name of the structural object class for LDAP entries created from the
132   * associated object type.  If no value is provided, then it will be assumed
133   * that the object class name is equal to the unqualified name of the Java
134   * class.
135   *
136   * @return  The name of the structural object class for LDAP entries created
137   *          from the associated object type, or an empty string if the object
138   *          class name will be assumed to be equal to the unqualified name of
139   *          the Java class.
140   */
141  @NotNull String structuralClass() default "";
142
143
144
145  /**
146   * The name) of any auxiliary object classes for LDAP entries created from the
147   * associated object type.
148   *
149   * @return  The names of any auxiliary object classes for LDAP entries created
150   *          from the associated object type, or an empty array if entries
151   *          should not include any auxiliary object classes.
152   */
153  @NotNull String[] auxiliaryClass() default {};
154
155
156
157  /**
158   * The names of any superior object classes for the structural and auxiliary
159   * object classes that should be included in generated entries.
160   *
161   * @return  The names of any superior object classes for the structural and
162   *          auxiliary object classes that should be included in generated
163   *          entries, or an empty array if no superior classes should be
164   *          included.
165   */
166  @NotNull String[] superiorClass() default {};
167}