Package com.unboundid.directory.sdk.common.types

Interface ValueConstructor

  • @ThreadSafety(level=INTERFACE_THREADSAFE)
public interface ValueConstructor
    A ValueConstructor is used to build String values using a value-pattern template that references attribute values within an Entry. An instance is created by calling ServerContext.createValueConstructor(java.lang.String).

    Referencing Attribute Values

    Any text provided in the value-pattern is copied verbatim into the constructed value with the exception of attribute names embedded in '{}'s. For instance, a value template of "{uid}@example.com" and an entry with a uid value of "jsmith" would produce a value of "jsmith@example.com".

    If a value template references multiple attributes, at most one may be multivalued. If one attribute is multivalued then the returned value will be multivalued with the same number of values. For example a template of '{givenName} {sn}' would produce values ['Jim Smith', 'James Smith'] if givenName had values of ['Jim', 'James'] and sn had a value of 'Smith'. If the source entry has no value or if there are multiple multivalued attributes, the attribute value construction will fail.

    To include a '{' in the constructed value (when constructing JSON for instance) use '{{' in the value-pattern. Likewise, '}}' will result in '}' in the value pattern.

    Regular Expressions

    A regular expression with a substitution pattern can be used to further manipulate an individual attribute value. The java.util.regex.Pattern and java.util.regex.Matcher classes are used to perform the substitution. The regular expression with replacement value uses this syntax '{attr-name:/regex/replacement/flags}'.
    • 'attr-name' is an attribute name such as 'cn'.
    • 'regex' is a regular expression using the syntax described in the java.util.regex.Pattern javadoc. The optional flag value can also be used to change how this regular expression is interpreted.
    • 'replacement' is a replacement value that is passed to the java.util.regex.Matcher#replaceFirst or java.util.regex.Matcher#replaceAll method to perform the replacement. The 'g' (global) flag controls whether replaceFirst or replaceAll is called.
    • 'flags' is an optional set of single character flags that control how the regular expression is interpreted and how the replacement is performed. The flags are:
      • 'g' : Matcher#replaceAll is called instead of Matcher#replaceFirst to replace all matching values instead of just the first one.
      • 'i' : the regex pattern is compiled with Pattern.CASE_INSENSITIVE.
      • 'x' : the regex pattern is compiled with Pattern.COMMENTS.
      • 's' : the regex pattern is compiled with Pattern.DOTALL.
      • 'm' : the regex pattern is compiled with Pattern.MULTILINE.
      • 'u' : the regex pattern is compiled with Pattern.UNICODE_CASE.
      • 'd' : the regex pattern is compiled with Pattern.UNIX_LINES.
    The substitution value is constructed using Java code equivalent to: 
       Pattern pattern = Pattern.compile(regex, flagsMask);
   Matcher matcher = pattern.matcher(attributeValueInput);
   String substitutionValueOutput = matcher.replaceFirst(replacement);

    JSON Attribute Values

    To extract JSON fields within JSON attributes append '.' and then the JSON field to extract to the attribute name. For example, if 'ubidEmailJSON' is a JSON attribute and the 'value' field is to be extracted then 'ubidEmailJSON.value' could be specified for the attribute name resulting in '{ubidEmailJSON.value}' or '{ubidEmailJSON.value:/regex/replacement/flags}' if a regular expression is to be used.

    Escaping and Transforming Attribute Values

    To apply modifiers to the values extracted append ':' and then the name of the modifier to apply. For example, if attribute 'mail' is to be included in a constructed JSON value then modifier 'jsonEscape' could be specified resulting in '{{ "userMail":"{mail:jsonEscape}" }}' or '{{ "userMail":"{mail:/regex/replacement/flags:jsonEscape}" }}' if a regular expression is to be used. Note that '{{' expands to '{' and '}}' to '}'.

    The modifiers are:

    • 'dnEscape' : Escape text for use in a DN value.
    • 'jsonEscape' : Escape text for use in a JSON value.
    • 'ldapFilterEscape' : Escape text for use in an LDAP filter.
    • 'lowerCase' : Convert text to lower case.
    • 'trim' : Remove leading and trailing whitespace.
    • 'upperCase' : Convert text to upper case.

    Example

    Here is an example to summarize these points. Suppose, the 'uid' field of the target entry needs to be populated with the initials of the first and last name followed by the user's employee number which is stored in the 'eid' attribute. For example, 'John Smith' with an employee id of 12345, would get a uid of 'js12345'. The value-pattern would be '{givenname:/^(.)(.*)/$1/s:lowerCase}{sn:/^(.)(.*)/$1/s:lowerCase}{eid}'. The employee's initials are extracted from the 'givenname' and 'sn' attributes. The '^(.)(.*)' regular expression used for these attributes matches the entire value and stores the initial character in the $1 variable, which is used for the replacement. (The 's' flag is used to guard against the unlikely event that the user's 'givenname' or 'sn' attribute includes a newline character.) The lowerCase modifier converts the initial to lowercase.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.util.List<java.lang.String> constructValues​(Entry entry)
      Returns a list of values constructed using the value template that was used to create this ValueConstructor substituting attribute values from the provided entry where they appear in the value template.
      java.util.List<java.lang.String> constructValues​(Entry entry)
      Returns a list of values constructed using the value template that was used to create this ValueConstructor substituting attribute values from the provided entry where they appear in the value template.

    • Method Detail

      • constructValues

        java.util.List<java.lang.String> constructValues​(Entry entry)
                                          throws LDAPException
        Returns a list of values constructed using the value template that was used to create this ValueConstructor substituting attribute values from the provided entry where they appear in the value template.
        Parameters:
        entry - Attributes referenced in the value template are pulled from this entry.
        Returns:
        The list of attribute values based on the value template and the specified entry.
        Throws:
        LDAPException - If the provided entry does not include values for all attributes that appear in the value template; if the value template includes regular expressions for extracting portions of an attribute value, and the attribute value does not match the regular expression; or if the value template references multiple attributes that have more than one value.

      • constructValues

        java.util.List<java.lang.String> constructValues​(Entry entry)
                                          throws LDAPException
        Returns a list of values constructed using the value template that was used to create this ValueConstructor substituting attribute values from the provided entry where they appear in the value template.
        Parameters:
        entry - Attributes referenced in the value template are pulled from this entry.
        Returns:
        The list of attribute values based on the value template and the specified entry.
        Throws:
        LDAPException - If the provided entry does not include values for all attributes that appear in the value template; if the value template includes regular expressions for extracting portions of an attribute value, and the attribute value does not match the regular expression; or if the value template references multiple attributes that have more than one value.