Plugin bundle properties

Content [ Hide ]

The bundle properties offer the plug-in developer the possibility to configure plug-ins externally and thus control the runtime behaviour of the developed plug-ins.

The bundle properties can be used, for example, to make addresses and access information of web service endpoints configurable.

They are suitable for externally influencing certain plugin types, such as the IPluginFormPreRender plugin or the IPluginServletAction plugin, which themselves do not have their own configuration interface in Xima® Formcycle.

Definition of bundle properties by the plugin developer

By including the IBundleProperties interface, configurable options can be displayed in the Xima® Formcycle interface.

The interface of Xima® Formcycle offers the possibility to store new properties with name and value at the respective plug-in bundle.
In most cases, however, it is useful if the name (access key, must be unique within the bundle properties) and, if necessary, a default value for a property are stored.
and, if applicable, a default value for a property, are already defined by the plug-in developer.

On the one hand, this eliminates typing errors when the access key is created by the plug-in user, and on the other hand
on the other hand, the plug-in user receives a view of all configuration values supported by the plug-in developer.

Interface IBundleProperties

The interface provides the following method signatures:

Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale)

The getConfigProperties method is used to configure property values that should be available to all Java classes within the plugin bundle.
Transfer values:
  • IPluginResourceHelper
    • Objects to access the file resources contained in the plugin bundle.
  • Locale
    • The Locale object defined for the currently logged-in user (contains information on the language and region). This can be used to determine language-dependent texts.
Return values:
The method must return an object of type java.util.Map with Value objects of type IBundleConfigParam. There are two possible implementations of IBundleConfigParam:
  • BundleConfigGroupItem This item can be used to structure the list display in the Xima® Formcycle interface.
  • BundleConfigParam
    • Used to define a bundle property. An object defines the following properties:
      name
      The name or access key of a property.
      description
      Description of a property. Displayed by mouseover over the Property name in the interface. Can be used to show the user of the plug-in more detailed information on the use or possible value ranges of the parameter.
      mandatory
      Determines whether the parameter is displayed as a mandatory parameter in the interface and whether a validation for the presence of a value is carried out when saving.
      crypticValue
      Determines whether the value of the property is to be masked as with a password field. Default value is false.
      defaultValue
      Allows the developer to set a default value. Default value is null.

Implementation example

The following code example shows a possible implementation:

@SuppressWarnings("serial")
public class MyBundleProperties implements IBundleProperties {

 /**
   * Returns a map with definitions of bundle configuration parameters. Key is the parameter name, value is a bundle
   * parameter definition of type {@link IBundleConfigParam}.
   * @param resHelper ResourceHelper to determine i18n values from the plugin bundle, if they exists.
   * @param currentLocale the current locale
   * @return {@link Map} with objects of type {@link IBundleConfigParam} or <code>null</code>.
   */
 @Override
 public Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale) {
    Map<String, IBundleConfigParam> config = new LinkedHashMap<>();
    config.put("Group", new BundleConfigGroupItem("Supported parameters:"));
    config.put("Parameter1", new BundleConfigParam("Parameter1", "Mandatory parameter in scope of plugin with default value", true, "Default value"));
    config.put("Parameter2", new BundleConfigParam("Parameter2", "Mandatory parameter in the scope of the plug-in", true));
    config.put("Parameter3", new BundleConfigParam("Parameter3", "Parameter in scope of plug-in with default value", false, "Initial value"));
    config.put("Parameter4", new BundleConfigParam("Parameter4", "Parameter in scope of plugin", false));
   return config;
 }

}

Access to bundle properties within the plugin logic

Access to bundle properties within individual plugin implementations is provided via the IFCPlugin interface and its provided plugin lifecycle methods.
All Plugin Types inherit from this interface, allowing access to bundle properties in all plugin implementations.

Examples for reading bundle properties

The following example shows how to access the bundle properties within a IPluginFormPreRender implementation.

By default, a PreRender plugin is executed on all form calls in the scope of the client in which it was registered.
For example, if you want the PreRenderer to be executed only when certain forms are called, you can make this configurable using Bundle-Properties.
The following example reads in the execute method reads the value of the Bundle-Property activate.form.alias, which contains the names of forms (separated by commas).
Then these names are compared with the name of the current form in whose scope the PreRenderer is currently running. 
If the name of the current form does not match a name from the configured list, further processing of the PreRenderer is aborted.

public class MyPreRenderer implements IPluginFormPreRender {

 private Properties bundleProperties = null;

 /**
   * Name which makes plugin uniquely identifiable.
   */
 @Override
 public String getName() {
   return "My PreRenderer";
 }

 /**
   * Plugin lifecycle method, which is called when the object instance is created.
   */
 @Override
 public void initialize(IPluginInitializeData initializeData) throws FCPluginException {
    bundleProperties = initializeData.getProperties();
 }

 /**
   * Method for executing plugin logic.
   */
 @Override
 public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams params) throws FCPluginException {
   // Read bundle property 'activate.form.alias'.
    Set<String> alias = getConfiguredFormAlias("activate.form.alias");

   // Is PreRender plugin enabled for current form instance?
    IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)params.getFormRequestContext();
   if (!alias.contains(ctx.getProject().getName())) {
     // no form activation found -> cancel processing
      return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
   }

   // further PreRender implementation
    // ....

   return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
 }

 /**
   * Function to determine a bundle property value.
   * The determined value is separated by a comma
   * and returned as a HashSet.
   * @param propertyName
   * @return a {@link HashSet}
   */
 protected Set<String> getConfiguredFormAlias(String propertyName) {
    String formAlias = bundleProperties.getProperty(propertyName, null);
   if (XStringUtils.isBlank(formAlias)) { return Collections.emptySet(); }
    String[] arr = XStringUtils.split(formAlias, ",");
   return new HashSet<String>(Arrays.asList(arr));
 }
}