Newton System Manager

The Newton System Manager is used to manage how many and which sort of SCA composites are installed in a Newton Fabric. The system manager is built using a collection of sub-components built from SCA documents.

A specific system manager can manage many systems. The system manager uses a document called a System Descriptor to define the set of composites that make up a system.

The system manager has two lifecycle events related to systems; manage and retire. The first time a system manager is asked to manage a system it reads the system document and builds the set of composites that it defines. It then passes these composites to the provisioner for installation somewhere within the Fabric.

If a system administrator wants to make a change to a given system he/she simply updates the system document and asks the system manager to manage the new document. A system manager treats two system documents as referring to the same system if their names match.

On update the system manager figures out the delta between the current deployment and the new requirement and actions the change only. So if a system is being increased from one to ten nodes then nine new instances are created and the existing one is reused. If it is being reduced in size from ten nodes to five nodes then five nodes are picked for uninstall and the rest remain in place.

When the system administrator no longer wants the system manager to deploy a specific system he/she simply retires the system and the system manager garbage collects all resources previously allocated.

Importantly the system document does not have to specify a static set of composites. It is possible to build dynamic behaviours by extending the ReplicationHandler interface and plugging the replication handler into the local osgi registry of the Newton process.

ReplicationHandlers are able to dynamically change the number of composites based on external information (such as management level information). The system manager will treat changes from replication handlers in the same way as changes from the administrator and simply deploy or undeploy the delta.

The following xml document is used to define a static set of six composite instances: one CompositeA; two CompositeB; and three CompositeC instances.

<system name="example">
  <description>An example static system</description>
  <system.composite name="a" bundle="example-bundle" template="CompositeA" version="1.0" />
  <system.composite name="b" bundle="example-bundle" template="CompositeB" version="1.0">        
    <replicator name="two" />
  </composite>
  <system.composite name="c" bundle="example-bundle" template="CompositeC" version="1.0">        
    <replicator name="three" />
  </composite>
  <replication.handler name="two" type="org.cauldron.newton.system.replication.FixedSizeReplicationHandler">
   <property name="size" value="2" type="integer"/>
  </replication.handler>
  <replication.handler name="three" type="org.cauldron.newton.system.replication.FixedSizeReplicationHandler">
   <property name="size" value="3" type="integer"/>
  </replication.handler>
</system>

Each composite element specifies four attributes:

• The name attribute defines a unique name for this composite within the system.

• The bundle attribute specifies the composite bundle that provides this composite - must be equal to the value specified in that bundles Bundle-Symbolic-Name jar manifest attribute.

• The template attribute specifies the template within that composite bundle to use - must be equal to the name attribute in the composite template xml file.

• The version attribute specifies the version of the composite bundle to use.

The first composite is an empty xml element, this is a short hand way of referring to a fixed size replicator with a size config of 1.

The second two composites include a replicator pointer which point to named replication elements in the document below. A replicator can be reused by more than one composite so if for example you wanted to have three CompositeB instances you could change the replicator element within the b composite to look like:

<system.composite name="b" bundle="example-bundle" template="CompositeB" version="1.0">        
  <replicator name="three" />
</composite>

What if you want to be able to scale the number of composites with the number of available containers though? In this case you can't use a fixed size replicator else you'll be constantly modifying you system declaration. Instead you should use a scalable replication handler:

<replication.handler name="scale" type="org.cauldron.newton.system.replication.ScalableReplicationHandler">
 <property name="scaleFactor" value="1" type="float"/>
</replication.handler>

This will create a replicator that will match the number of composite instances to the number of available containers. If you wanted to take up half the available containers specify a scaleFactor of 0.5, if you wanted two instances per container specify 2.0, etc.