newton
Newton
 

Spring OSGi based chainlink demo

Introduction

Overview

In this example we show how Newton can be used to manage Spring OSGi bundles. The specific features demonstrated are:

  1. Deployment and full lifecycle management of Spring OSGi bundles using Newton

  2. Automatic installation of the Spring-OSGi runtime whenever Spring-OSGi bundles are in use, and its automatic removal when it is no longer needed

  3. How Spring-OSGi bundles are interpreted as SCA composites by Newton

  4. How to configure Spring-OSGi bundles using SCA properties

  5. How to promote OSGi level services and references to SCA level so that they can work non OSGi bindings to, for example, communicate remotely.

  6. Use of Newton's provisioning infrastructure to deploy and maintain a distributed system based on Spring OSGi bundles.

Note
This example (examples/spring.chain) uses the Sigil OSGi build tools that are used by the other examples. There is also a similar example (examples/spring) that uses the Spring Maven archetypes with minimal modification

Prerequisites

To build and run the example you will need the following:

  • Newton version 1.4 or higher

  • The Spring-OSGi for Newton example (examples/spring.chain in Newton distribution)

  • Java 5 or 6

  • Spring-OSGi version 1.2 (with dependencies)

  • Ant 1.7.0 or later

  • At least one OS instance (Linux, OS X or Windows). If more OS instances are available to you, you can use them as well.

Maven, Ant, Spring OSGi, and the examples need only be installed on your development machine, but Newton must be installed on any OS instances that you use to run these examples.

Developing Spring-OSGi bundles

This is not a tutorial on general Spring-OSGi bundle development. The following links may be useful to you if you are not already familiar with Spring-OSGi

The demo application

Overview

This example builds a chain made up of links. Each link provides a Link service with a single method append, and has a reference to another Link service. Properties and filters are used to control the order in which the links wire up.

As calls pass through the chain each link appends is name, building up a string that shows the full path. When the end of the chain is reached the string is returned.

There are two Spring-OSGi bundles in this demo. One, called springlink, implements the links in the chain. The other, called springchaincli provides an extension to the Newton console that makes it possible to invoke the chain from the command line.

Structure

There are two main parts to this example.

  1. Local example. In this section we show how the addition of a small amount of metadata can be used to turn Spring-OSGi bundles into SCA components and how SCA properties can be used to configure Spring-OSGi bundles.

  2. Distributed example. In this section we show how to promote OSGi level services and references to SCA level so that they can, for example, interact remotely. We also show how Newton's provisioning capabilities can be used to deploy and maintain a distributed Spring-OSGi application.

The bundles in the two parts differ only in their metadata (stored below src/main/resources directory of each Spring-OSGi project). Ant targets for switching to the metadata for each part are supplied.

Local Example

In this initial example we'll show how to deploy and undeploy the springchaincli and springlink bundles to a single Newton container, walking through the necessary Newton specific configuration.

First of all make sure you are using the local example metadata by running the following in the examples directory.

ant clean install-list

This copies the local chain metadata into the bundle resources directory (src/main/resources in each Spring-OSGi project). If you are using an IDE, you should refresh your projects after running this task.

Before running anything let's look at the configuration files. These are below the src/main/resources directory of each Spring-OSGi project and are organized as follows

`-- META-INF
    |-- MANIFEST.MF
    |-- paremus
    |   `-- springchaincli.template
    `-- spring
        |-- bundle-context-osgi.xml
        `-- bundle-context.xml

Below the spring directory are the standard Spring-OSGi configuration files. bundle-context.xml is just an ordinary spring beans.xml file, while bundle-context-osgi.xml contains OSGi specific extensions. The newton directory holds a Newton template. This is used to expose the Spring-OSGi bundle as an SCA composite, to configure the bundle and to promote its references and services. The MANIFEST.MF file does not contain the full bundle manifest, most of which is generated by Spring-OSGi's Maven based build system. All it contains are additions to the manifest required by Newton, specifically entries identifying the bundle as a Newton bundle and telling Newton where to look for the template file.

We are now going to look at all of these files in detail. Here they are for springchaincli. Their rather verbose namespace declarations have been omitted for clarity.

