Configuration

The module assumes a file called "units.json" placed under the core "conf" directory. You can find several examples under the project test/resources folder.

This is the example we will use through this tutorial:

{
  "units" : {
      "capacity": {
        "unit": "lt"
      },
      "voltage": {
        "unit": "v",
        "variants": {
          "v": ["volt","volts"]
        },
        "boost": 1.3
      },
      "wattage": {
        "unit": "w",
        "variants": {
          "w": ["watt","watts"]
        },
        "gap": {
          "value": 10,
          "mode": "PIVOT"
        },
        "boost": 1.3
      },
      "height": {
        "unit": "cm",
        "variants": {
          "cm": ["centimeters"]
        },
        "gap": {
          "value": 10,
          "mode": "PIVOT"
        }
      },
      "price_min_with_value": {
        "unit": "euro",
        "gap": {
          "value": 10,
          "mode": "MIN"
        }
      },
      "price_max_with_value": {
        "unit": "dollars",
        "gap": {
          "value": 50,
          "mode": "MAX"
        }
      },
      "price_min_without_value": {
        "unit": "francs",
        "gap": {
          "mode": "MIN"
        }
      },
      "price_max_without_value": {
        "unit": "cad",
        "gap": {
          "mode": "MAX"
        }
      }
  },
  "equivalence.table": {
      "cm" : {
        "mm" : 10,
        "m" : 0.01
      },
      "lt" : {
        "cl": 100,
        "ml": 1000
      }
  },
  "assumption.table": {
    "lt": [[0.25,0.50],[0.50,0.75]],
    "cl": [[250,1000]],
    "m": [[1.5,3]],
    "cm": [[1500,3000]],
    "default" : "volt"
  }
}

as you can see, the main section is defined under the "units" attribute. Within this section we have to define all the units (and the corresponding configuration) we want to enable in our Solr instance. Each unit includes the following attributes:

      "price": {
        "unit": "usd",
        "variants": {
          "usd": ["dollar","$","dollars"]
        },
        "gap": {
          "value": 50,
          "mode": "PIVOT"
        },
        "boost": 1.3
      }

The following table describes the constituent parts of a unit, following the example above:

Attribute	Description
"price"	This is not actually an attribute, instead it is the field name (price, in the example) within the Solr schema.
unit	A reference name for the unit. We could call it the "preferred" unit form.
variants	A set of objects where we can declare the different forms of a given unit. The content of the attribute is an object where keys are reference names and values are list of variants forms.
gap	A gap, when declared, enables range querying amount quantities. A gap has a mode (PIVOT, MIN, MAX) and a value, which is required only in case of PIVOT gaps.
boost	An optional boost associated to the unit

The other top level section is called "equivalence.table" and contains the equivalence rules between units. The example above reports two different families of rules. As you can see it's possibile to define, for each unit, all the equivalent units with the corresponding conversion factor. For example:

 "cm" : {
      "mm" : 10,
      "m" : 0.01
  }

means that a cm (which is the reference name for that unit, see the "units" section) can be converted

• in millimeters using a conversion factor of 10
• in meters using a conversion factor of 0.01

The last section is called "assumption.table", it is optional and it is used in those cases when "orphan" amounts are detected (i.e. amounts without a following unit).

 "assumption.table": {
    "lt": [[0.25,0.50],[0.50,0.75]],
    "cl": [[250,1000]],
    "m": [[1.5,3]],
    "cm": [[1500,3000]],
    "default" : "volt"
  }

In this section, we can configure a default rule (i.e. the default unit that will be applied to orphan amounts) and a set of unit - ranges pairs that will be used for guessing the unit depending on the amount value.