In many situations, it may be necessary to load additional bundles at runtime. For example, perhaps different users with different security rights have access to different features. In these situations, you may call IBundleService#install() to add new bundles to the application (note: at this time bundles may only be added/installed, not removed/uninstalled).

To hook into Potomac’s bundle loading process and add bundles dynamically, use the [StartupListener] extension point. [StartupListener]s are classes that are created and called during Potomac’s startup. Because startup listeners are executed so early in the Potomac initialization, bundle’s that declare a [StartupListener] must be preloaded. A StartupEvent.POTOMAC_INITIALIZED (”potomacInitialized”) event will dispatched on each startup listener. Potomac will suspend the creation of the Potomac UI until each startup listener has completed its processing and dispatched a StartupEvent.STARTUPLISTENER_COMPLETE event. This allows these classes to do significant processing during the startup phase including adding new bundles via IBundleService#install().

Please see the PotomacAdvancedExample application and the potomac_advancedexample_core for examples of using a startup listener to load bundles dynamically.

Application’s that use [StartupListener]s will typically increase the time until the Potomac UI is visible (i.e. because you’re likely calling a web service during startup). It is suggested that these applications also implement a Potomac preloader.

Loading Bundles Anytime

IBundleService#install() technically can be called at anytime not just during a startup listener, but individual extension points may or may not be dynamic aware. An extension point is dynamic aware if its controller listens to and responds appropriately to the ExtensionEvent.EXTENSIONS_UPDATED event. This event is dispatched on IBundleService anytime new extensions are added to the system via newly installed bundles. A dynamic aware extension point would update its processing to account for the new extensions. For example, if the Potomac [Page] extension point were dynamic aware it would add new page UI controls to the template for any new [Page] extensions found in newly installed bundles. Unfortunately [Page] is not dynamic aware (doh!), neither are any of the core Potomac UI extension points at this time (doh! doh!). Therefore installing new bundles should be done before any of the Potomac UI is created. The [StartupListener] extension point is made available just for this purpose. In future versions we hope to have all core Potomac extension points become dynamic aware.