bundle-context.xml 

<beans>
  <bean name="chainLinkCliBean" 
  class="org.cauldron.newton.examples.spring.chain.cli.impl.ChainLinkCliBeanImpl" />
</beans>

This contains a single bean. It has no explicit dependencies, but as we shall see from the next file, it has an implicit dependency on a Link (the first link in the chain)

bundle-context-osgi.xml 

<beans>
  <osgi:reference 
    id="nextLink" 
    interface="org.cauldron.newton.test.bundles.chainlink.interfaces.Link" 
    filter='(tag=a)' 
    cardinality="0..1"
  >
  <osgi:listener bind-method="bindLink" unbind-method="unbindLink" 
    ref="chainLinkCliBean"/>
  </osgi:reference>
  <osgi:service ref="chainLinkCliBean" 
    interface="org.cauldron.newton.command.console.ConsoleCommandHandler"/>
</beans>

This defines a reference to an OSGi service, implementing Link, with property tag=a. Whenever a service satisfying this reference is found or lost the listener calls back to the chainLinkCliBean bean defined in bundle-context.xml.

Also defined is a service implementing Newton's ConsoleCommandHandler. This provides the command line extension used to interact with the chain.

springchaincli.template 

<composite name="springchaincli">
  <component name="cli">
    <description>spring chain cli</description>
    <implementation.spring /> 
  </component>
</composite>

This defines an SCA composite, and states that it is implemented by a Spring-OSGi bundle. At this stage all we are interested is the composite name springchaincli, which will be used below.

Here are the equivalent files for springlink

bundle-context.xml 

<beans> 
  <!-- Configuration Admin entry -->
    <osgix:cm-properties persistent-id="org.cauldron.newton.example.spring.chain.link" id=”cmProps”/>
  <!-- placeholder configurer -->
  <ctx:property-placeholder properties-ref="cmProps" />
  <bean name="springLinkBean" 
   class="org.cauldron.newton.examples.spring.chain.link.impl.SpringLinkImpl" >
    <property name="linkName" value="${linkName}"/>
  </bean>
</beans>

Again this contains a single bean, but this time it has a property, linkName which is read from the OSGi Configuration Admin service. The cm-properties line indicates the Configuration Admin service pid from which the properties should be read. In the template and instances below we'll see how these can be set using SCA properties

bundle-context-osgi.xml 

<beans>
  <osgi:reference id="nextLink" 
       interface="org.cauldron.newton.test.bundles.chainlink.interfaces.Link" 
       filter=”(tag=b)” cardinality="0..1">
    <osgi:listener bind-method="bindLink" unbind-method="unbindLink" ref="springLinkBean"/>
  </osgi:reference>
  

  <osgi:service ref="springLinkBean" 
    interface="org.cauldron.newton.test.bundles.chainlink.interfaces.Link">
    <service-properties>
      <entry key="tag" value="a"/>
    </service-properties>
  </osgi:service>
</beans>

This bundle has a reference to an implementation of Link filtered by (tag=b), and provides a service implementing Link with property tag=a. Note that in this local example the (tag=b) filter wont be used, although it will be later on in the in remote example.

springlink.template 

<composite name="springlink" >
  <component name="springLink">
    <service name="springLink" />
    <description>spring based chain link</description>
    <property name="service.pid"
              value="org.cauldron.newton.examples.spring.chain.link"
              type="string" />
    <property name="linkName"
              value="Local-A-Default"
              type="string" />
    <implementation.spring /> 
  </component>
</composite>

This template exposes the springlink bundle as a composite and sets its service.pid property. Whenever Newton sees a service.pid property in a component it registers all other SCA properties for that component with the OSGi Configuration Admin service using that service.pid as the key. In this case the service.pid correlates with the persistent-id attribute from the property-placeholder element in bundle-context.xml, so these properties are made available to the Spring configuration files.

Running the local example

To run the demo first start Newton by changing to the Newton bin directory and running

for unix

$ ./container

for windows:

> container.bat

If at any time you want to look at Newton's log, you can find it under var/container.log

Once Newton has started we need to load the example bundles and the Spring-OSGi bundles into CDS (Content Distribution System), Newtons repository.

