Transformer

From wiki.gpii
Jump to: navigation, search

Description

The transformer is a utility that can be used by the Cloud4All/GPII architecture to translate between common terms and application specific settings. It is stateless, relatively easy to extend an has a basic API. Generally, transformations are defined by a vendor (or user) in the description of a solution in the Solution Registry, more particular in a Settings Handler blocks, to describe how an application specific setting(s) can be understood and transformed into a common term(s) and vice versa.

A "normal" transformer translates from common terms to application-specific terms, while an inverse transformer translates from application-specific terms to common terms.

Below is a description of how a transformation is described and what transformations are available. To get more context on where and how this is defined, see: Solution Registry.

The last part of this document describes how to implement new types of transformations. This is targeted at implementers only.

Declaring a transformation for a solution

As mentioned above, transformation rules for solution settings are declared along with the solutions in the settingsHandler section of the Solution Registry. The general format of this block of a solution declaration in object (hash). The key of the hash is a setting that the application understands and the value should describe how to set that value.

In it's simplest form (without any transformation), it could look something like this:

capabilitiesTransformation: {
    "Magnification": "display.screenEnhancement.magnification"
}

Which would mean that the setting Magnification (which the application needs and understands) should take the value set by the user for the common term "display.screenEnhancement.magnification". Implied in the above declaration is that the unit and range for both Magnification and "display.screenEnhancement.magnification" is the same (eg. magnification in percent).

Another example would be:

"Magnification": {
   "transform": {
      "type": "fluid.transforms.scaleValue",
      "inputPath": "display.screenEnhancement.magnification"
      "outputPath": "value",
      "factor": 100
   }
}

Here, a proper transformation will take place. The user preference value for the common term "display.screenEnhancement.magnification" will be scaled by a 100 before being assigned to the "Magnification" application setting. This would be relevant if the common term was specified as a factor and the application only understands Magnification as a percentage magnification.

Before diving into the available transformations, a few words about the general structure of transformations.

The general structure of transformations

Transformations will always have the keyword "expander", which tells the system that it needs to do a transformation. The "expander" block will be replaced by the value of the transformation result, except for the special case where outputPath is declared. Each expander will have a type, describing what type of transformation is being declared. The "type" field is mandatory. inputPath refers to the preference of the users needs and preferences set that should be transformed. This is also mandatory. Depending on the type of transformation, several other parameters may be required - see the individual transformation type details below. Transformations can also take an optional outputPath key. When using this, the value of the transformation will be assigned to a key by that name, rather than the key of the object containing the transformation.

"applicationSettingFoo": {
   "transform": {
       "type": "type.of.transformation",
       "inputPath": "preference.from.np.set",
       "outputPath": "optional-key",
       "transformationParam1": "foo",
       "transformationParam2": "bar"
       (...)
    }
}

In the below example the key applicationSettingFoo would be a setting the application understand. After the transformation the value of this key will become an object containing the key "optional-key" (from outputPath), with value given in inputPath ("preference.from.np.set") transformed as declared in the type using the parameters transformationParam1 and transformationParam2. Resulting in:

"applicationSettingFoo": {
    "optional-key": "transformed value of the preference preference.from.np.set"
}

If no outputPath key had been present, the applicationSettingFoo would get the output of the transformation assigned directly:

"applicationSettingFoo": "transformed value of the preference preference.from.np.set"

Available Transformations

Complete documentation of available transformation functions, along with more details of how to use it can be found on the page Architecture - Available transformation functions.

Wiki Categories