Managing bundles programmatically

Searching for bundles

The BundleContext also provides methods to search for bundles installed in the App Runtime using getBundles().

BundleContext.getBundles
export default class {
   start(){
      // returns array of all bundles
      let allbundles = bundleContext.getBundles();
      // search bundles with symbolic name "test"
      let bundles = bundleContext.getBundles("(name=test)");
      // expect one test bundle
      let testBundle = bundles[0];
   }
}

getBundles() accepts a filter string that can define complex filter expressions. This expression is used to filter bundles based on their manifest properties.

Filter expressions are specified by the RFC-1960 and known as LDAP filter syntax.

Here are some examples of filter expressions:

Sample Description

(name=test)

Property name must have the value test (case sensitive)

(name=*)

Property name must have a value (must exist).

(keywords=wizard)

Property keywords must have the value wizard. keywords is of type array. This means that one value of the array must match the condition.

(name=test*)

Property name must start with test

(startLevel <= 10)

Property startLevel must be less than or equal to 10.

(startLevel >= 10)

Property startLevel must be greater than or equal to 10.

(! (startLevel = 10))

Property startLevel must not be equal to 10. This is the NOT operator.

(& (startLevel < 10) (startLevel > 8))

Property startLevel must be less than 10 and greater than 8. This is the AND operator.

(| (startLevel < 10) (startLevel > 10))

Property startLevel must be less than 10 or greater than 10. This is the OR operator.

(name~=test)

Property name must be equal to test (case insensitive), so it matches test, TEST, and TesT for example.

(name~=test*)

Property name must start with test but (case insensitive), so it matches testab, TESTab, and TesTaB for example.

Starting a bundle

If a bundle activator needs to start a bundle, it can use the start method of a bundle object.

Bundle.start
export default class {
   start() {
      // search bundles with symbolic name "test"
      let bundles = bundleContext.getBundles("(name=test)");
      // expect one test bundle
      let testBundle = bundles[0];
      // start the test bundle
      testBundle.start().then(()=>{
        console.debug("test bundle started");
      });
   }
}

Stopping a bundle

If a bundle activator needs to stop a bundle, it can use the stop method of a bundle object.

A bundle should not stop itself.

Bundle.stop
export default class {
   start() {
      // search bundles with symbolic name "test"
      let bundles = bundleContext.getBundles("(name=test)");
      // expect one test bundle
      let testBundle = bundles[0];
      // stop the test bundle
      testBundle.stop().then(function() {
        console.debug("test bundle stopped");
      });
   }
}

Installing a bundle

If a bundle activator needs to install new bundles into the system, it can use the installBundle method of the BundleContext. This is a very powerful feature, because it allows to add features to a running application lazily.

installBundle() expects three parameters and can be used in different ways.

installBundle interface
installBundle(
  location, // URL pointing to the bundle directory
  manifest, // manifest.json object (optional)
  name  // the name of the bundle (optional), overwrites the name provided in the manifest.json
);

The following code sample shows the most simple way to install a new bundle:

BundleContext.installBundle()
export default class {
   start() {
      // install a test bundle
      let promise = bundleContext.installBundle("http://localhost:8080/js/externalBundles/test");
      // The installBundle method, now fetches the manifest.json provided
      // at http://localhost:8080/js/externalBundles/test/manifest.json
      // interprets it and constructs a bundle instance
      promise.then((testBundle) => {
        // after successful installation, start the bundle
        testBundle.start();
      });
  }
}

Uninstalling a bundle

If a bundle activator needs to uninstall a bundle, it can use the uninstall method of a bundle object.

Bundle.uninstall
export default class {
   start() {
      // search bundles with symbolic name "test"
      let bundles = bundleContext.getBundles("(name=test)");
      // expect one test bundle
      let testBundle = bundles[0];
      // uninstall the test bundle
      testBundle.uninstall().then(() => {
        console.debug("test bundle uninstalled");
      });
  }
}