To do this run

cds scan boot examples/spring.chain/build/lib/
cds scan boot examples/chainlink/build/lib
cds publish boot examples/spring.chain/xml/publish-springdm-1.2.xml <Spring-OSGi install directory>

Here the first line loads the spring example bundles. The second line loads the non-Spring Newton chainlink bundles (from which our Spring bundles import an API package). The third line uses a Newton publish file to load the required bundles from the Spring OSGi install directory. Note that this publish file is specific to version 1.1.2 of Spring-OSGi, so if you are using a later version you should edit it appropriately. All bundles are loaded into the boot zone of CDS, i.e. they are private to this Newton instance.

Note that CDS takes paths relative to the Newton install directory regardless of the directory from which you launched Newton.

Before installing anything take a look at the bundles that are already installed by running

> bundles -i

at the Newton command line. This will display all installed bundles, in the order in which they were installed. Here are the last few taken from my machine

  82 --/resolved  org.cauldron.newton.presence.local.api   
  83 --/resolved  org.cauldron.newton.presence.remote.api
  84 --/active    org.cauldron.newton.presence.service  
  85 --/resolved  com.sun.jmx.remote.optional
  86 --/active    org.cauldron.newton.management.server   
  87 --/active    org.cauldron.newton.management.monitor
  88 --/resolved  org.cauldron.newton.boot.control.api   
  89 --/active    org.cauldron.newton.boot.control

Note that no example or spring bundles are present.

It is also worth typing help at the console to see the available commands. 

> help
Available command groups (type 'enter' to enter a group):
system - commands for manipulating systems
storagecds - Commands for manipulating cds storage
sleep - sleeps for a configurable number of milliseconds
session - Session commands built into the console
provisioner - Commands for manipulating the provisioner
obr - OBR commands
logman - Commands for controlling logging within container
logconfig - Configuration commands for the log.
log - Log commands
installer - installs/uninstalls/tracks SCA components in this jvm
indexcds - Commands for manipulating the index service
framework - Framework commands
exec - executes a script from a file or url location
configuration - Configuration commands
cds - Commands for manipulating cds content
binder - Tools for introspecting the binding graph

Note that this list does not include any references to our demo.

Now install springchaincli as follows:

> installer install composite:springchaincli

If we now take another look at the installed bundles using bundles -i. the last few bundles should be 

  88 --/resolved  org.cauldron.newton.boot.control.api   
  89 --/active    org.cauldron.newton.boot.control
   90 --/resolved  chainlink-api-bundle    91 --/active    Spring Chain Cli
   92 --/resolved  slf4j-api               93 --/resolved  slf4j-log4j12
   94 --/resolved  aopalliance.osgi        95 --/resolved  jcl104-over-slf4j
   96 --/resolved  spring-core             97 --/resolved  spring-osgi-io
   98 --/resolved  spring-beans            99 --/resolved  spring-aop
  100 --/resolved  spring-context         101 --/resolved  spring-osgi-core

Note that as well as installing springchaincli (bundle 91 in this list), the Spring-OSGi runtime has also been installed. Newton does this on demand whenever a Spring-OSGi bundle is installed. To see the OSGi services published by these bundles type services -i, or services -l <bundle-number> for more detail

Rerunning help 

>help
Available command groups (type 'enter' to enter a group):
system - commands for manipulating systems
storagecds - Commands for manipulating cds storage
springchain - Spring: Commands for manipulating chains of Links
sleep - sleeps for a configurable number of milliseconds
session - Session commands built into the console
provisioner - Commands for manipulating the provisioner
obr - OBR commands
logman - Commands for controlling logging within container
logconfig - Configuration commands for the log.
log - Log commands
installer - installs/uninstalls/tracks SCA components in this jvm
indexcds - Commands for manipulating the index service
framework - Framework commands
exec - executes a script from a file or url location
configuration - Configuration commands
cds - Commands for manipulating cds content
binder - Tools for introspecting the binding graph

We can see that there is now an entry called springchain. This is the command line extension we'll use to run the demo. If we try it now all we see is

> springchain chain
[end of chain]

This is because there are no links installed. We can get one by installing springlink

