UnboundID LDAP SDK for Java

LDAP SDK Home Page
Product Information
Using the UnboundID LDAP SDK Persistence Framework

The @LDAPField Annotation Type

The @LDAPField annotation type may be used to mark Java fields whose values should be stored in LDAP attributes. When encoding an entry from the object, the value(s) for the field will be encoded to an LDAP attribute, and when initializing a Java object from an LDAP entry, the value(s) of the corresponding attribute will be assigned to the marked field. The logic used to perform this encoding and decoding is provided by an instance of an ObjectEncoder class. A DefaultObjectEncoder class is included as part of the LDAP SDK persistence framework, and information about the data types that it supports is available in the supported data types page.

Fields that are marked with the @LDAPField annotation type must not be marked with any other annotation type used by the LDAP SDK persistence framework, like @LDAPDNField or @LDAPEntryField. They must not be declared final or static, but they may have any visibility level (including public, private, protected or the default package-level access).

Elements that may be included in the @LDAPField annotation type include:

  • attribute -- This element is used to specify the name (or OID) of the attribute that will be used to hold the value(s) of the field in LDAP entries. This attribute should be defined in the directory server schema, and it should be allowed by at least one of the structural or auxiliary object classes referenced in the @LDAPObject annotation used to mark the Java class. If this is not provided, then it will be assumed that LDAP attribute has the same name as the Java field.

  • objectClass -- This element is used to specify the name(s) of the LDAP object classes that allow the associated attribute. This is primarily used when generating LDAP schema definitions from annotated Java source code using the generate-schema-from-source tool. If it is not provided, then it will be assumed that the attribute is included in the structural object class.

  • inRDN -- This element is used to indicate whether the attribute should be included in the RDN for entries generated from Java objects of the associated type. At least one @LDAPField or @LDAPGetter annotation defined in the class must indicate that the associated attribute should be included in the entry's RDN. If this element is not provided, then it will be assumed that the corresponding field should not be used to construct the entry's RDN.

  • inAdd -- This element is used to indicate whether the attribute created from the associated field should be included when adding an entry created from an instance of the object to the directory. It may be false if the attribute should be generated by the directory server or populated through some other means. If this element is not provided, then it will have a default value of true. Note that if the inRDN element is present with a value of true, then the attribute will always be included in add operations regardless of the value of the inAdd element.

  • inModify -- This element is used to indicate whether changes to the value(s) of the marked field should be applied to the corresponding entry when performing an LDAP modify operation. It may be false if the attribute should not be updated by modify operations (e.g., if it should only be written in add operations). If this element is not provided, then it will have a default value of true. Note that if the inRDN element is present with a value of true, then the attribute will never be included in modify operations regardless of the value of the inModify element.

  • filterUsage -- This element is used to indicate whether the associated field should be used when generating a search filter to search for entries that correspond to objects of the associated type. It may have a value of REQUIRED (to indicate that the field must have a value in order to be able to generate a search filter for the object), ALWAYS_ALLOWED (to indicate that it may be present by itself or in conjunction with other fields or getter methods when generating the search filter), CONDITIONALLY_ALLOWED (to indicate that it may only be used in conjunction with other fields or getter methods that are REQUIRED or ALWAYS_ALLOWED), or EXCLUDED (to indicate that this field will never be included in generated search filters). If this element is not provided, then it will have a default value of CONDITIONALLY_ALLOWED.

  • failOnInvalidValue -- This element is used to indicate whether attempts to initialize a Java object with information from an LDAP entry should fail if the corresponding attribute has an invalid value for the associated field (e.g., the field has a type of Integer but the attribute value cannot be parsed as an integer). If this is false then any such decoding errors will be ignored and the corresponding fields will be left uninitialized. If this element is not provided, then it will have a default value of true.

  • failOnTooManyValues -- This element is used to indicate whether attempts to initialize a Java object with information from an LDAP entry should fail if the corresponding attribute has multiple values but the associated field can only hold a single value. If this is false then only the first value will be used to initialize the corresponding field and all other values will be ignored. If this element is not provided, then it will have a default value of true.

  • requiredForDecode -- This element is used to indicate whether the associated attribute must be present in an LDAP entry in order to successfully initialize an object. If this is true then an attempt to decode an entry that does not contain the associated attribute will fail. If this element is not provided, then it will have a default value of false, and the field will remain uninitialized if the associated attribute is not present when attempting to decode an entry.

  • requiredForEncode -- This element is used to indicate whether the field must have a non-null value when encoding an instance of the associated class to an LDAP entry. If this is true and the associated field does not have a non-null value, then attempts to encode the object to an entry will fail. If this element is not provided, then it will have a default value of false and the corresponding attribute will be omitted from the generated entry if the field has a null value.

  • defaultDecodeValue -- This element is used to specify the default value(s) that should be used for the field if the associated attribute is not present in an entry being used to initialize an object instance. If one or more values are provided, then they should be in the format in which they would be represented in the attribute. If this element is not provided, then no default decode values will be used.

  • defaultEncodeValue -- This element is used to specify the default value(s) that should be used for the field if it is not set when encoding an object to an LDAP entry. If one or more values are provided, then they should be in the format in which they should be stored in the attribute. If this element is not provided, then no default encode values will be used.

  • encoderClass -- This element is used to specify the class that provides the logic that will be used to encode the field value(s) to an LDAP attribute, and to initialize the field value(s) from an LDAP attribute. If a value is specified, then it must represent a Java class which is a subclass of com.unboundid.ldap.sdk.persist.ObjectEncoder. If this element is not provided, then a default value of com.unboundid.ldap.sdk.persist.DefaultObjectEncoder will be used.