com.unboundid.ldap.sdk.transformations

Class FlattenSubtreeTransformation

java.lang.Object

com.unboundid.ldap.sdk.transformations.FlattenSubtreeTransformation

All Implemented Interfaces:

EntryTransformation, LDIFReaderEntryTranslator, LDIFWriterEntryTranslator, java.io.Serializable

@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class FlattenSubtreeTransformation
extends java.lang.Object
implements EntryTransformation, java.io.Serializable

This class provides an implementation of an entry transformation that will alter DNs below a specified base DN to ensure that they are exactly one level below the specified base DN. This can be useful when migrating data containing a large number of branches into a flat DIT with all of the entries below a common parent.

Only entries that were previously more than one level below the base DN will be renamed. The DN of the base entry itself will be unchanged, as well as the DNs of entries outside of the specified base DN.

For any entries that were originally more than one level below the specified base DN, any RDNs that were omitted may optionally be added as attributes to the updated entry. For example, if the flatten base DN is "ou=People,dc=example,dc=com" and an entry is encountered with a DN of "uid=john.doe,ou=East,ou=People,dc=example,dc=com", the resulting DN would be "uid=john.doe,ou=People,dc=example,dc=com" and the entry may optionally be updated to include an "ou" attribute with a value of "East".

Alternately, the attribute-value pairs from any omitted RDNs may be added to the resulting entry's RDN, making it a multivalued RDN if necessary. Using the example above, this means that the resulting DN could be "uid=john.doe+ou=East,ou=People,dc=example,dc=com". This can help avoid the potential for naming conflicts if entries exist with the same RDN in different branches.

This transformation will also be applied to DNs used as attribute values in the entries to be processed. All attributes in all entries (regardless of location in the DIT) will be examined, and any value that is a DN will have the same flattening transformation described above applied to it. The processing will be applied to any entry anywhere in the DIT, but will only affect values that represent DNs below the flatten base DN.

In many cases, when flattening a DIT with a large number of branches, the non-leaf entries below the flatten base DN are often simple container entries like organizationalUnit entries without any real attributes. In those cases, those container entries may no longer be necessary in the flattened DIT, and it may be desirable to eliminate them. To address that, it is possible to provide a filter that can be used to identify these entries so that they can be excluded from the resulting LDIF output. Note that only entries below the flatten base DN may be excluded by this transformation. Any entry at or outside the specified base DN that matches the filter will be preserved.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
FlattenSubtreeTransformation(Schema schema, DN flattenBaseDN, boolean addOmittedRDNAttributesToEntry, boolean addOmittedRDNAttributesToRDN, Filter excludeFilter) Creates a new instance of this transformation with the provided information.

Method Summary

Modifier and Type	Method and Description
Entry	transformEntry(Entry e) Applies an appropriate transformation to the provided entry.
Entry	translate(Entry original, long firstLineNumber) Applies some special transformation or filtering to the original Entry.
Entry	translateEntryToWrite(Entry original) Applies some special transformation or filtering to the original Entry.

Methods inherited from class java.lang.Object

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

Constructor Detail

FlattenSubtreeTransformation

public FlattenSubtreeTransformation(@Nullable
                                    Schema schema,
                                    @NotNull
                                    DN flattenBaseDN,
                                    boolean addOmittedRDNAttributesToEntry,
                                    boolean addOmittedRDNAttributesToRDN,
                                    @Nullable
                                    Filter excludeFilter)

Creates a new instance of this transformation with the provided information.

Parameters:

schema - The schema to use in processing. It may be null if a default standard schema should be used.

flattenBaseDN - The base DN below which any flattening will be performed. In the transformed data, all entries below this base DN will be exactly one level below this base DN. It must not be null.

addOmittedRDNAttributesToEntry - Indicates whether to add the attribute-value pairs of any RDNs stripped out of DNs during the course of flattening the DIT should be added as attribute values in the target entry.

addOmittedRDNAttributesToRDN - Indicates whether to add the attribute-value pairs of any RDNs stripped out of DNs during the course of flattening the DIT should be added as additional values in the RDN of the target entry (so the resulting DN will have a multivalued RDN with all of the attribute-value pairs of the original RDN, plus all attribute-value pairs from any omitted RDNs).

excludeFilter - An optional filter that may be used to exclude entries during the flattening process. If this is non-null, then any entry below the flatten base DN that matches this filter will be excluded from the results rather than flattened. This can be used to strip out "container" entries that were simply used to add levels of hierarchy in the previous branched DN that are no longer needed in the flattened representation of the DIT.

Method Detail

transformEntry

@Nullable
public Entry transformEntry(@NotNull
                                      Entry e)

Applies an appropriate transformation to the provided entry.

Specified by:

transformEntry in interface EntryTransformation

Parameters:

e - The entry to transform.

Returns:

A copy of the entry with any appropriate transformation applied, the original entry if no transformations were necessary, or null if the entry should be suppressed.

translate

@Nullable
public Entry translate(@NotNull
                                 Entry original,
                                 long firstLineNumber)

Applies some special transformation or filtering to the original Entry.

Specified by:

translate in interface LDIFReaderEntryTranslator

Parameters:

original - The original Entry that was read and parsed from the input file.

firstLineNumber - The first line number of the LDIF record corresponding to the read Entry. This is most useful when throwing an LDIFException.

Returns:

The Entry that should be returned in the call to LDIFReader.readEntry(). This can be the original parameter Entry, a newly constructed Entry, or null to signal that the provided Entry should be skipped.

translateEntryToWrite

@Nullable
public Entry translateEntryToWrite(@NotNull
                                             Entry original)

Applies some special transformation or filtering to the original Entry.

Specified by:

translateEntryToWrite in interface LDIFWriterEntryTranslator

Parameters:

original - The original Entry that was to be written.

Returns:

The Entry that should be written. This can be the original parameter Entry, a newly-constructed Entry, or null to signal that this Entry should not be written. Note, however, that if the original entry provided as a parameter is altered, then the change will be visible to anything that references that entry. If you are not sure about whether changes to the original entry are acceptable, it is recommended that you use the duplicate() method to create a copy of the original and make the necessary changes to that duplicate.