>installer install composite:springlink

Re-running the demo we now see

> springchain chain
chain: cli->{Local-A-Default} [end of chain]

This indicates that we have a chain consisting of one springlink. The link has bound to the command line because it has property tag=a which is accepted by the filter (tag=a) on springchaincli's Link reference.

SCA composite documents can be used to override or extends the SCA template files embedded in Newton bundles. In the chain above the name 'Local-A-Default' comes from the property 'linkName' set in the SCA template. We're going to override this using an SCA composite called local-link-a.composite.

<composite name="local-link-a">
<bundle.root bundle="org.cauldron.newton.examples.spring.chain.link"
  version="1.0" />
  <include name="springlink" />
  <component name="springLink">
    <property name="linkName" value="LocalLink-A" type="string" />
  </component>
</composite>

The bundle.root element points at the bundle this composite will be created by. The include element selects the template being overridden. The component element identifies component being overridden and includes a new value for the overridden property.

Only one instance of any bundle can be installed per OSGi framework instance, so before we can install local-link-a.composite we have to uninstall the default springlink composite.

> installer uninstall composite:springlink

We can now install the new composite using

> installer install examples/spring.chain/build/etc/local-link-a.composite

Re-running springchain we can see overridden name ' LocalLink-A' has been picked up.

> springchain chain
chain: cli->{LocalLink-A} [end of chain]

Notice in the above that the default composite for a Spring-OSGi bundle, or any Newton bundle, is installed using a logical name of the form composite:<template-name>. On the other hand, overriding composites, which live outside the bundle they configure, are installed by providing the path or URL of their composite file.

Next we'll uninstall everything.

> installer uninstall examples/spring.chain/build/etc/local-link-a.composite
> installer uninstall composite:springchaincli

Having done this Newton will mark all unused bundles as available for garbage collection, and uninstall them. Further, Newton notices that the Spring-OSGi runtime is no longer needed, so its bundles are also stopped and made eligible for garbage collection.

Remote Example

The previous example was confined to a single Newton instance, and we did everything manually. Next we're going to build a chain spanning multiple Newton instances. To do this we'll use Newton to promote OSGi level services to SCA level, and then show how an SCA system description can be used to manage the distributed chain.

Before doing anything run the ant task that replaces the local chain metadata with distributed chain metadata.

$ cd $examples
$ ant -Dspring.chain=/remote clean-list install-list


Next let's look at how the metadata has changed. In the spring specific files, below META_INF/spring the only things that have changed are the OSGi filters and properties on the references and services of type Link. The filters now have the form

filter="(newton.sca.reference=nextLink)"

and the properties now have the form

<service-properties>
  <entry key="newton.sca.service" value="springLink"/>
</service-properties>

The filter name newton.sca.reference and property name newton.sca.service are handled in a special way by Newton.

Services with the newton.sca.service property are published at SCA level rather than OSGi level. The value of the property is used as the SCA service name.

References with the newton.sca.reference filter are resolved at SCA level rather than OSGi level. The value of the filter is used as the SCA reference name.

Note
From their point of view, Spring-OSGi bundles only ever interact directly with the OSGi registry, so they are oblivious to Newton.

The Newton template files have also changed.

springchaincli.template (namespaces omitted) 

<composite name="springchaincli" >
  <component name="cli">
    <reference name="nextLink" />
    <description>spring chain cli</description>
    <implementation.spring /> 
  </component>
  

  <reference name="nextLink" multiplicity="0..1">
    <interface.java 
      interface="org.cauldron.newton.test.bundles.chainlink.interfaces.Link" />
  </reference>
  

  <wire>
    <source.uri>cli/nextLink</source.uri>
    <target.uri>nextLink</target.uri>
  </wire>
</composite>

The first thing to notice is that the springchaincli component now contains a reference called nextLink. This was made available by the (newton.sca.reference=nextLink) filter which promoted nextLink to SCA level. The wire element connects this component level reference to a composite level reference of the same type. At the moment no SCA binding is specified for the composite level reference. This will be supplied later by composite instance files.

springlink.template (namespaces omitted)

