/* * CDDL HEADER START * * The contents of this file are subject to the terms of the * Common Development and Distribution License, Version 1.0 only * (the "License"). You may not use this file except in compliance * with the License. * * You can obtain a copy of the license at * docs/licenses/cddl.txt * or http://www.opensource.org/licenses/cddl1.php. * See the License for the specific language governing permissions * and limitations under the License. * * When distributing Covered Code, include this CDDL HEADER in each * file and include the License file at * docs/licenses/cddl.txt. If applicable, * add the following below this CDDL HEADER, with the fields enclosed * by brackets "[]" replaced with your own identifying information: * Portions Copyright [yyyy] [name of copyright owner] * * CDDL HEADER END * * * Copyright 2010-2018 Ping Identity Corporation */ package com.unboundid.directory.sdk.examples; import java.util.ArrayList; import java.util.Arrays; import java.util.Collections; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; import com.unboundid.directory.sdk.sync.api.SyncDestination; import com.unboundid.directory.sdk.sync.config.SyncDestinationConfig; import com.unboundid.directory.sdk.sync.types.EndpointException; import com.unboundid.directory.sdk.sync.types.SyncOperation; import com.unboundid.directory.sdk.sync.types.SyncServerContext; import com.unboundid.util.args.ArgumentException; import com.unboundid.util.args.ArgumentParser; import com.unboundid.util.args.DNArgument; import com.unboundid.util.args.IntegerArgument; import com.unboundid.util.args.StringArgument; import com.unboundid.ldap.sdk.Attribute; import com.unboundid.ldap.sdk.ChangeLogEntry; import com.unboundid.ldap.sdk.DN; import com.unboundid.ldap.sdk.Entry; import com.unboundid.ldap.sdk.LDAPConnection; import com.unboundid.ldap.sdk.LDAPException; import com.unboundid.ldap.sdk.LDAPThreadLocalConnectionPool; import com.unboundid.ldap.sdk.Modification; import com.unboundid.ldap.sdk.RDN; import com.unboundid.ldap.sdk.ResultCode; /** * This example provides an implementation of SyncDestination which pushes * changes to a target LDAP directory server. This can optionally be used as the * destination of a Sync Pipe in notification mode. Its configuration arguments * require the host, port, and credentials for a target LDAP directory, to which * changes are pushed straight through. The fetchEntry() method is implemented * for reference, although it is not used when a Sync Pipe is in * <i>notification</i> mode. */ public class ExampleSyncDestination extends SyncDestination { // The general configuration for this Sync Destination private volatile SyncDestinationConfig config; // The server context for the server in which this extension is running private SyncServerContext serverContext; // A pool of connections to the destination LDAP server private LDAPThreadLocalConnectionPool connectionPool; /** * Retrieves a human-readable name for this extension. * * @return A human-readable name for this extension. */ @Override public String getExtensionName() { return "Example Sync Destination"; } /** * Retrieves a human-readable description for this extension. Each element * of the array that is returned will be considered a separate paragraph in * generated documentation. * * @return A human-readable description for this extension, or {@code null} * or an empty array if no description should be available. */ @Override public String[] getExtensionDescription() { return new String[] { "This implementation serves as an example that may be used to " + "demonstrate the process for creating a third-party Sync Destination " + "extension. It will forward notifications from the Synchronization " + "Server on to another LDAP directory server." }; } /** * {@inheritDoc} */ @Override public void defineConfigArguments(final ArgumentParser parser) throws ArgumentException { StringArgument hostArg = new StringArgument( null, "host", true, 1, "{hostname}", "The hostname of the target directory " + "server to which notifications should be " + "sent."); IntegerArgument portArg = new IntegerArgument( null, "port", true, 1, "{port}", "The port number of the target directory " + "server to which notifications should be " + "sent."); DNArgument bindDNArg = new DNArgument( null, "bind-dn", true, 1, "{bind-DN}", "The bind DN to use for requests to the " + "target directory server."); StringArgument bindPasswordArg = new StringArgument( null, "bind-password", true, 1, "{bind-password}", "The bind password to " + "use for requests to the target directory " + "server."); parser.addArgument(hostArg); parser.addArgument(portArg); parser.addArgument(bindDNArg); parser.addArgument(bindPasswordArg); } /** * Retrieves a map containing examples of configurations that may be used for * this extension. The map key should be a list of sample arguments, and the * corresponding value should be a description of the behavior that will be * exhibited by the extension when used with that configuration. * * @return A map containing examples of configurations that may be used for * this extension. It may be {@code null} or empty if there should * not be any example argument sets. */ @Override public Map<List<String>, String> getExamplesArgumentSets() { final LinkedHashMap<List<String>,String> exampleMap = new LinkedHashMap<List<String>,String>(1); exampleMap.put( Arrays.asList("host=sample.host.com", "port=1389", "bind-dn=cn=Sync User", "bind-password=p@ssW0rd"), "Push changes to ldap://sample.host.com:1389, using the " + "Sync User account."); return exampleMap; } /** * Initializes this sync destination. This hook is called when a Sync Pipe * first starts up, or when the <i>resync</i> process first starts up. Any * initialization should be performed here. This method should generally store * the {@link SyncServerContext} in a class * member so that it can be used elsewhere in the implementation. * * @param serverContext A handle to the server context for the server in * which this extension is running. Extensions should * typically store this in a class member. * @param config The general configuration for this object. * @param parser The argument parser which has been initialized from * the configuration for this sync destination. * @throws EndpointException * if a problem occurs while initializing this * sync destination. */ @Override() public void initializeSyncDestination( final SyncServerContext serverContext, final SyncDestinationConfig config, final ArgumentParser parser) throws EndpointException { this.serverContext = serverContext; this.config = config; StringArgument hostArg = (StringArgument) parser.getNamedArgument("host"); IntegerArgument portArg = (IntegerArgument) parser.getNamedArgument("port"); DNArgument bindDNArg = (DNArgument) parser.getNamedArgument("bind-dn"); StringArgument passwordArg = (StringArgument) parser.getNamedArgument("bind-password"); String host = hostArg.getValue(); int port = portArg.getValue(); DN bindDN = bindDNArg.getValue(); String bindPassword = passwordArg.getValue(); try { LDAPConnection conn = new LDAPConnection(host, port, bindDN.toString(), bindPassword); connectionPool = new LDAPThreadLocalConnectionPool(conn); } catch(LDAPException e) { throw new EndpointException(e); } } /** * This hook is called when a Sync Pipe shuts down, or when the <i>resync</i> * process shuts down. Any clean-up of this sync destination should be * performed here. */ @Override public void finalizeSyncDestination() { if(connectionPool != null) { connectionPool.close(); } } /** * Return the URL or path identifying the destination endpoint * to which this extension is transmitting data. This is used for logging * purposes only, so it could just be a server name or hostname and port, etc. * * @return the path to the destination endpoint */ @Override public String getCurrentEndpointURL() { if(connectionPool == null) { return "not connected"; } LDAPConnection conn = null; try { conn = connectionPool.getConnection(); return conn.getConnectedAddress() + ":" + conn.getConnectedPort(); } catch (LDAPException e) { return "not connected"; } finally { connectionPool.releaseConnection(conn); } } /** * Return a full destination entry (in LDAP form) from the destination * endpoint, corresponding to the source {@link Entry} that is passed in. * This method should perform any queries necessary to gather the latest * values for all the attributes to be synchronized and return them in an * Entry. * <p> * This method only needs to be implemented if the 'synchronization-mode' on * the Sync Pipe is set to 'standard'. If it is set to 'notification', this * method will never be called, and the pipe will pass changes straight * through to one of {@link #createEntry}, {@link #modifyEntry}, or * {@link #deleteEntry}. * <p> * Note that the if the source entry was renamed (see * {@link SyncOperation#isModifyDN}), the * <code>destEntryMappedFromSrc</code> will have the new DN; the old DN can * be obtained by calling * {@link SyncOperation#getDestinationEntryBeforeChange()} and getting the DN * from there. This method should return the entry in its existing form * (i.e. with the old DN, before it is changed). * <p> * This method <b>must be thread safe</b>, as it will be called repeatedly and * concurrently by each of the Sync Pipe worker threads as they process * entries. * @param destEntryMappedFromSrc * the LDAP entry which corresponds to the destination "entry" to * fetch * @param operation * the sync operation for this change * @return a list containing the full LDAP entries that matched this search * (there may be more than one), or an empty list if no such entry * exists * @throws EndpointException * if there is an error fetching the entry */ @Override public List<Entry> fetchEntry(final Entry destEntryMappedFromSrc, final SyncOperation operation) throws EndpointException { List<Entry> entries = new ArrayList<Entry>(); try { Entry e = connectionPool.getEntry(destEntryMappedFromSrc.getDN()); if(e != null) { entries.add(e); } return entries; } catch(LDAPException e) { if(e.getResultCode().equals(ResultCode.NO_SUCH_OBJECT)) { return Collections.emptyList(); } throw new EndpointException(e); } } /** * Creates a full destination "entry", corresponding to the LDAP * {@link Entry} that is passed in. This method is responsible for * transforming the contents of the entry into the desired format and * transmitting it to the target destination. It should perform any inserts or * updates necessary to make sure the entry is fully created on the * destination endpoint. * <p> * This method <b>must be thread safe</b>, as it will be called repeatedly and * concurrently by the Sync Pipe worker threads as they process CREATE * operations. * @param entryToCreate * the LDAP entry which corresponds to the destination * "entry" to create * @param operation * the sync operation for this change * @throws EndpointException * if there is an error creating the entry */ @Override public void createEntry(final Entry entryToCreate, final SyncOperation operation) throws EndpointException { if (shouldIgnore(entryToCreate, operation)) { return; } try { connectionPool.add(entryToCreate); operation.logInfo("Created entry: " + entryToCreate.getDN()); } catch(LDAPException e) { throw new EndpointException(e); } } /** * Modify an "entry" on the destination, corresponding to the LDAP * {@link Entry} that is passed in. This method is responsible for * transforming the contents of the entry into the desired format and * transmitting it to the target destination. It may perform multiple updates * (including inserting or deleting other attributes) in order to fully * synchronize the entire entry on the destination endpoint. * <p> * Note that the if the source entry was renamed (see * {@link SyncOperation#isModifyDN}), the * <code>fetchedDestEntry</code> will have the old DN; the new DN can * be obtained by calling * {@link SyncOperation#getDestinationEntryAfterChange()} and getting the DN * from there. * <p> * This method <b>must be thread safe</b>, as it will be called repeatedly and * concurrently by the Sync Pipe worker threads as they process MODIFY * operations. * @param entryToModify * the LDAP entry which corresponds to the destination * "entry" to modify. If the synchronization mode is 'standard', * this will be the entry that was returned by {@link #fetchEntry}; * otherwise if the synchronization mode is 'notification', this * will be the destination entry mapped from the source entry, before * changes are applied. * @param modsToApply * a list of Modification objects which should be applied; these will * have any configured attribute mappings already applied * @param operation * the sync operation for this change * @throws EndpointException * if there is an error modifying the entry */ @Override public void modifyEntry(final Entry entryToModify, final List<Modification> modsToApply, final SyncOperation operation) throws EndpointException { if (shouldIgnore(entryToModify, operation)) { return; } if(operation.isModifyDN()) { Entry destEntryAfterChange = operation.getDestinationEntryAfterChange(); try { String newRDN = destEntryAfterChange.getRDN().toString(); String newSuperior = destEntryAfterChange.getParentDNString(); boolean deleteOldRdn = operation.getChangeLogEntry() .getAttributeValueAsBoolean(ChangeLogEntry.ATTR_DELETE_OLD_RDN); connectionPool.modifyDN(entryToModify.getDN(), newRDN, deleteOldRdn, newSuperior); operation.logInfo("Modified DN " + entryToModify.getDN() + " to " + destEntryAfterChange.getDN()); } catch(LDAPException e) { throw new EndpointException(e); } } else if(!modsToApply.isEmpty()) { try { connectionPool.modify(entryToModify.getDN(), modsToApply); operation.logInfo("Modified entry: " + entryToModify.getDN()); } catch(LDAPException e) { throw new EndpointException(e); } } } /** * Delete a full "entry" from the destination, corresponding to the LDAP * {@link Entry} that is passed in. This method may perform multiple deletes * or updates if necessary to fully delete the entry from the destination * endpoint. * <p> * This method <b>must be thread safe</b>, as it will be called repeatedly and * concurrently by the Sync Pipe worker threads as they process DELETE * operations. * @param entryToDelete * the LDAP entry which corresponds to the destination * "entry" to delete. If the synchronization mode is 'standard', * this will be the entry that was returned by {@link #fetchEntry}; * otherwise if the synchronization mode is 'notification', this * will be the mapped destination entry. * @param operation * the sync operation for this change * @throws EndpointException * if there is an error deleting the entry */ @Override public void deleteEntry(final Entry entryToDelete, final SyncOperation operation) throws EndpointException { if (shouldIgnore(entryToDelete, operation)) { return; } try { connectionPool.delete(entryToDelete.getDN()); operation.logInfo("Deleted entry: " + entryToDelete.getDN()); } catch(LDAPException e) { throw new EndpointException(e); } } /** * Entries that have 'cn=ignore user' as the RDN will be ignored. This method * demonstrates using SyncOperation#setIgnored() to direct the Sync Server to * ignore certain types of changes and isn't tied to a true use case. * * @param entry * The entry to to be checked. * @param operation * The sync operation. * @return {@code true} if the entry should be ignored. * @throws EndpointException * If the RDN could not be retrieved. */ protected boolean shouldIgnore(final Entry entry, final SyncOperation operation) throws EndpointException { try { final RDN rdn = entry.getRDN(); for (Attribute attribute : rdn.getAttributes()) { if (attribute.getName().equalsIgnoreCase("cn") && attribute.getValue().equals("ignore user")) { // Setting this prevents this operation from being included in the // monitor statistics. operation.setIgnored(); return true; } } } catch(LDAPException e) { throw new EndpointException(e); } return false; } }