UnboundID LDAP SDK for Java

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

The @LDAPGetter and @LDAPSetter Annotation Types

The @LDAPGetter annotation type may be used to mark a method that will be invoked in the course of encoding a Java object to an LDAP entry. The method should not take any arguments, and should return a value (or set of values) that will be converted to an attribute to include in the generated entry. The @LDAPSetter annotation type may be used to mark a method that will be invoked in the course of initializing a Java object from an LDAP entry. The method should take exactly one argument, which will be a value (or set of values) decoded from an LDAP attribute.

In simple cases, the @LDAPGetter and @LDAPSetter annotation types provide roughly the same functionality as the @LDAPField annotation type, but they can be used to provide additional functionality. In particular, using the method annotations rather than field annotations make it possible to provide more complex processing when encoding or decoding attribute values (e.g., breaking up a single attribute value across multiple fields), or to have values which are read-only or write-only.

The methods marked with @LDAPGetter or @LDAPSetter must not be declared static, but they may have any visibility modifier, including public, private, protected, or the default package-level access.

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

  • attribute -- This element is used to specify the name (or OID) of the attribute that will be used to hold the method return value(s) 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 element is not provided, then the name of the method must start with "get" and it will be assumed that the attribute name will be the remainder of the method name.

  • 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 method should not be used to construct the entry's RDN.

  • inAdd -- This element is used to indicate whether the attribute created from the associated method 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 in the return value(s) of the marked method 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 return value of the associated method 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 method must return 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 method will never be included in generated search filters). If this element is not provided, then it will have a default value of CONDITIONALLY_ALLOWED.

  • encoderClass -- This element is used to specify the class that provides the logic that will be used to encode the method return value(s) to 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.

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

  • attribute -- This element is used to specify the name (or OID) of the attribute that will be used to provide the value(s) for the argument to pass to the setter method. 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 element is not provided, then the name of the method must start with "get" and it will be assumed that the attribute name will be the remainder of the method name.

  • 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 method argument (e.g., the argument 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 method will not be invoked. 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 argument for the associated method can only hold a single value. If this is false then only the first value will be used to initialize the corresponding method and all other values will be ignored. If this element is not provided, then it will have a default value of true.

  • encoderClass -- This element is used to specify the class that provides the logic that will decode the attribute to obtain the value(s) to pass as an argument to the associated method. 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.