<composite name="springlink">
  <reference name="nextLink" multiplicity="0..1">
    <interface.java 
      interface="org.cauldron.newton.test.bundles.chainlink.interfaces.Link" />
  </reference>


  <service name="link">
    <interface.java 
      interface="org.cauldron.newton.test.bundles.chainlink.interfaces.Link" />
  </service>


  <component name="springLink">
    <reference name="nextLink" />
    <service name="link" />
    <description>spring based chain link</description>
    <property name="service.pid"
              value="org.cauldron.newton.examples.spring.chain.link"
              type="string" />
    <implementation.spring /> 
  </component>
  

  <wire>
    <source.uri>springLink/nextLink</source.uri>
    <target.uri>nextLink</target.uri>
  </wire>>
  

  <wire>
    <source.uri>link</source.uri>
    <target.uri>springLink/link</target.uri>
  </wire>
</composite>

The springLink component includes a reference called nextLink and a service called springLink, both promoted from the Spring-OSGi bundle. They are wired respectively to a composite level reference and service, each with an unspecified binding. These will be filled in by the composite instance documents.

That's the end of the differences in the metadata embedded in the example bundles. It's also worth looking at some of the composite instance documents we'll be using.

For springchaincli there is only one composite instance document, here it is

springchaincli.composite (namespaces omitted) 

<composite name="springchaincli" >
	

  <bundle.root bundle="org.cauldron.newton.examples.spring.chain.cli"
               version="1.0" />
  <include name="springchaincli" />


  <reference name="nextLink" >
    <binding.rmi filter="(tag=a)" />
  </reference>


</composite>

As in the local example this overrides some of the template. In this case it adds an RMI binding to the nextLink reference, i.e. tries to resolve the reference using an RMI based transport, and gives it a filter of (tag=a). This filter will make springlinkcli connect to the first link in the chain (remote-link-a).

For springlink there are three composite instance documents, all of which have the same form. The first is shown below

remote-link-a.composite (namespaces omitted)

<composite name="remote-link-a">
  <bundle.root bundle="org.cauldron.newton.examples.spring.chain.link"
               version="1.0" />
  <include name="springlink" />
	

  <reference name="nextLink" >
    <binding.rmi filter="(tag=b)" />
  </reference>
  

  <service name="link">
    <binding.rmi >
      <attribute name="tag" value="a" type="string" />
    </binding.rmi>
  </service>


  <component name="springLink">
    <property name="linkName" value="Remote-Link-A" type="string" />
  </component>


</composite>

In this case several template level settings have been overridden. The bindings are all set to RMI. The service property tag=a is added, and the reference filter is set to (tag=b), so the composite provides link-a and tries to connect to link-b, all over RMI. Also, the linkName property is set to Remote-Link-A.

remote-link-b.composite and remote-link-c.composite differ only on their filters, properties and linkName property value. These are arranged so that the chain wires up in alphabetical order.

Running the remote example

To run the example we'll need three running Newton instances. The first of these should be on your development machine. The others can be on the same machine, or on different machines, as long as all machines are within multicast range of each other.

Assuming that they are all being started on one machine from the same Newton install directory the commands we need are as follows. You should pick a fabricName unique to yourself to prevent remote interaction with other Newton instances

for unix

development machine

$ ./container -fabricName=your-fabric-name

instance 1

$ ./container -instance=1 -fabricName=your-fabric-name

instance 2

$ ./container -instance=2 -fabricName=your-fabric-name

for windows:

development machine

> container.bat -fabricName=your-fabric-name

instance 1

> container.bat -instance=1 -fabricName=your-fabric-name

instance 2

> container.bat -instance=2 -fabricName=your-fabric-name

The logs for the different Newton instances can be found below the Newton install at var/container.log, var/1/container.log and var/2/container.log.

At startup, Newton is in local mode. To set it up for distributed use, we must first initialise the distributed runtime and install its command line extensions by running the following on the development machine (only). 

> exec etc/scripts/single-jvm-dist-infra

A side effect of running this script is to start Newton's global event log. This is on your development machine below the Newton install directory at var/global-event.log. Warnings and errors from any Newton instance in you fabric can be found here.

We should also load the example bundles into CDS. 

