org.springframework.ldap.ldif.parser

## Class LdifParser

- java.lang.Object
- - org.springframework.ldap.ldif.parser.LdifParser

- All Implemented Interfaces:
    InitializingBean, Parser

      public class LdifParser
      extends Object
      implements Parser, InitializingBean

  The `LdifParser` is the main class of the `org.springframework.ldap.ldif` package. This class reads lines from a resource and assembles them into an `LdapAttributes` object. The `LdifParser` does ignores changetype LDIF entries as their usefulness in the context of an application has yet to be determined.

  Design
  `LdifParser` provides the main interface for operation but requires three supporting classes to enable operation:

  - `SeparatorPolicy` - establishes the mechanism by which lines are assembled into attributes.
  - `AttributeValidationPolicy` - ensures that attributes are correctly structured prior to parsing.
  - `Specification` - provides a mechanism by which object structure can be validated after assembly.
  Together, these 4 classes read from the resource line by line and translate the data into objects for use.

  Usage
  `getRecord()` reads the next available record from the resource. Lines are read and passed to the `SeparatorPolicy` for interpretation. The parser continues to read lines and appends them to the buffer until it encounters the start of a new attribute or an end of record delimiter. When the new attribute or end of record is encountered, the buffer is passed to the `AttributeValidationPolicy` which ensures the buffer conforms to a valid attribute definition as defined in RFC2849 and returns an `LdapAttribute` object which is then added to the record, an `LdapAttributes` object. Upon encountering the end of record, the record is validated by the `Specification` policy and, if valid, returned to the requester.

  NOTE: By default, objects are not validated. If validation is required, an appropriate specification object must be set.

  The parser requires the resource to be `open()` prior to an invocation of `getRecord()`. `hasMoreRecords()` can be used to loop over the resource until all records have been retrieved. Likewise, the `reset()` method will reset the resource.

  Objects implementing the `Attributes` interface are required to support a case sensitivity setting which controls whether or not the attribute IDs of the object are case sensitive. The `caseInsensitive` setting of the `LdifParser` is passed to the constructor of any `Attributes` created. The default value for this setting is true so that case insensitive objects are created.

  Author:
    Keith Barlow

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `LdifParser()` Default constructor.
    `LdifParser(boolean caseInsensitive)` Creates a LdifParser with the indicated case sensitivity setting.
    `LdifParser(File file)` Convenience constructor: accepts a File object.
    `LdifParser(Resource resource)` Convenience constructor for resource specification.
    `LdifParser(Resource resource, boolean caseInsensitive)` Creates an LdifParser for the specified resource with the provided case sensitivity setting.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()`
    `void` | `close()` Closes the resource after parsing.
    `LdapAttributes` | `getRecord()` Parses the next record from the resource.
    `boolean` | `hasMoreRecords()` True if the resource contains more records; false otherwise.
    `boolean` | `isReady()` Indicates whether or not the parser is ready to to return results.
    `void` | `open()` Opens the resource: the resource must be opened prior to parsing.
    `void` | `reset()` Resets the line read parser.
    `void` | `setAttributeValidationPolicy(AttributeValidationPolicy avPolicy)` Policy object enforcing the rules for acceptable attributes.
    `void` | `setCaseInsensitive(boolean caseInsensitive)` Sets the control parameter for specifying case sensitivity on creation of the `Attributes` object.
    `void` | `setRecordSpecification(Specification<LdapAttributes> specification)` Policy object for enforcing rules to acceptable LDAP objects.
    `void` | `setResource(Resource resource)` Sets the resource to parse.
    `void` | `setSeparatorPolicy(SeparatorPolicy separatorPolicy)` Set the separator policy.

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

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

- - ### Constructor Detail

    - #### LdifParser

          public LdifParser()

      Default constructor.

    - #### LdifParser

          public LdifParser(boolean caseInsensitive)

      Creates a LdifParser with the indicated case sensitivity setting.
      Parameters:
        `caseInsensitive` - Case sensitivity setting for LdapAttributes objects returned by the parser.

    - #### LdifParser

          public LdifParser(Resource resource,
                            boolean caseInsensitive)

      Creates an LdifParser for the specified resource with the provided case sensitivity setting.
      Parameters:
        `resource` - The resource to parse.
        `caseInsensitive` - Case sensitivity setting for LdapAttributes objects returned by the parser.

    - #### LdifParser

          public LdifParser(Resource resource)

      Convenience constructor for resource specification.
      Parameters:
        `resource` - The resource to parse.

    - #### LdifParser

          public LdifParser(File file)

      Convenience constructor: accepts a File object.
      Parameters:
        `file` - The file to parse.

  - ### Method Detail

    - #### setSeparatorPolicy

          public void setSeparatorPolicy(SeparatorPolicy separatorPolicy)

      Set the separator policy. The default separator policy should suffice for most needs.
      Parameters:
        `separatorPolicy` - Separator policy.

    - #### setAttributeValidationPolicy

          public void setAttributeValidationPolicy(AttributeValidationPolicy avPolicy)

      Policy object enforcing the rules for acceptable attributes.
      Parameters:
        `avPolicy` - Attribute validation policy.

    - #### setRecordSpecification

          public void setRecordSpecification(Specification<LdapAttributes> specification)

      Policy object for enforcing rules to acceptable LDAP objects. This policy may be used to enforce schema restrictions.
      Parameters:
        `specification` -

    - #### setResource

          public void setResource(Resource resource)

      Description copied from interface: `Parser`
      Sets the resource to parse.
      Specified by:
        `setResource` in interface `Parser`
      Parameters:
        `resource` - The resource to parse.

    - #### setCaseInsensitive

          public void setCaseInsensitive(boolean caseInsensitive)

      Description copied from interface: `Parser`
      Sets the control parameter for specifying case sensitivity on creation of the `Attributes` object.
      Specified by:
        `setCaseInsensitive` in interface `Parser`
      Parameters:
        `caseInsensitive` - The resource to parse.

    - #### open

          public void open()
                    throws IOException

      Description copied from interface: `Parser`
      Opens the resource: the resource must be opened prior to parsing.
      Specified by:
        `open` in interface `Parser`
      Throws:
        `IOException` - if a problem is encountered while trying to open the resource.

    - #### isReady

          public boolean isReady()
                          throws IOException

      Description copied from interface: `Parser`
      Indicates whether or not the parser is ready to to return results.
      Specified by:
        `isReady` in interface `Parser`
      Returns:
        boolean indicator
      Throws:
        `IOException` - if there is a problem with the underlying resource.

    - #### close

          public void close()
                     throws IOException

      Description copied from interface: `Parser`
      Closes the resource after parsing.
      Specified by:
        `close` in interface `Parser`
      Throws:
        `IOException` - if a problem is encountered while trying to close the resource.

    - #### reset

          public void reset()
                     throws IOException

      Description copied from interface: `Parser`
      Resets the line read parser.
      Specified by:
        `reset` in interface `Parser`
      Throws:
        `IOException` - if a problem is encountered while trying to reset the resource.

    - #### hasMoreRecords

          public boolean hasMoreRecords()
                                 throws IOException

      Description copied from interface: `Parser`
      True if the resource contains more records; false otherwise.
      Specified by:
        `hasMoreRecords` in interface `Parser`
      Returns:
        boolean indicating whether or not the end of record has been reached.
      Throws:
        `IOException` - if a problem is encountered while trying to validate the resource is ready.

    - #### getRecord

          public LdapAttributes getRecord()
                                   throws IOException

      Description copied from interface: `Parser`
      Parses the next record from the resource.
      Specified by:
        `getRecord` in interface `Parser`
      Returns:
        LdapAttributes object representing the record parsed.
      Throws:
        `IOException` - if a problem is encountered while trying to read from the resource.

    - #### afterPropertiesSet

          public void afterPropertiesSet()
                                  throws Exception

      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`
      Throws:
        `Exception`