Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
6 changed files
with
286 additions
and
37 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,256 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <chapter version="5.0" xml:id="extensions" xmlns="http://docbook.org/ns/docbook" | ||
| xmlns:xlink="http://www.w3.org/1999/xlink" | ||
| xmlns:xi="http://www.w3.org/2001/XInclude" | ||
| xmlns:svg="http://www.w3.org/2000/svg" | ||
| xmlns:ns="http://docbook.org/ns/docbook" | ||
| xmlns:mml="http://www.w3.org/1998/Math/MathML" | ||
| xmlns:html="http://www.w3.org/1999/xhtml"> | ||
| <title>Extending SymmetricDS</title> | ||
|
|
||
|
|
||
| <para> | ||
| SymmetricDS may be extended via a plug-in like architecture where extension point interfaces | ||
| may be implemented by a custom class and registered with the synchronization engine. All supported extension | ||
| points extend the IExtensionPoint interface. The currently available extension points are documented in the following sections. | ||
| </para> | ||
| <para> | ||
| When the synchronization engine starts up, a Spring | ||
| post processor searches the Spring ApplicationContext for any registered classes which implement | ||
| IExtensionPoint. An IExtensionPoint designates whether it should be auto registered or not. If the extension point | ||
| is to be auto registered then the post processor registers the known interface with the appropriate service. | ||
| </para> | ||
| <para> | ||
| The INodeGroupExtensionPoint interface may be optionally implemented to designate that auto registered | ||
| extension points should only be auto registered with specific node groups. | ||
| <programlisting><![CDATA[/** | ||
| * Only apply this extension point to the 'root' node group. | ||
| */ | ||
| public String[] getNodeGroupIdsToApplyTo() { | ||
| return new String[] { "root" }; | ||
| } | ||
| ]]></programlisting> | ||
| </para> | ||
| <para> | ||
| SymmetricDS will look for Spring configured extensions in the application Classpath by importing any Spring | ||
| XML configuration files found matching the following pattern: <literal>META-INF/services/symmetric-*-ext.xml</literal>. When packaged in | ||
| a jar file the <literal>META-INF</literal> directory should be at the root of the jar file. When packaged in a war file, the <literal>META-INF</literal> directory | ||
| should be in the <literal>WEB-INF/classes</literal> directory. | ||
| </para> | ||
| <section id="configuration-parameter-filter"> | ||
| <title>IParameterFilter</title> | ||
| <para> | ||
| Parameter values can be specified in code using a parameter filter. Note that there can be only one parameter | ||
| filter per engine instance. The IParameterFilter replaces the deprecated IRuntimeConfig from prior releases. | ||
| <programlisting><![CDATA[public class MyParameterFilter | ||
| implements IParameterFilter, INodeGroupExtensionPoint { | ||
| /** | ||
| * Only apply this filter to stores | ||
| */ | ||
| public String[] getNodeGroupIdsToApplyTo() { | ||
| return new String[] { "store" }; | ||
| } | ||
| public String filterParameter(String key, String value) { | ||
| // look up a store number from an already existing properties file. | ||
| if (key.equals(ParameterConstants.EXTERNAL_ID)) { | ||
| return StoreProperties.getStoreProperties(). | ||
| getProperty(StoreProperties.STORE_NUMBER); | ||
| } | ||
| return value; | ||
| } | ||
| public boolean isAutoRegister() { | ||
| return true; | ||
| } | ||
| }]]></programlisting> | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-data-loader-filter"> | ||
| <title>IDataLoaderFilter</title> | ||
| <para> | ||
| Data can be filtered as it is loaded into the target database. It can also be | ||
| filtered when | ||
| it is extracted from the source database. | ||
|
|
||
| As data is loaded into the target database, a filter can change the | ||
| data in a column or save it somewhere else. It can also specify by the | ||
| return value of the function call that the data loader should continue on | ||
| and load the data (by returning true) or ignore it (by returning false). One | ||
| possible use of the filter might be to | ||
| route credit card data to a secure database and blank it out as it loads | ||
| into a less-restricted reporting database. | ||
| </para> | ||
| <para> | ||
| An IDataLoaderContext is passed to each of the callback methods. A new | ||
| context is created for each synchronization. The context provides methods to | ||
| lookup column indexes by column name, get table meta data, and access to | ||
| old data if the <literal>sync_column_level</literal> flag is enabled. The context also provides a means | ||
| to share data during a synchronization between different rows of data that are | ||
| committed in a database transaction and are in the same channel. It does so by | ||
| providing a context cache which can be populated by the extension point. | ||
| </para> | ||
| <para> | ||
| Many times the IDataLoaderFilter will be combined with the IBatchListener. The | ||
| XmlPublisherFilter (in the <literal>org.jumpmind.symmetric.ext</literal> package) is a good example | ||
| of using the combination of the two extension points in order to create XML messages | ||
| to be published to JMS. | ||
| </para> | ||
| <para> | ||
| A class implementing the IDataLoaderFilter interface is injected onto the | ||
| DataLoaderService in order to receive callbacks when data is inserted, | ||
| updated, or deleted. | ||
|
|
||
| <programlisting><![CDATA[public MyFilter implements IDataLoaderFilter { | ||
| public boolean isAutoRegister() { | ||
| return true; | ||
| } | ||
| public boolean filterInsert(IDataLoaderContext context, | ||
| String[] columnValues) { | ||
| return true; | ||
| } | ||
| public boolean filterUpdate(IDataLoaderContext context, | ||
| String[] columnValues, String[] keyValues) { | ||
| return true; | ||
| } | ||
| public void filterDelete(IDataLoaderContext context, | ||
| String[] keyValues) { | ||
| return true; | ||
| } | ||
| }]]></programlisting> | ||
| </para> | ||
| <para> | ||
| The filter class is specified as a Spring-managed bean. A custom Spring XML file | ||
| is specified as follows in a jar at <literal>META-INF/services/symmetric-myfilter-ext.xml</literal>. | ||
|
|
||
| <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> | ||
| <beans xmlns="http://www.springframework.org/schema/beans" | ||
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
| xmlns:context="http://www.springframework.org/schema/context" | ||
| xsi:schemaLocation="http://www.springframework.org/schema/beans | ||
| http://www.springframework.org/schema/beans/spring-beans-3.0.xsd | ||
| http://www.springframework.org/schema/context | ||
| http://www.springframework.org/schema/context/spring-context-3.0.xsd"> | ||
| <bean id="myFilter" class="com.mydomain.MyFilter"/> | ||
| </beans>]]></programlisting> | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-table-column-filter"> | ||
| <title>ITableColumnFilter</title> | ||
| <para> | ||
| Implement this extension point to filter out specific columns from | ||
| use by the dataloader. Only one column filter may be added per target table. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-batch-listener"> | ||
| <title>IBatchListener</title> | ||
| <para> | ||
| This extension point is called whenever a batch has completed loading but before | ||
| the transaction has committed. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-acknowledge-event-listener"> | ||
| <title>IAcknowledgeEventListener</title> | ||
| <para> | ||
| Implement this extension point to receive callback events when a batch is acknowledged. | ||
| The callback for this listener happens at the point of extraction. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-reload-listener"> | ||
| <title>IReloadListener</title> | ||
| <para> | ||
| Implement this extension point to listen in and take | ||
| action before or after a reload is requested for a Node. The callback for this listener | ||
| happens at the point of extraction. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-extractor-filter"> | ||
| <title>IExtractorFilter</title> | ||
| <para> | ||
| This extension point is called after data has been extracted, but before it has been streamed. It | ||
| has the ability to inspect each row of data to take some action and indicate, if necessary, that the | ||
| row should not be streamed. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-sync-url-extension"> | ||
| <title>ISyncUrlExtension</title> | ||
| <para> | ||
| This extension point is used to select an appropriate URL based on | ||
| the URI provided in the <literal>sync_url</literal> column of <literal>sym_node</literal>. | ||
| </para> | ||
| <para> | ||
| To use this extension point configure the sync_url for a node with the | ||
| protocol of ext://beanName. The beanName is the name you give the extension | ||
| point in the extension xml file. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-node-id-generator"> | ||
| <title>INodeIdGenerator</title> | ||
| <para> | ||
| This extension point allows SymmetricDS users to implement their own algorithms for how | ||
| node ids and passwords are generated or selected during the registration process. There may be | ||
| only one node generator per SymmetricDS instance. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-trigger-creation-listener"> | ||
| <title>ITriggerCreationListener</title> | ||
| <para> | ||
| Implement this extension point to get status callbacks during trigger creation. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-batch-algorithm"> | ||
| <title>IBatchAlgorithm</title> | ||
| <para> | ||
| Implement this extension point and set the name of the Spring bean on the batch_algorithm column of the Channel table to use. | ||
| This extension point gives fine grained control over how a channel is batched. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-data-router"> | ||
| <title>IDataRouter</title> | ||
| <para> | ||
| Implement this extension point and set the name of the Spring bean on the router_type column | ||
| of the Router table to use. This extension point gives the ability to programatically decide | ||
| which nodes data should be routed to. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-heartbeat-listener"> | ||
| <title>IHeartbeatListener</title> | ||
| <para> | ||
| Implement this extension point to get callbacks during the heartbeat job. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-offline-client-listener"> | ||
| <title>IOfflineClientListener</title> | ||
| <para> | ||
| Implement this extension point to get callbacks for offline events on client nodes. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-offline-server-listener"> | ||
| <title>IOfflineServerListener</title> | ||
| <para> | ||
| Implement this extension point to get callbacks for offline events detected on a server node during monitoring of client nodes. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-node-password"> | ||
| <title>INodePasswordFilter</title> | ||
| <para> | ||
| Implement this extension point to intercept the saving and rendering of the node password. | ||
| </para> | ||
| </section> | ||
| <section id="configuration-extensions-servlets"> | ||
| <title>IServletExtension</title> | ||
| <para> | ||
| Implement this extension point to allow additional Servlets to be registered with SymmetricDS. This is probably only | ||
| useful if SymmetricDS is running in standalone or embedded mode. | ||
| </para> | ||
| </section> | ||
| </chapter> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.