> cds scan remote examples/spring.chain/build/lib
> cds scan remote examples/chainlink/build/lib
> cds publish remote examples/spring/xml/publish-springdm-1.2.xml <Spring-OSGi install directory>

Note that this time we're loading bundles into the remote zone to make them available to all Newton instances. Make sure you enter remote here, not boot.

The other two Newton instances can share the distributed runtime installed in the first one, but have to be told to make themselves available for remotely initiated installations. To do this run

> system manage etc/systems/remote-container.system

in both of them.

First time round we'll install the chain manually as follows:.

On the development machine we'll install springchaincli and an instance of sprinklink configured to serve as link a.

> installer install examples/spring.chain/build/etc/springchaincli.composite
> installer install examples/spring.chain/build/etc/remote-link-a.composite

In instance 1 we'll install link-b.

> installer install examples/spring.chain/build/etc/remote-link-b.composite

In instance 2 we'll install link-c

> installer install examples/spring.chain/build/etc/remote-link-c.composite

Returning to the development machine we can now try out the chain

> springchain chain
chain: cli->{Remote-Link-A}->{Remote-Link-B}->{Remote-Link-C} [end of chain]

So, without any code changes we've distributed out Spring-OSGi based chain over three Newton instances, and arranged for them to wire up in the correct order.

Before the next part of the demo we need to uninstall all of the springlinks, although we'll keep the springchaincli.

Development machine

> installer uninstall examples/spring.chain/build/etc/remote-link-a.composite

Instance 1

> installer uninstall examples/spring.chain/build/etc/remote-link-b.composite

Instance 2

> installer uninstall examples/spring.chain/build/etc/remote-link-c.composite

The ability to wire up Spring-OSGi services and references remotely is valuable, but it's awkward and unscaleable to have to go to each terminal and start the required composites manually. Newton's provisioning system can help here.

Newton is able to deploy and maintain SCA system documents. These documents include references to several related composites and use replication handlers, to control how many of each are created. System documents are handed to Newton's distributed provisioning system. This examines the available containers and based on what it finds tries to satisfy the target state specified by the system document.

