PingDirectory

Implement a JDBC sync source

The JDBCSyncSource abstract class must be implemented to synchronize data from a relational database. Because PingDataSync is Lightweight Directory Access Protocol (LDAP)-centric, this class enables database content to be converted into LDAP entries. For more detailed information on the class, see the Server SDK Javadoc.

When using custom Java database connectivity (JDBC) sources, SQL statements cannot be called unless JDBC drivers are set in the java.properties file. For example:

start-server.java-args=<…​> -Djdbc.drivers=com.microsoft.sqlserver.jdbc.SQLServerDriver

The admin must run dsjavaproperties for the update to the java.properties file to take effect.

The extension imports classes from the Java API, LDAP SDK for Java API, and the Server SDK. Depending on the data, implement the following methods:

  • initializeJDBCSyncSource – Called when a Sync Pipe first starts, or when the resync process starts. Any initialization should be performed here, such as creating internal data structures and setting up variables.

  • finalizeJDBCSyncSource – Called when a Sync Pipe stops, or when the resync process stops. Any clean up should be performed here, and all internal resources should be freed.

  • setStartpoint – Sets the starting point for synchronization by identifying the starting point in the change log. This method should cause all changes previous to the specified start point to be disregarded and only changes after that point to be returned by the getNextBatchOfChanges method. There are several different startpoint types (see SetStartpointOptions in the Server SDK), and this implementation is not required to support them all. If the specified startpoint type is unsupported, this method throws an exception (IllegalArgumentException). This method can be called from two different contexts: when the realtime-syncset-startpoint command is used (the Sync Pipe is required to be stopped) or immediately after a connection is established to the source server.

    The RESUME_AT_SERIALIZABLE startpoint type must be supported. This method is used when a Sync Pipe first starts and loads its state from disk.

  • getStartpoint – Gets the current value of the startpoint for change detection.

  • fetchEntry – Returns a full source entry (in LDAP form) from the database, corresponding to the DatabaseChangeRecord object that is passed. The resync command also uses this class to retrieve entries.

  • acknowledgeCompletedOps– Provides a means for PingDataSync to acknowledge to the database which operations have completed processing.

    The internal value for the startpoint should only be updated after a synchronization operation is acknowledged in to this script (through this method). If not, changes could be missed when PingDataSync is restarted.

  • getNextBatchOfChanges – Retrieves the next set of changes for processing. The method also provides a generic means to limit the size of the result set.

  • listAllEntries – Used by the resync command to get a listing of all entries.

  • cleanupChangelog – In general, we recommend implementing a cleanupChangelog method, so that PingDataSync can purge old records from the change log table, based on a configurable age.

See the config/jdbc/samples directory for example script implementations and the Server SDK Javadoc for more detailed information on each method.