| 📜 LSC ORIGINAL README |

---

About LSC Junx mods

This fork of LSC 2.2 includes a focused set of “Junx” extensions that harden synchronization in complex LDAP environments (OpenLDAP, Active Directory) without changing the core data model or configuration philosophy.
The goal is to make DN handling, rename operations, monitoring and large‑scale runs more predictable and observable while remaining backward‑compatible with existing configurations.

Distinguished Name (DN) handling and comparison

• Canonical DN comparison across heterogeneous directories
  DN values can be represented differently by servers (mixed case in attribute names, hex escapes such as \3D vs \=, redundant escaped spaces).
  The Junx layer introduces DN‑aware normalization utilities and configuration (dnAttributes per connection) so that:

  • DN attributes in source entries are normalized when they are read (hex‑escapes decoded, attribute names made case‑consistent, redundant escaped spaces cleaned when desired).
  • DN attributes in destination entries are normalized in a way that can either preserve or normalize escaped spaces, depending on comparison needs.
    Business effect: the synchronizer now compares logical DNs instead of raw strings, eliminating false “differences” and unnecessary updates caused purely by encoding variations.

• Stable identifiers built from cleaned DNs
  When entries are read into beans, their mainIdentifier is now derived from a DN where problematic escaped‑space patterns are cleaned in a controlled way.
  This ensures that the same directory entry is recognized consistently across passes, even if its textual DN representation changes slightly (for example because of tooling or server upgrades).

Rename (MODRDN) robustness and collision handling

• Automatic recovery when renames cancel attribute changes
  Some LDAP servers cancel accompanying attribute modifications when a MODRDN is performed on the same entry.
  Junx mods introduce an internal queue that re‑schedules attribute modifications for entries that were just renamed, so that field‑level changes are not silently lost.
  From a business perspective, a “rename + attribute update” requested by the sync is now treated as an atomic intent: if the rename succeeds, the attribute updates are reliably reapplied later.

• Handling DN collisions during rename (NameAlreadyBound)
  When a target DN already exists (LDAP error 68), the rename is now resolved automatically by:

  • renaming the source entry to a temporary DN with a short random postfix, and
  • queuing a second rename that moves it to the final requested DN once it becomes available.
    This greatly reduces manual intervention during reorganizations (for example, swapping or reusing OU names) and keeps synchronization progressing even in the presence of naming conflicts.

• Controlled replay and service integration
  A small IRenameService interface and a thread‑local “replay mode” flag allow higher‑level components to:

  • drive reprocessing of queued MODRDN and attribute operations without risking infinite loops, and
  • count and report how many items were “reprocessed” separately from ordinary updates.
    The user experience is that difficult rename scenarios are automatically retried in a safe, bounded way instead of resulting in hard failures.

Connection roles, RootDSE insight and monitoring

• Per‑connection role detection (source vs destination)
  Each LDAP connection is now classified at runtime as “source”, “destination”, both or unused by scanning the configured tasks.
  This role is attached to the connection properties and reused in logging and statistics, so operators can immediately see which server a message refers to (for example ldap_src_* vs ldap_dst_*).

• Optional RootDSE statistics for replication awareness
  Two new connection‑level directives in the XSD and configuration (print_highestCommittedUSN, print_currentTime) control whether LSC will, on startup:

  • open a short‑lived RootDSE connection (respecting StartTLS settings),
  • read highestCommittedUSN and/or currentTime, and
  • log them and expose them as Java system properties (lsc.rootdse.<role>.*).
    This gives operations teams a lightweight snapshot of each directory’s replication watermark and clock at the time a run starts, without requiring external monitoring tooling.

• Aggregated RootDSE summary
  A small in‑memory summary of all RootDSE reads can be retrieved and used in final run statistics or external reporting.
  This makes it easy to annotate dashboards or run reports with “backend state” information that explains why a given sync saw more or fewer changes than expected.

Apply/commit semantics and performance

• Connection‑aware retry on communication errors
  The low‑level “apply” path for JNDI modifications has been wrapped with a single automatic reconnect‑and‑retry when a CommunicationException or “service unavailable” error is encountered.
  From the outside, this turns transient network glitches into at most a short delay, instead of immediate failure for the entire task.

• No‑op modification handling
  When a calculated MODIFY operation would result in “no attributes to change”, LSC now treats it as a successful no‑op instead of sending an empty modification to the directory.
  This reduces protocol noise and avoids confusing logs and corner‑case server behaviour around empty modifications.

• Configurable batch processing of pivots
  Tasks now expose an effective batchSize (with precedence: JVM system property lsc.batchSize, then task XML, then a safe default), and LDAP source services provide a forEachPivotBatch API.
  This allows large trees to be processed in fixed‑size batches, significantly reducing peak memory usage and making long‑running synchronizations more predictable.

Logging, LDIF output and diagnostics

• More accurate MODRDN LDIF entries
  LDIF logging for “change identifier” operations now parses the full DN and reconstructs newrdn and newsuperior fields using an LDAP‑aware parser instead of simple string slicing.
  As a result, LDIF logs for renames reflect exactly what was sent to the server, even in deeply nested trees or when RDN values contain special characters.

• DN‑aware difference evaluation for attributes
  Before scripts and policies decide whether an attribute on the destination “differs” from the source, DN attributes are normalized on both sides with the rules above.
  Business effect: reports and debug logs about “attribute X will be updated” now correspond to true semantic differences rather than encoding quirks.

Configuration schema extensions and backward compatibility

• Marking DN attributes explicitly in configuration
  The schema and configuration gained a dnAttributes list on LDAP connections.
  Attributes listed there are treated as DNs for normalization and comparison, while all others keep their original string semantics; this keeps existing profiles working as‑is while enabling precise DN logic where needed.

• Opt‑in RootDSE directives
  The XSD was extended with print_highestCommittedUSN and print_currentTime elements on LDAP connections.
  They default to false, so existing configurations are unaffected until these elements are explicitly enabled.

---

| 📜 LSC ORIGINAL README |

Full HTML documentation is available at https://lsc-project.org/