Using Dynamic Variable Substitution in Composite Applications 

Many times when developing or assembling applications a need arises to have the ability to substitute a value with something . Many times you may not know the actual value at assembly time or you wish the value to be defined in a single location which can also be updated. This capability now exists within composite applications starting in Lotus Expeditor 6.2.1 and Lotus Notes 8.5.1. The mechanism behind dynamic variable substitution support in composite applications is the org.eclipse.core.variables.dynamicVariables extension point. In this latest release the resolver supports reading dynamic variables from Eclipse plugin preferences. This means that you can specify a variable value in your plugin_customization.ini file by using the following convention:

<plugin id>/<variable name>=<value>

This will set the value properly within the framework. The next step is to simply reference this within your composite application. Areas that support string substitution with composite applications include all page and component preferences, along with many of the inputs used when defining an application containment configuration component. The following screen shots show how an application assembler can use the variable substitution mechanism to set the default URL for a defined browser component:



First we edit the plugin_customization.ini file to contain the value of our variable. For this example we are using a URL value to be used to set the default URL for a browser component within a basic composite application. The preference browserUrl in the topologyhandler plugin is the newly created preference we will use. The contents of the file look like this:



Next we open our composite application within the Composite Application Editor and we right click on our browser component and choose to edit properties. We go to the initialURL property in the component configuration and we enter in the preference value in the format ${ECLIPSE:<plugin id>/<preference name>}.



Since the value of the url was set to be http://www.ibm.com, after we refresh when clicking OK on our component properties tab, we see the browser default URL will be set to our value:



There is no restriction on which preference values can use substitution. Even newly created values the assembler has added are supported.

Using Variable Substitution with the Container Framework

When creating container framework components, we can use the CAE landmark editor UI or the toolbar UI (for most container components) in order to defineLandmarks and the actions to be executed within those landmarks. In short, aLandmark is a specific state in which a series of actions should execute in relation to the component. An example of this would be for a browser based container component where we wish to execute a series ofpublish actions when a particular URL is reached. The assembler defines theLandmark URL, the event which triggers the actions when the landmark is reached and the actions to be executed. The landmark editor panel looks like this:



Notice how we have a variable substitution in the Landmark field. In this particular composite application I created a preference called defaultLandmark with a plugin ID of com.ibm.rcp.composite.container.core. Variable substitution is also supported by the default publish and receive actions. For example, when using a web browser container component, I may choose to publish the value of the field as shown in the above screen shot. Instead of hard coding the value in there I could use variable substitution by adding my preference to the plugin_customization.ini (as shown above) and then using that value as the field value. Here are some steps outlining these techniques:

1. Make the change to the plugin_customization.ini file to add my preference.



2. We add our variable in to the field text box.

Using the Eclipse Preference Store as a Variable Source

The current support for dynamic variables works off of the Eclipse preference store. One of the benefits to using the Eclipse preferences is that there are a few ways to set these values. As outlined in the above examples, the plugin_customization.ini file can be used to statically set different preference values. This method is best used if the preferences your application will be accessing will not be changing often. It allows the assembler to set the value from a single location and not have to worry about modifying configurations within composite applications which reference this value.

Another way of setting preferences is through the Eclipse preferences API. This allows application developers to add a higher level of dynamicity to their applications since the preference value can be changed dynamically at runtime. Each time the value is accessed the change will be picked up and application behavior can change accordingly. Applications can be deployed to many users who may have different configurations which may result in slightly different settings for certain preferences. Using dynamic variable substitution in this manner can greatly reduce deployment and assembly headaches by not having to "special case" a configuration.

Setting Eclipse Preferences Programmatically

In order to set an Eclipse preference to be used by the variable substitution mechanism, the preference must be store in the proper format (as described above). This means, that the preference must be scoped to a plugin. This code snippet shows how to access the Eclipse preferences service and set a value that can be picked up by the variable substitution mechanism.

Access the preferences for a given plugin by retrieving the preferences from the plugin Activator class:

Support for Dynamic Variables

This section has a list of components and the specific areas that support use of dynamic variables:

All advanced property values for all component types

Notes View container component

Notes Document container component

Managed Browser container component

Summary

Variable substitution is a simple yet powerful mechanism which can not only simplify and provide convenience for application developers and assemblers, but it can also ease deployment and configuration of enterprise applications. As of this writing, retrieving values from the Eclipse preferences is the only supported service. However, in coming releases more support will be added for items such as Java System properties, Accounts settings and others.