Create the JDBC extension
The Java database connectivity (JDBC) extension implementation must be written in Java or in the Groovy scripting language. Consult the Server SDK documentation for details on how to build and deploy extensions. The examples in this guide use Java. Java extensions are more strict and will catch programming errors during compile time rather than at runtime. Groovy is more flexible and can accomplish more with less lines of code.
Groovy scripts must reside in the /lib/groovy-scripted-extensions
directory (Java implementations reside in /lib/extensions
), which can also contain other plugins built using the Server SDK. If a script declares a package name, it must live under the corresponding folder hierarchy, just like a Java class. For example, to use a script class called ComplexJDBCSyncSource
whose package is com.unboundid.examples.oracle
, place it in /lib/groovy-scripted-extensions/com/unboundid/examples/oracleand
set the script-class
property on the Sync Source to com.unboundid.examples.oracle.ComplexJDBCSyncSource
. There are a few reference implementations provided in the config/jdbc/samples
directory. Use the manage-extension
tool in the bin
directory, or bat
(Windows), to install or update the extension. See the Server SDK extensions section for more information.
When using custom JDBC endpoints, 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.
Any changes to an existing script require a manual Sync Pipe restart. Any configuration change automatically restarts the affected Sync Pipe. |
The default libraries available on the classpath to the script implementation include:
-
Groovy
-
Lightweight Directory Access Protocol (LDAP) SDK for Java
-
JRE
Logging from within a script can be done with the Server SDK’s ServerContext
abstract class. Some of the ServerContext
methods are not available when the resync
tool runs, because it runs outside of the PingDataSync process. Any logging during a resync
operation is saved to the logs/tools/resync.log
file.
Implement a JDBC sync source
The JDBCSyncSource
abstract class must be implemented to synchronize data from a relational database. Because PingDataSync is 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 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 theresync
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 theresync
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 thegetNextBatchOfChanges
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 therealtime-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 theDatabaseChangeRecord
object that is passed. Theresync
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 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 theresync
command to get a listing of all entries. -
cleanupChangelog
– In general, we recommend implementing acleanupChangelog
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.
Implement a JDBC sync destination
The JDBCSyncDestination
abstract class must be implemented to synchronize data into a relational database. The class enables converting LDAP content to database content. The extension imports classes from the Java API, LDAP SDK for Java API, and the Server SDK, depending on the database configuration.
When using custom JDBC destinations, 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.
Implement the following methods in the script:
-
initializeJDBCSyncDestination
– Called when a Sync Pipe starts, or when theresync
process starts. Any initialization should be performed here, such as creating internal data structures and setting up variables. -
finalizeJDBCSyncDestination
– Called when a Sync Pipe stops, or when theresync
process stops. Any clean up should be performed here, and all internal resources should be freed. -
createEntry
– Creates a full database entry (or row), corresponding to the LDAP entry that is passed in. -
modifyEntry
– Modifies a database entry, corresponding to the LDAP entry that is passed in. -
fetchEntry
– Returns a full destination database entry (in LDAP form), corresponding to the source entry that is passed in. -
deleteEntry
– Deletes a full entry from the database, corresponding to the LDAP entry that is passed in.
For more detailed information on the abstract class, see the Server SDK Javadoc.