We'll demonstrate all of this here by creating a system document to represent the chain of springlinks. Here's the springchain.system system document (links b and c have the same structure as link a, so they've been elided for clarity.

<system name="springchain" boundary="fabric">
  <description>spring DM for OSGi based chain</description>
 

  <system.composite name="linka"
                    bundle="org.cauldron.newton.examples.spring.chain.link"
                    template="springlink"
                    version="1.0" >
  

    <reference name="nextLink" >
      <binding.rmi filter="(tag=b)" />
    </reference>
    

    <service name="link">
      <binding.rmi >
      <attribute name="tag"
                 value="a"
                 type="string" />
      </binding.rmi>
    </service>
  

    <component name="springLink">
        <property name="linkName"
                  value="SpringLink-A"
                  type="string" />
    </component>


    <replicator name="scale" />       
    

  </system.composite>
  

  <system.composite name="linkb" ... />
  <system.composite name="linkc" ... />   
     

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


</system>

The value 'fabric' for the boundary attribute on the top level system element tells Newton's provisioning system that it can use all containers that are part of this fabric to try to realise the system.

This system includes three composites and one replication handler.

The composites have essentially the same structure as the remote-link-a.composite etc. that we used above. The only differences are that the bundle information and template now appear as attributes, that the link names have the form SpringLink-A etc. and that each composite includes a reference to the replication handler.

The replication handler is a ScalableReplicationHandler. Handlers of this type produce a number of copies that varies with the number of available Newton instances according to the specified scale factor. In this case the scale factor is 0.33333, because we want a third as many copies of each link type as there are containers.

Before asking Newton to manage this system, we'll take a look at the state of the provisioner.

> remote-provisioner status
-----------------
Provisioner history:
  Resolve(Success)   current: 0 max: 0 total: 0
  Install(Success)   current: 0 max: 0 total: 0
  Uninstall(Success) current: 0 max: 0 total: 0
  Resolve(Failure)   current: 0 max: 0 total: 0
  Install(Failure)   current: 0 max: 0 total: 0
  Container(Failure) current: 0 max: 0 total: 0
  Uninstall(Failure) current: 0 max: 0 total: 0
-----------------
Listing all containers
Container ContainerID[cd9157e0-30ca-12a1-94ca-bbe1b0695873:opensuse-1]
Container ContainerID[75bb8580-30c6-12a1-926b-bbe1b0695873:opensuse-1]
Container ContainerID[0e1895a0-312d-12a1-ad32-07a4b50f4af5:opensuse-1:2]
Container ContainerID[007d00c0-312d-12a1-9efb-595061512df3:opensuse-1:1]
-----------------
No commands registered
-----------------

Here you should see four containers, one for each Newton instance you started, and one used internally by Newton. If you don't see all four make sure you have three Newton instances running and that you have run 

system manage etc/systems/remote-container.system

on instances 1 and 2.

As you can see from the last line, the provisioner has not yet been given any commands.

Now let's tell Newton to manage our system

remote-system manage examples/spring.chain/build/etc/springchain.system

Taking another look at the provisioner state you should see the following.

remote-provisioner status

> remote-provisioner status
-----------------
Provisioner history:
  Resolve(Success)   current: 3 max: 3 total: 3
  Install(Success)   current: 3 max: 3 total: 3
  Uninstall(Success) current: 0 max: 0 total: 0
  Resolve(Failure)   current: 0 max: 0 total: 0
  Install(Failure)   current: 0 max: 0 total: 0
  Container(Failure) current: 0 max: 0 total: 0
  Uninstall(Failure) current: 0 max: 0 total: 0
-----------------
Listing all containers
Container ContainerID[40204160-3132-12a1-9f58-595061512df3:opensuse-1:1]
Container ContainerID[cd9157e0-30ca-12a1-94ca-bbe1b0695873:opensuse-1]
Container ContainerID[75bb8580-30c6-12a1-926b-bbe1b0695873:opensuse-1]
Container ContainerID[0e1895a0-312d-12a1-ad32-07a4b50f4af5:opensuse-1:2]
-----------------
Listing all commands
springchain:linka : Hosting -> ContainerID[0e1895a0-312d-12a1-ad32-
07a4b50f4af5:opensuse-1:2] cost = 1
springchain:linkb : Hosting -> ContainerID[cd9157e0-30ca-12a1-94ca-bbe1b0695873:opensuse-1] cost = 1
springchain:linkc : Hosting -> ContainerID[40204160-3132-12a1-9f58-595061512df3:opensuse-1:1] cost = 1
-----------------

If you ran this command very quickly, you may see different status messages, but it will settle down to something like this after a few seconds.

Here we can see that the provisioner has been asked to install one copy each of links a,b and c, and that it has succeeded in doing so.

To verify this let's run the chain again

> springchain chain
chain: cli->{SpringLink-A}->{SpringLink-B}->{SpringLink-C} [end of chain]

If you go to your Newton instance-1 or instance-2 now and type bundles -i or services -i, you'll be able to see that the Spring-OSGi runtime and the springlink bundle have been installed.

When we're finished with the system we can shut it down by retiring it from the provisioner as follows.

remote-system retire examples/spring/xml/springchain.system

If you now check the provisioner status using remote-provisioner status you should see that it is back to its initial state, with no commands registered. To verify that the chain has really gone away.

let's run it again

> springchain chain
[end of chain]

What we've done here is describe a full distributed system based on Spring-OSGi bundles using a single SCA system document, used Newton to automate the details of deploying it across several OSGi containers, tested it and then used Newton to remove it again.

For the purposes of this example we started Newton's distributed runtime on a single machine. In production deployments of Newton this runtime is typically deployed in a replicating and self healing configuration.

Summary

The important points to take away from these examples are that:

  • Using Spring-OSGi bundles with Newton involves no changes to code and lightweight changes to configuration

  • Newton provides an easy way to configure and deploy Spring-OSGi bundles

  • Newton is capable of managing the deployment and wire-up of multiple Spring-OSGi bundles to realize the application described in a high level SCA system description.

Although we didn't show it here, services and references based on Spring-OSGi bundles can interact with SCA level services from any SCA composite deployable in Newton, not only those built using Spring-OSGi.