First, it is important to understand what "replication" means and why it exists.
All configuration for each sipXecs service is created by sipXconfig and replicated to the system where the service runs through sipXsupervisor.

Replication of service configurations

In sipXconfig, the managed services configurations are kept in the database for presentation purposes. Each service keeps its configuration in xml files found at specific locations. A client may alter a service configuration via sipXconfig's UI or REST services. Obviously the configuration of each service must be kept in synch with sipXconfig's database. Thus a configuration change in sipXconfig will trigger a replication of the service's configuration. In particular cases, a service restart must be triggered in order for the new configuration to take effect.

Replications are triggered in 2 ways: in bulk, via one of the ServiceConfigurator.replicateServiceConfig() overloaded methods or manually with the help of org.sipfoundry.sipxconfig.admin.commserver.SipxReplicationContext. In the first case all the configuration files are replicated, in the second we can trigger specific file replciation. Ideally all configurations should be replicated by the ServiceConfigurator, but there are cases when a single replication is performed.

Datasets replications

In addition to service configurations there is another type of replications: replication of datasets. TBD

Other replications

Not only sipXecs services configurations and data sets need to be replicated. In addition to those, other entities use configuration files that sipXconfig must provide via the replication mechanism. Some examples are: dial plans, alarms configuration, etc.

Configuring replications

Service configs

In sipXconfig, services are configured in service.beans.xml. Here, amongst other properties, a list of "service configurations" is kept for each service.

  <bean id="sipxProxyService" class="org.sipfoundry.sipxconfig.service.SipxProxyService" parent="sipxService"
    scope="prototype">
    <property name="processName" value="SIPXProxy" />
    <property name="modelName" value="sipxproxy.xml" />
    <property name="modelDir" value="sipxproxy" />
    <property name="editable" value="true" />
    <property name="configurations">
      <list>
        <ref bean="sipxProxyConfiguration" />
        <ref bean="peerIdentitiesConfiguration" />
      </list>
    </property>
    <property name="bundles">
      <set>
        <ref bean="primarySipRouterBundle" />
        <ref bean="redundantSipRouterBundle" />
      </set>
    </property>
  </bean>

Each "configuration" is configured separately:

  <bean id="sipxProxyConfiguration" class="org.sipfoundry.sipxconfig.service.SipxProxyConfiguration" scope="prototype"
    parent="serviceConfigurationFile">
    <property name="template" value="sipxproxy/sipXproxy-config.vm" />
    <property name="name" value="sipXproxy-config" />
    <property name="sipxServiceManager" ref="sipxServiceManager" />
  </bean>

  <bean id="peerIdentitiesConfiguration" class="org.sipfoundry.sipxconfig.service.PeerIdentitiesConfiguration" scope="prototype"
    parent="defaultConfigurationFile">
    <property name="name" value="peeridentities.xml"/>
    <property name="tlsPeerManager" ref="tlsPeerManager" />
    <property name="restartRequired" value="true" />
  </bean>

Datasets

org.sipfoundry.sipxconfig.admin.commserver.imdb.DataSet holds an enumeration of datasets. Dataset beans are registered in Spring in commserver.beans.xml. Here, the beans hold the configuration of the business beans that do the replication. These beans are implementations of org.sipfoundry.sipxconfig.admin.commserver.imdb.DataSetGenerator abstract class.

The other replications are configured similarly with the service configuration.

Lazy vs eager replication

Some operations may involve modifying a large chunk of entities, each of this modification triggering a replication. For instance, think about importing users from an LDAP server. Each save of a new user should be replicated in various configuration files. So, instead of doing a replication for each operation, the concept of lazy replication was introduced.

org.sipfoundry.sipxconfig.admin.commserver.LazySipxReplicationContextImpl is the implementation of the SipxReplicationContext that takes care of the lazy replications. Replication jobs are kept in an ArrayList of ReplicationTasks. A worker thread sleeps while waiting for something to be done and when there is, it is notified, sleeps for a bit and then it triggers the queued replications.

In sipXconfig all replications are lazy, except dial plans.

Writing XML files

All configuration files extend the abstract class org.sipfoundry.sipxconfig.admin.AbstractConfigurationFile. org.sipfoundry.sipxconfig.admin.TemplateConfigurationFile is a Common base class for all configuration files generators that use Velocity templating engine.

The service configuration files are a particular case of the TemplateConfigurationFile mentioned above. The configuration bean is registered in Spring as a child of serviceConfigurationFile bean. The class itself extends org.sipfoundry.sipxconfig.admin.TemplateConfigurationFile. Spring injects the sipxServiceManager into the bean. In the above example sipxProxyConfiguration is a serviceConfigurationFile. It uses sipXproxy-config.vm as the Velocity template. Of course other parameters can be configured on a case by case scenario.

Another common way to write XML files is to use org.dom4j.Document. In the above example peerIdentitiesConfiguration is configured as a child of defaultConfigurationFile. The class itself extends org.sipfoundry.sipxconfig.admin.dialplan.config.XmlFile and it must override XmlFile.getDocument() method and return a dom4j document.

Other types of configuration files can be viewed by checking out the type hierarchy of org.sipfoundry.sipxconfig.admin.AbstractConfigurationFile.

isReplicable() and isRestartRequired()

Replication triggers

Short info. See Replication triggers

Proposed changes for future versions