Class MappingConverter

java.lang.Object
org.openehealth.ipf.commons.map.MappingConverter
public class MappingConverter extends Object
Converts a mapping source from any format a MappingLoader on the classpath can read into any format a MappingWriter on the classpath can produce. In practice that means migrating a legacy Groovy .map script to *.mapping.xml or *.mapping.yaml.

The conversion is a starting point, not a finished file, and it says so: every judgement it had to make comes back as a warning naming the mapping.

  • Fallback closures. A closure has no declarative equivalent, so the converter probes it: one that returns its argument for every probe becomes Unmatched.Identity, one that returns the same constant for every probe becomes Unmatched.Fixed, and anything else becomes an Unmatched.Computed reference to a function named TODO-<mapping>, with a warning. Across all mapping files shipped with IPF that last case occurs once. The probe is a heuristic - a closure that behaves like the identity on the probes but not on some other input would be simplified wrongly - which is the reason the output is meant to be read before it is committed.
  • Reverse collisions. Where several keys map onto one value the Groovy service silently made the last one the inverse. The converter reproduces that, marking the others wider, and warns so that the canonical inverse can be chosen deliberately.
  • Composite values. The ~ convention of the Groovy DSL is gone. Values containing ~ are written verbatim; the loader reports each such mapping, which wants splitting by hand.
  • Typed mappings. A script may map objects - enum constants, numbers - where the model holds strings, so their string form is all that is converted. The loader reports each such mapping; it cannot be expressed in any of the formats and wants rewriting in Java, because the calling code relied on getting the objects back.
  • Comments. A .map file is evaluated, not parsed, so its comments do not survive into the loaded model. Several of them record the HL7 table a code came from and are worth copying over by hand.
Since:
6.0

  • Constructor Details

    • MappingConverter

      public MappingConverter()

  • Method Details

    • read

      public MappingConverter.Conversion read(URL source)
      Reads a mapping source and normalizes it so that it can be expressed declaratively, without writing anything.

    • read

      public MappingConverter.Conversion read(URL source, String sourceFormat)
      Reads a mapping source whose format is named explicitly rather than left to its file extension.
      Parameters:
      sourceFormat - a format id, or null to dispatch by file extension

    • render

      public String render(List<? extends Mapping> mappings, String target)
      Renders mappings in a target format, named either by its format id or by the file extension it produces.
      Parameters:
      mappings - the mappings to render
      target - xml or .mapping.xml - both select the same writer
      Throws:
      IllegalArgumentException - if no writer on the classpath produces that format

    • convert

      public MappingConverter.Conversion convert(Path source, Path targetDirectory, String targetFormat)
      Converts one source file and writes the result next to it, or into targetDirectory if one is given.
      Parameters:
      source - the mapping source to read
      targetDirectory - where to write, or null for next to the source
      targetFormat - the target format, named by its id or by the file extension it produces
      Returns:
      the conversion, whose warnings are worth reading; the written file is the source's name up to its first dot, plus the target format's extension

    • convert

      public MappingConverter.Conversion convert(Path source, String sourceFormat, Path targetDirectory, String targetFormat)
      Converts one source file, reading it in a format named explicitly.
      Parameters:
      sourceFormat - a format id, or null to dispatch by file extension
      See Also:

    • main

      public static void main(String[] args) throws IOException
      Converts mapping files from the command line, for the one-off migration of a source tree. 
      java -cp ... org.openehealth.ipf.commons.map.MappingConverter [-f <format>] [--from <format>] <output-dir|-> <file-or-dir>...
      -f names the target format, by its id (xml, yaml) or by the file extension it produces, and defaults to .mapping.xml; --from names the format the sources are read in, for files whose extension does not identify one, and defaults to dispatching per file by extension; - as the output directory writes each result next to its source. A directory argument is searched for anything a loader on the classpath can read - or, with --from, for every file in it - so which formats can be converted from and to is decided by which modules are on the classpath: ipf-commons-map-groovy to read .map, ipf-commons-map-xml and ipf-commons-map-yaml to write.
      Throws:
      IOException