org.springframework.ldap.core.support

## Class DefaultIncrementalAttributesMapper

- java.lang.Object
- - org.springframework.ldap.core.support.DefaultIncrementalAttributesMapper

- All Implemented Interfaces:
    AttributesMapper<DefaultIncrementalAttributesMapper>, IncrementalAttributesMapper<DefaultIncrementalAttributesMapper>

      public class DefaultIncrementalAttributesMapper
      extends Object
      implements IncrementalAttributesMapper<DefaultIncrementalAttributesMapper>

  Utility class that helps with reading all attribute values from Active Directory using Incremental Retrieval of Multi-valued Properties.

  Example usage of this attribute mapper:

           List values = DefaultIncrementalAttributeMapper.lookupAttributeValues(ldapTemplate, theDn, "oneAttribute");
           Attributes attrs = DefaultIncrementalAttributeMapper.lookupAttributeValues(ldapTemplate, theDn, new Object[]{"oneAttribute", "anotherAttribute"});

  For greater control, e.g. explicitly specifying the requested page size, create and use an instance yourself:

            IncrementalAttributesMapper incrementalAttributeMapper = new DefaultIncrementalAttributeMapper(10, "someAttribute");
            while (incrementalAttributeMapper.hasMore()) {
                ldap.lookup(entrDn, incrementalAttributeMapper.getAttributesForLookup(), incrementalAttributeMapper);
            }

            List values = incrementalAttributeMapper.getValues("someAttribute");

  NOTE: Instances of this class are highly stateful and must not be reused or shared between threads in any way.

  NOTE: Instances of this class can only be used with lookups. No support is given for searches.

  Since:
    1.3.2
  Author:
    Marius Scurtescu, Mattias Hellborg Arthursson
  See Also:
    Incremental Retrieval of Multi-valued Properties, `lookupAttributes(org.springframework.ldap.core.LdapOperations, javax.naming.Name, String[])`, `lookupAttributeValues(org.springframework.ldap.core.LdapOperations, javax.naming.Name, String)`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultIncrementalAttributesMapper(int pageSize, String attributeName)` Create an instance for the requested attribute with a specific page size.
    `DefaultIncrementalAttributesMapper(int pageSize, String[] attributeNames)` Create an instance for the requested attributes with a specific page size.
    `DefaultIncrementalAttributesMapper(String attributeName)` Create an instance for the requested attribute.
    `DefaultIncrementalAttributesMapper(String[] attributeNames)` Create an instance for the requested attributes.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `String[]` | `getAttributesForLookup()` Get properly formatted attributes for use in the next query.
    `Attributes` | `getCollectedAttributes()` Get all collected values for all managed attributes as an Attributes instance.
    `List<Object>` | `getValues(String attributeName)` Get all of the collected values for the specified attribute.
    `boolean` | `hasMore()` Check whether another query iteration is required to get all values for all attributes.
    `static Attributes` | `lookupAttributes(LdapOperations ldapOperations, Name dn, String attribute)` Lookup all values for the specified attribute, looping through the results incrementally if necessary.
    `static Attributes` | `lookupAttributes(LdapOperations ldapOperations, Name dn, String[] attributes)` Lookup all values for the specified attributes, looping through the results incrementally if necessary.
    `static Attributes` | `lookupAttributes(LdapOperations ldapOperations, String dn, String attribute)` Lookup all values for the specified attribute, looping through the results incrementally if necessary.
    `static Attributes` | `lookupAttributes(LdapOperations ldapOperations, String dn, String[] attributes)` Lookup all values for the specified attributes, looping through the results incrementally if necessary.
    `static List<Object>` | `lookupAttributeValues(LdapOperations ldapOperations, Name dn, String attribute)` Lookup all values for the specified attribute, looping through the results incrementally if necessary.
    `static List<Object>` | `lookupAttributeValues(LdapOperations ldapOperations, String dn, String attribute)` Lookup all values for the specified attribute, looping through the results incrementally if necessary.
    `DefaultIncrementalAttributesMapper` | `mapFromAttributes(Attributes attributes)` Goes through all of the attributes to record their values and figure out whether a new query iteration is needed to get more values.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DefaultIncrementalAttributesMapper

          public DefaultIncrementalAttributesMapper(String attributeName)

      Create an instance for the requested attribute.
      Parameters:
        `attributeName` - the name of the attribute that this instance handles. This is the attribute name that will be requested, and whose values are managed.

    - #### DefaultIncrementalAttributesMapper

          public DefaultIncrementalAttributesMapper(String[] attributeNames)

      Create an instance for the requested attributes.
      Parameters:
        `attributeNames` - the name of the attributes that this instance handles. These are the attribute names that will be requested, and whose values are managed.

    - #### DefaultIncrementalAttributesMapper

          public DefaultIncrementalAttributesMapper(int pageSize,
                                                    String attributeName)

      Create an instance for the requested attribute with a specific page size.
      Parameters:
        `pageSize` - the requested page size that will be included in range query attribute names.
        `attributeName` - the name of the attribute that this instance handles. This is the attribute name that will be requested, and whose values are managed.

    - #### DefaultIncrementalAttributesMapper

          public DefaultIncrementalAttributesMapper(int pageSize,
                                                    String[] attributeNames)

      Create an instance for the requested attributes with a specific page size.
      Parameters:
        `pageSize` - the requested page size that will be included in range query attribute names.
        `attributeNames` - the name of the attributes that this instance handles. These are the attribute names that will be requested, and whose values are managed.

  - ### Method Detail

    - #### mapFromAttributes

          public final DefaultIncrementalAttributesMapper mapFromAttributes(Attributes attributes)
                                                                     throws NamingException

      Description copied from interface: `IncrementalAttributesMapper`
      Goes through all of the attributes to record their values and figure out whether a new query iteration is needed to get more values.
      Specified by:
        `mapFromAttributes` in interface `AttributesMapper<DefaultIncrementalAttributesMapper>`
      Specified by:
        `mapFromAttributes` in interface `IncrementalAttributesMapper<DefaultIncrementalAttributesMapper>`
      Parameters:
        `attributes` - attributes from a SearchResult.
      Returns:
        this instance.
      Throws:
        `NamingException` - if any error occurs mapping the attributes

    - #### getValues

          public final List<Object> getValues(String attributeName)

      Description copied from interface: `IncrementalAttributesMapper`
      Get all of the collected values for the specified attribute.
      Specified by:
        `getValues` in interface `IncrementalAttributesMapper<DefaultIncrementalAttributesMapper>`
      Parameters:
        `attributeName` - the attribute to get values for.
      Returns:
        the collected values for the specified attribute. Will be `null` if the requested attribute has not been returned by the server (attribute did not exist).

    - #### getCollectedAttributes

          public final Attributes getCollectedAttributes()

      Description copied from interface: `IncrementalAttributesMapper`
      Get all collected values for all managed attributes as an Attributes instance.
      Specified by:
        `getCollectedAttributes` in interface `IncrementalAttributesMapper<DefaultIncrementalAttributesMapper>`
      Returns:
        an Attributes instance populated with all collected values.

    - #### hasMore

          public final boolean hasMore()

      Description copied from interface: `IncrementalAttributesMapper`
      Check whether another query iteration is required to get all values for all attributes.
      Specified by:
        `hasMore` in interface `IncrementalAttributesMapper<DefaultIncrementalAttributesMapper>`
      Returns:
        `true` if there are more values for at least one of the managed attributes, `false` otherwise.

    - #### getAttributesForLookup

          public final String[] getAttributesForLookup()

      Description copied from interface: `IncrementalAttributesMapper`
      Get properly formatted attributes for use in the next query. The attribute names included will include Range specifiers as needed and only the attributes that have not been retrieved in full will be included.
      Specified by:
        `getAttributesForLookup` in interface `IncrementalAttributesMapper<DefaultIncrementalAttributesMapper>`
      Returns:
        an array of Strings to be used as input to e.g. `LdapTemplate.lookup(javax.naming.Name, String[], org.springframework.ldap.core.AttributesMapper)` in the next iteration.

    - #### lookupAttributes

          public static Attributes lookupAttributes(LdapOperations ldapOperations,
                                                    String dn,
                                                    String attribute)

      Lookup all values for the specified attribute, looping through the results incrementally if necessary.
      Parameters:
        `ldapOperations` - The instance to use for performing the actual lookup.
        `dn` - The distinguished name of the object to find.
        `attribute` - name of the attribute to request.
      Returns:
        an Attributes instance, populated with all found values for the requested attribute. Never `null`, though the actual attribute may not be set if it was not set on the requested object.

    - #### lookupAttributes

          public static Attributes lookupAttributes(LdapOperations ldapOperations,
                                                    String dn,
                                                    String[] attributes)

      Lookup all values for the specified attributes, looping through the results incrementally if necessary.
      Parameters:
        `ldapOperations` - The instance to use for performing the actual lookup.
        `dn` - The distinguished name of the object to find.
        `attributes` - names of the attributes to request.
      Returns:
        an Attributes instance, populated with all found values for the requested attributes. Never `null`, though the actual attributes may not be set if they was not set on the requested object.

    - #### lookupAttributes

          public static Attributes lookupAttributes(LdapOperations ldapOperations,
                                                    Name dn,
                                                    String attribute)

      Lookup all values for the specified attribute, looping through the results incrementally if necessary.
      Parameters:
        `ldapOperations` - The instance to use for performing the actual lookup.
        `dn` - The distinguished name of the object to find.
        `attribute` - name of the attribute to request.
      Returns:
        an Attributes instance, populated with all found values for the requested attribute. Never `null`, though the actual attribute may not be set if it was not set on the requested object.

    - #### lookupAttributes

          public static Attributes lookupAttributes(LdapOperations ldapOperations,
                                                    Name dn,
                                                    String[] attributes)

      Lookup all values for the specified attributes, looping through the results incrementally if necessary.
      Parameters:
        `ldapOperations` - The instance to use for performing the actual lookup.
        `dn` - The distinguished name of the object to find.
        `attributes` - names of the attributes to request.
      Returns:
        an Attributes instance, populated with all found values for the requested attributes. Never `null`, though the actual attributes may not be set if they was not set on the requested object.

    - #### lookupAttributeValues

          public static List<Object> lookupAttributeValues(LdapOperations ldapOperations,
                                                           String dn,
                                                           String attribute)

      Lookup all values for the specified attribute, looping through the results incrementally if necessary.
      Parameters:
        `ldapOperations` - The instance to use for performing the actual lookup.
        `dn` - The distinguished name of the object to find.
        `attribute` - name of the attribute to request.
      Returns:
        a list with all attribute values found for the requested attribute. Never `null`, an empty list indicates that the attribute was not set or empty.

    - #### lookupAttributeValues

          public static List<Object> lookupAttributeValues(LdapOperations ldapOperations,
                                                           Name dn,
                                                           String attribute)

      Lookup all values for the specified attribute, looping through the results incrementally if necessary.
      Parameters:
        `ldapOperations` - The instance to use for performing the actual lookup.
        `dn` - The distinguished name of the object to find.
        `attribute` - name of the attribute to request.
      Returns:
        a list with all attribute values found for the requested attribute. Never `null`, an empty list indicates that the attribute was not set or empty.