diff --git a/symmetric/src/docbook/configuration.xml b/symmetric/src/docbook/configuration.xml index b54f2435da..6248c8b344 100644 --- a/symmetric/src/docbook/configuration.xml +++ b/symmetric/src/docbook/configuration.xml @@ -753,14 +753,28 @@ values
Dead Triggers - - Normally a Trigger is specified to capture data changes to a table and send them to - a target Node Group. A "dead" Trigger is one that does not capture data changes. + + Occasionally the decision of what data to load initially results in additional triggers. These triggers, known as Dead Triggers, + are configured such that they do not capture any data changes. + A "dead" Trigger is one that does not capture data changes. In other words, the sync_on_insert, sync_on_update, and sync_on_delete properties - for the Trigger are all set to false. However, because the Trigger is specified, - it will + for the Trigger are all set to false. However, since the Trigger is specified, it will be included in the initial load of data for target Nodes. + + Why might you need a Dead Trigger? + A dead Trigger might be used to load a read-only lookup table, for example. It could also + be used + to load a table that needs populated with example or default data. + Another use is a recovery load of data for tables that have a single direction + of synchronization. For example, a retail store records sales transaction that + synchronize in one direction by trickling back to the central office. + If the retail store needs to recover all the sales transactions from the central office, + they can be sent + are part of an initial load from the central office by setting up dead Triggers + that "sync" in that direction. + + The following SQL statement sets up a non-syncing dead Trigger that sends the sale_transaction table to the "store" Node Group from the "corp" Node Group during diff --git a/symmetric/src/docbook/extensions.xml b/symmetric/src/docbook/extensions.xml new file mode 100644 index 0000000000..83f6a9f07a --- /dev/null +++ b/symmetric/src/docbook/extensions.xml @@ -0,0 +1,256 @@ + + + Extending SymmetricDS + + + + 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. + + + 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. + + + The INodeGroupExtensionPoint interface may be optionally implemented to designate that auto registered + extension points should only be auto registered with specific node groups. + + + + SymmetricDS will look for Spring configured extensions in the application Classpath by importing any Spring + XML configuration files found matching the following pattern: META-INF/services/symmetric-*-ext.xml. When packaged in + a jar file the META-INF directory should be at the root of the jar file. When packaged in a war file, the META-INF directory + should be in the WEB-INF/classes directory. + +
+ IParameterFilter + + 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. + + +
+
+ IDataLoaderFilter + + 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. + + + 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 sync_column_level 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. + + + Many times the IDataLoaderFilter will be combined with the IBatchListener. The + XmlPublisherFilter (in the org.jumpmind.symmetric.ext 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. + + + A class implementing the IDataLoaderFilter interface is injected onto the + DataLoaderService in order to receive callbacks when data is inserted, + updated, or deleted. + + + + + The filter class is specified as a Spring-managed bean. A custom Spring XML file + is specified as follows in a jar at META-INF/services/symmetric-myfilter-ext.xml. + + + + + + +]]> + +
+
+ ITableColumnFilter + + Implement this extension point to filter out specific columns from + use by the dataloader. Only one column filter may be added per target table. + +
+
+ IBatchListener + + This extension point is called whenever a batch has completed loading but before + the transaction has committed. + +
+
+ IAcknowledgeEventListener + + Implement this extension point to receive callback events when a batch is acknowledged. + The callback for this listener happens at the point of extraction. + +
+
+ IReloadListener + + 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. + +
+
+ IExtractorFilter + + 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. + +
+
+ ISyncUrlExtension + + This extension point is used to select an appropriate URL based on + the URI provided in the sync_url column of sym_node. + + + 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. + +
+
+ INodeIdGenerator + + 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. + +
+
+ ITriggerCreationListener + + Implement this extension point to get status callbacks during trigger creation. + +
+
+ IBatchAlgorithm + + 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. + +
+
+ IDataRouter + + 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. + +
+
+ IHeartbeatListener + + Implement this extension point to get callbacks during the heartbeat job. + +
+
+ IOfflineClientListener + + Implement this extension point to get callbacks for offline events on client nodes. + +
+
+ IOfflineServerListener + + Implement this extension point to get callbacks for offline events detected on a server node during monitoring of client nodes. + +
+
+ INodePasswordFilter + + Implement this extension point to intercept the saving and rendering of the node password. + +
+
+ IServletExtension + + 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. + +
+ \ No newline at end of file diff --git a/symmetric/src/docbook/introduction.xml b/symmetric/src/docbook/introduction.xml index 4d048c36dd..f674d5df01 100644 --- a/symmetric/src/docbook/introduction.xml +++ b/symmetric/src/docbook/introduction.xml @@ -2,8 +2,7 @@ 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"> Introduction -
- Overview + This User Guide will introduce both basic and advanced concepts in the configuration of SymmetricDS. By the end of this chapter, you will have a better understanding of SymmetricDS' capabilities, and many of its basic concepts. This chapter also includes a hands-on, step-by-step, tutorial meant to demonstrate some of @@ -178,7 +177,7 @@ used to send data. The data payload can be any SQL statement. The event is processed and acknowledged just like any other event type.
-
+
System Requirements @@ -286,6 +285,4 @@ statistics, have been moved over to the batch tables themselves. The statistics in the batch tables now always represent the latest synchronization attempt.
- - \ No newline at end of file diff --git a/symmetric/src/docbook/planning.xml b/symmetric/src/docbook/planning.xml index ff2cbe9ba5..786a4665ae 100644 --- a/symmetric/src/docbook/planning.xml +++ b/symmetric/src/docbook/planning.xml @@ -1,5 +1,5 @@ - @@ -280,7 +280,7 @@
- Planning Initial Loads and Dead Triggers + Planning Initial Loads The mapping between Triggers and Routers defines more than just the many-to-many relationship between your Triggers and your Routers. It also defines two aspects of how initial loads occur, so now is a good time to plan how your Initial Loads will work. @@ -293,25 +293,7 @@ - - Occasionally the decision of what data to load initially results in additional triggers. These triggers, known as Dead Triggers, - are configured such that they do not capture any data changes. In other words, their settings for synchronizing on - updates, inserts, and deletes are all set to false. However, since the Trigger is specified, it will - be included in the initial load of data for target Nodes. - - - Why might you need a Dead Trigger? - A dead Trigger might be used to load a read-only lookup table, for example. It could also - be used - to load a table that needs populated with example or default data. - Another use is a recovery load of data for tables that have a single direction - of synchronization. For example, a retail store records sales transaction that - synchronize in one direction by trickling back to the central office. - If the retail store needs to recover all the sales transactions from the central office, - they can be sent - are part of an initial load from the central office by setting up dead Triggers - that "sync" in that direction. - +
diff --git a/symmetric/src/docbook/tutorial.xml b/symmetric/src/docbook/tutorial.xml index 3603e0c570..dd0eaa9ae5 100644 --- a/symmetric/src/docbook/tutorial.xml +++ b/symmetric/src/docbook/tutorial.xml @@ -1,9 +1,7 @@ - -
- SymmetricDS Hands-on Tutorial + Hands-on Tutorial Now that several of the features of SymmetricDS have been discussed, a quick working example of SymmetricDS is in order. This section contains a hands-on tutorial that demonstrates how to synchronize a sample database between two running instances of SymmetricDS. This example models a retail business that has a central office database (called "root") and @@ -415,4 +413,4 @@ registration.url=http://localhost:8080/sync]]>
- \ No newline at end of file + \ No newline at end of file diff --git a/symmetric/src/docbook/user-guide.xml b/symmetric/src/docbook/user-guide.xml index 41de455c4f..6a1318cd10 100644 --- a/symmetric/src/docbook/user-guide.xml +++ b/symmetric/src/docbook/user-guide.xml @@ -54,9 +54,11 @@ + +