Composite Instance Reference

XML Reference

As well as packaging SCA composites in bundles, Newton also allows developers to create “instance” documents which point to an existing SCA composite and (potentially) modify it in some way.

This allows the original software developer to specify the basic behaviour of an SCA composite in their bundles, but for another developer (acting as a user of the software) to customise the composite for his/her environment.

XML Reference

The following example creates an instance of a composite with the named “helloWorld” from the bundle with the bundle-symbolic-name “org.example.helloworld” and bundle version “1.0”:

<?xml version="1.0"?>
<composite name="helloWorld-instance">
  <bundle.root bundle="org.example.helloworld" version="1.0"/>
  <include name="helloWorld"/>
</composite>

The bundle root element specifies the bundle that supplies the composite file and provides the classpath (via local references or import statements) for all classes loaded by this composite.

The following is an example of how the helloWorld composite may look:

<?xml version="1.0"?>
<composite name="helloWorld">
  <property name=”defaultName” value=”world” />


  <service name=”api”>
    <interface.java interface=”org.example.HelloWorld” />
    <binding.osgi />
  </service>


  <component name=”impl”>
    <implementation.java impl=”org.example.impl.HelloWorldImpl” />
  </component>


  <wire>
    <source.uri>api</source.uri>
    <target.uri>impl</target.uri>
  </wire>
</composite>

To follow the original example we would then package this composite file in the META-INF folder of a bundle with the following manifest headers:

Manifest-Version: 1.0
Bundle-SymbolicName: org.example.helloworld
Bundle-Version: 1.0
Bundle-Name: Hello World
Installable-Component: true
Installable-Component-Templates: META-INF/helloWorld.composite

Note

The Installable-Component and Installable-Component-Templates manifest headers are required to indicate to Newton firstly that the bundle contains templates and secondly the location of the templates within the bundle. The templates header can contain a comma separated list of paths if more than one composite is provided by a bundle.

To complete the picture we could then create a second instance which customises the hello world composite to publish it's interface remotely and change the property default name to something else:

<?xml version="1.0"?>
<composite name="helloWorld-instance">
  <bundle.root bundle="org.example.helloworld" version="1.0"/>
  <include name="helloWorld"/>
  <property name=”defaultName” value=”Dave” />
  <service name=”api>
    <binding.rmi />
  </service>
</composite>